Add audio encryption/decryption utilities

encryption.go

@@ -0,0 +1,204 @@
+package lksdk
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"crypto/sha256"
+	"errors"
+	"io"
+
+	"golang.org/x/crypto/hkdf"
+	"golang.org/x/crypto/pbkdf2"
+)
+
+const (
+	LIVEKIT_SDK_SALT         = "LKFrameEncryptionKey"
+	LIVEKIT_IV_LENGTH        = 12
+	LIVEKIT_PBKDF_ITERATIONS = 100000
+	LIVEKIT_KEY_SIZE_BYTES   = 16
+	LIVEKIT_HKDF_INFO_BYTES  = 128
+	unencrypted_audio_bytes  = 1
+)
+
+var ErrIncorrectKeyLength = errors.New("incorrect key length for encryption/decryption")
+var ErrUnableGenerateIV = errors.New("unable to generate iv for encryption")
+var ErrIncorrectIVLength = errors.New("incorrect iv length")
+var ErrIncorrectSecretLength = errors.New("input secret provided to derivation function cannot be empty or nil")
+var ErrIncorrectSaltLength = errors.New("input salt provided to derivation function cannot be empty or nil")
+
+func DeriveKeyFromString(password string) ([]byte, error) {
+	return DeriveKeyFromStringCustomSalt(password, LIVEKIT_SDK_SALT)
+}
+
+func DeriveKeyFromStringCustomSalt(password, salt string) ([]byte, error) {
+
+	if password == "" {
+		return nil, ErrIncorrectSecretLength
+	}
+	if salt == "" {
+		return nil, ErrIncorrectSaltLength
+	}
+
+	encPassword := []byte(password)
+	encSalt := []byte(salt)
+
+	return pbkdf2.Key(encPassword, encSalt, LIVEKIT_PBKDF_ITERATIONS, LIVEKIT_KEY_SIZE_BYTES, sha256.New), nil
+
+}
+
+func DeriveKeyFromBytes(secret []byte) ([]byte, error) {
+	return DeriveKeyFromBytesCustomSalt(secret, LIVEKIT_SDK_SALT)
+}
+
+func DeriveKeyFromBytesCustomSalt(secret []byte, salt string) ([]byte, error) {
+
+	info := make([]byte, LIVEKIT_HKDF_INFO_BYTES)
+	encSalt := []byte(salt)
+
+	if secret == nil {
+		return nil, ErrIncorrectSecretLength
+	}
+	if salt == "" {
+		return nil, ErrIncorrectSaltLength
+	}
+
+	hkdfReader := hkdf.New(sha256.New, secret, encSalt, info)
+
+	key := make([]byte, LIVEKIT_KEY_SIZE_BYTES)
+	_, err := io.ReadFull(hkdfReader, key)
+	if err != nil {
+		return nil, err
+	}
+
+	return key, nil
+
+}
+
+// Take audio sample (body of RTP) encrypted by LiveKit client SDK, extract IV and decrypt using provided key
+// Encrypted sample format based on livekit client sdk
+// ---------+-------------------------+---------+----
+// payload  |IV...(length = IV_LENGTH)|IV_LENGTH|KID|
+// ---------+-------------------------+---------+----
+// First byte of audio frame is not encrypted and only authenticated
+// payload - variable bytes
+// IV - variable bytes (equal to IV_LENGTH bytes)
+// IV_LENGTH - 1 byte
+// KID (Key ID) - 1 byte - ignored here, key is provided as parameter to function
+func DecryptGCMAudioSample(sample, key, sifTrailer []byte) ([]byte, error) {
+
+	if len(key) != 16 {
+		return nil, ErrIncorrectKeyLength
+	}
+
+	if sifTrailer != nil && len(sample) >= len(sifTrailer) {
+		possibleTrailer := sample[len(sample)-len(sifTrailer):]
+		if bytes.Equal(possibleTrailer, sifTrailer) {
+			// this is unencrypted Server Injected Frame (SIF) thas should be dropped
+			return nil, nil
+		}
+
+	}
+
+	// variable naming is kept close to LiveKit client SDK decrypt function
+	// https://github.com/livekit/client-sdk-js/blob/main/src/e2ee/worker/FrameCryptor.ts#L402
+
+	frameHeader := sample[:unencrypted_audio_bytes] // first unencrypted bytes are "frameHeader" and used for authentication later
+	frameTrailer := sample[len(sample)-2:]          // last 2 bytes having IV_LENGTH and KID (1 byte each)
+	ivLength := int(frameTrailer[0])                // single byte, Endianness doesn't matter
+	ivStart := len(sample) - len(frameTrailer) - ivLength
+	if ivStart < 0 {
+		return nil, ErrIncorrectIVLength
+	}
+
+	iv := make([]byte, ivLength)
+	copy(iv, sample[ivStart:ivStart+ivLength]) // copy IV value out of sample into iv
+
+	cipherTextStart := len(frameHeader)
+	cipherTextLength := len(sample) - len(frameTrailer) - ivLength - len(frameHeader)
+	cipherText := make([]byte, cipherTextLength)
+	copy(cipherText, sample[cipherTextStart:cipherTextStart+cipherTextLength])
+
+	// setup AES
+	aesCipher, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+
+	aesGCM, err := cipher.NewGCMWithNonceSize(aesCipher, ivLength) // standard Nonce size is 12 bytes, but since it MAY be different in the sample, we use the one from the sample
+	if err != nil {
+		return nil, err
+	}
+
+	// fmt.Println("**** DECRYPTION BEGIN ********")
+	plainText, err := aesGCM.Open(nil, iv, cipherText, frameHeader)
+	if err != nil {
+		return nil, err
+	}
+
+	newData := make([]byte, len(frameHeader)+len(plainText)) // allocate space for final packet
+
+	_ = copy(newData[0:], frameHeader)              // put unencrypted frameHeader first
+	_ = copy(newData[len(frameHeader):], plainText) // add decrypted remaining value
+
+	return newData, nil
+
+}
+
+// Take audio sample (body of RTP) and encrypts it using AES-GCM 128bit with provided key
+// Encrypted sample format based on livekit client sdk
+// ---------+-------------------------+---------+----
+// payload  |IV...(length = IV_LENGTH)|IV_LENGTH|KID|
+// ---------+-------------------------+---------+----
+// First byte of audio frame is not encrypted and only authenticated
+// payload - variable bytes
+// IV - variable bytes (equal to IV_LENGTH bytes) - 12 random bytes
+// IV_LENGTH - 1 byte - 12 bytes fixed
+// KID (Key ID) - 1 byte - taken from "kid" parameter
+func EncryptGCMAudioSample(sample, key []byte, kid uint8) ([]byte, error) {
+
+	if len(key) != 16 {
+		return nil, ErrIncorrectKeyLength
+	}
+
+	// variable naming is kept close to LiveKit client SDK decrypt function
+	// https://github.com/livekit/client-sdk-js/blob/main/src/e2ee/worker/FrameCryptor.ts#L402
+
+	frameHeader := append(make([]byte, 0), sample[:unencrypted_audio_bytes]...) // first unencrypted bytes are "frameHeader" and used for authentication later
+	iv := make([]byte, LIVEKIT_IV_LENGTH)
+	_, err := rand.Read(iv)
+	if err != nil {
+		return nil, errors.Join(ErrUnableGenerateIV, err)
+	}
+
+	frameTrailer := []byte{LIVEKIT_IV_LENGTH, kid} // last 2 bytes having IV_LENGTH and KID (1 byte each)
+
+	plainTextStart := len(frameHeader)
+	plainTextLength := len(sample) - len(frameHeader)
+	plainText := make([]byte, plainTextLength)
+	copy(plainText, sample[plainTextStart:plainTextStart+plainTextLength])
+
+	// setup AES
+	aesCipher, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+
+	aesGCM, err := cipher.NewGCMWithNonceSize(aesCipher, LIVEKIT_IV_LENGTH) // standard Nonce size is 12 bytes, but using one from defined constant (which matches Javascript SDK)
+	if err != nil {
+		return nil, err
+	}
+
+	cipherText := aesGCM.Seal(nil, iv, plainText, frameHeader)
+
+	newData := make([]byte, len(frameHeader)+len(cipherText)+len(iv)+len(frameTrailer)) // allocate space for final packet
+
+	_ = copy(newData[0:], frameHeader)                                         // put unencrypted frameHeader first
+	_ = copy(newData[len(frameHeader):], cipherText)                           // add cipherText
+	_ = copy(newData[len(frameHeader)+len(cipherText):], iv)                   // add iv
+	_ = copy(newData[len(frameHeader)+len(cipherText)+len(iv):], frameTrailer) // add trailer
+
+	return newData, nil
+
+}

encryption_test.go

@@ -0,0 +1,80 @@
+package lksdk
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+var opusEncryptedFrame = []byte{120, 145, 24, 159, 76, 65, 130, 48, 144, 249, 17, 112, 134, 78, 250, 129, 171, 194, 16, 173, 73, 196, 5, 152, 69, 225, 28, 210, 196, 241, 226, 139, 231, 172, 51, 38, 139, 179, 245, 182, 170, 8, 122, 117, 98, 144, 123, 95, 73, 89, 119, 39, 205, 20, 191, 55, 121, 59, 239, 192, 85, 224, 228, 143, 10, 113, 195, 223, 118, 42, 2, 32, 22, 17, 77, 227, 109, 160, 245, 202, 189, 63, 162, 164, 5, 241, 24, 151, 45, 42, 165, 131, 171, 243, 141, 53, 35, 131, 141, 52, 253, 188, 12, 0}
+var opusDecryptedFrame = []byte{120, 11, 109, 82, 113, 132, 189, 156, 220, 173, 30, 109, 87, 54, 173, 99, 26, 126, 166, 37, 127, 234, 110, 211, 230, 152, 181, 235, 197, 19, 140, 230, 179, 35, 131, 132, 29, 192, 97, 247, 108, 53, 183, 214, 77, 181, 173, 206, 175, 7, 228, 145, 93, 155, 155, 142, 14, 27, 111, 64, 96, 196, 229, 189, 142, 59, 149, 169, 99, 225, 216, 85, 186, 182}
+var opusSilenceFrame = []byte{0xf8, 0xff, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}
+var sifTrailer = []byte{50, 86, 10, 220, 108, 185, 57, 211}
+var testPassphrase = "12345"
+
+func TestDeriveKeyFromString(t *testing.T) {
+
+	password := "12345"
+
+	key, err := DeriveKeyFromString(password)
+	expectedKey := []byte{15, 94, 198, 66, 93, 211, 116, 46, 55, 97, 232, 121, 189, 233, 224, 22}
+
+	assert.Nil(t, err)
+	assert.Equal(t, key, expectedKey)
+}
+
+func TestDeriveKeyFromBytes(t *testing.T) {
+
+	inputSecret := []byte{34, 21, 187, 202, 134, 204, 168, 62, 5, 105, 40, 244, 88}
+	expectedKey := []byte{129, 224, 93, 62, 17, 203, 99, 136, 101, 35, 149, 128, 189, 152, 251, 76}
+
+	key, err := DeriveKeyFromBytes(inputSecret)
+	assert.Nil(t, err)
+	assert.Equal(t, expectedKey, key)
+
+}
+
+func TestDecryptAudioSample(t *testing.T) {
+
+	key, err := DeriveKeyFromString(testPassphrase)
+	assert.Nil(t, err)
+
+	decryptedFrame, err := DecryptGCMAudioSample(opusEncryptedFrame, key, sifTrailer)
+
+	assert.Nil(t, err)
+	assert.Equal(t, opusDecryptedFrame, decryptedFrame)
+
+	var sifFrame []byte
+	sifFrame = append(sifFrame, opusSilenceFrame...)
+	sifFrame = append(sifFrame, sifTrailer...)
+
+	decryptedFrame, err = DecryptGCMAudioSample(sifFrame, key, sifTrailer)
+	assert.Nil(t, err)
+	assert.Nil(t, decryptedFrame)
+
+}
+
+func TestEncryptAudioSample(t *testing.T) {
+
+	key, err := DeriveKeyFromString(testPassphrase)
+	assert.Nil(t, err)
+
+	encryptedFrame, err := EncryptGCMAudioSample(opusDecryptedFrame, key, 0)
+
+	assert.Nil(t, err)
+
+	// IV is generated randomly so to verify we decrypt and make sure that we got the expected plain text frame
+	decryptedFrame, err := DecryptGCMAudioSample(encryptedFrame, key, sifTrailer)
+	assert.Nil(t, err)
+	assert.Equal(t, opusDecryptedFrame, decryptedFrame)
+
+}

go.mod

@@ -20,6 +20,7 @@ require (
 	github.com/stretchr/testify v1.9.0
 	github.com/twitchtv/twirp v8.1.3+incompatible
 	go.uber.org/atomic v1.11.0
+	golang.org/x/crypto v0.30.0
 	golang.org/x/exp v0.0.0-20241108190413-2d47ceb2692f
 	google.golang.org/protobuf v1.35.2
 )
@@ -66,13 +67,12 @@ require (
 	go.uber.org/multierr v1.11.0 // indirect
 	go.uber.org/zap v1.27.0 // indirect
 	go.uber.org/zap/exp v0.3.0 // indirect
-	golang.org/x/crypto v0.25.0 // indirect
-	golang.org/x/net v0.27.0 // indirect
-	golang.org/x/sync v0.9.0 // indirect
-	golang.org/x/sys v0.22.0 // indirect
-	golang.org/x/text v0.16.0 // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20240528184218-531527333157 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20240725223205-93522f1f2a9f // indirect
-	google.golang.org/grpc v1.65.0 // indirect
+	golang.org/x/net v0.31.0 // indirect
+	golang.org/x/sync v0.10.0 // indirect
+	golang.org/x/sys v0.28.0 // indirect
+	golang.org/x/text v0.21.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20240903143218-8af14fe29dc1 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20240903143218-8af14fe29dc1 // indirect
+	google.golang.org/grpc v1.68.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )