task(e2ee): switch back to GCM

doc/e2ee.md

@@ -39,28 +39,41 @@ the set of keys when we find a valid signature which avoids a denial of service
 
 We are using a variant of [SFrame](https://tools.ietf.org/html/draft-omara-sframe-00)
 that uses a trailer instead of a header. We call it JFrame.
+`
+These transformations use AES-GCM (with a 128 bit key; we could have used
+256 bits but since the keys are short-lived decided against it) and the
+webcrypto API:
+  https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt
+
+AES-GCM needs a 96 bit initialization vector which we construct
+based on the SSRC, the rtp timestamp and a frame counter which is similar to
+how the IV is constructed in SRTP with GCM
+  https://tools.ietf.org/html/rfc7714#section-8.1
+
+This IV gets sent along with the packet, adding 12 bytes of overhead. The GCM
+tag length is the default 128 bits or 16 bytes. For video this overhead is ok but
+for audio (where the opus frames are much, much smaller) we are considering shorter
+authentication tags.
 
 At a high level the encrypted frame format looks like this:
 ```
-     +------------+------------------------------------------+^+
-     |unencrypted payload header (variable length)           | |
-   +^+------------+------------------------------------------+ |
-   | |                                                       | |
-   | |                                                       | |
-   | |                                                       | |
-   | |                                                       | |
-   | |                  Encrypted Frame                      | |
-   | |                                                       | |
-   | |                                                       | |
-   | |                                                       | |
-   | |                                                       | |
-   +^+-------------------------------------------------------+ +
-   | |                 Authentication Tag                    | |
-   | +---------------------------------------+-+-+-+-+-+-+-+-+ |
-   | |    CTR... (length=LEN + 1)            |R|LEN  |KID    | |
-   | +---------------------------------------+-+-+-+-+-+-+-+-+^|
-   |                                                           |
-   +----+Encrypted Portion            Authenticated Portion+---+
+     +------------+--------------------------------------+^+
+     |unencrypted payload header (variable length)       | |
+   +^+------------+--------------------------------------+ |
+   | |                                                   | |
+   | |                                                   | |
+   | |                                                   | |
+   | |                                                   | |
+   | |              Encrypted Frame                      | |
+   | |                                                   | |
+   | |                                                   | |
+   | |                                                   | |
+   | |                                                   | |
+   | | ---------+-------------------------+-+---------+----
+   | | payload  |IV...(length = IV_LENGTH)|R|IV_LENGTH|KID |
+   | | ---------+-------------------------+-+---------+----
+   |                                                       |
+   +--+Encrypted Portion        Authenticated Portion+---+
 ```
 
 We do not encrypt the first few bytes of the packet that form the

modules/e2ee/Context.js

@@ -2,7 +2,6 @@
 /* global BigInt */
 
 import { deriveKeys, importKey, ratchet } from './crypto-utils';
-import { isArrayEqual } from './utils';
 
 // We use a ringbuffer of keys so we can change them and still decode packets that were
 // encrypted with an old key. We use a size of 16 which corresponds to the four bits
@@ -24,26 +23,12 @@ const UNENCRYPTED_BYTES = {
     delta: 3,
     undefined: 1 // frame.type is not set on audio
 };
+const ENCRYPTION_ALGORITHM = 'AES-GCM';
 
-// Use truncated SHA-256 hashes, 80 bіts for video, 32 bits for audio.
-// This follows the same principles as DTLS-SRTP.
-const AUTHENTICATIONTAG_OPTIONS = {
-    name: 'HMAC',
-    hash: 'SHA-256'
-};
-const ENCRYPTION_ALGORITHM = 'AES-CTR';
-
-// https://developer.mozilla.org/en-US/docs/Web/API/AesCtrParams
-const CTR_LENGTH = 64;
-
-const DIGEST_LENGTH = {
-    key: 10,
-    delta: 10,
-    undefined: 4 // frame.type is not set on audio
-};
+/* We use a 96 bit IV for AES GCM. This is signalled in plain together with the
+ packet. See https://developer.mozilla.org/en-US/docs/Web/API/AesGcmParams */
+const IV_LENGTH = 12;
 
-// Maximum number of forward ratchets to attempt when the authentication
-// tag on a remote packet does not match the current key.
 const RATCHET_WINDOW_SIZE = 8;
 
 /**
@@ -61,10 +46,7 @@ export class Context {
         // A pointer to the currently used key.
         this._currentKeyIndex = -1;
 
-        // A per-sender counter that is used create the AES CTR.
-        // Must be incremented on every frame that is sent, can be reset on
-        // key changes.
-        this._sendCount = BigInt(0); // eslint-disable-line new-cap
+        this._sendCounts = new Map();
 
         this._id = id;
     }
@@ -111,96 +93,68 @@ export class Context {
      * @param {RTCEncodedVideoFrame|RTCEncodedAudioFrame} encodedFrame - Encoded video frame.
      * @param {TransformStreamDefaultController} controller - TransportStreamController.
      *
-     * The packet format is a variant of
-     *   https://tools.ietf.org/html/draft-omara-sframe-00
-     * using a trailer instead of a header. One of the design goals was to not require
-     * changes to the SFU which for video requires not encrypting the keyframe bit of VP8
-     * as SFUs need to detect a keyframe (framemarking or the generic frame descriptor will
-     * solve this eventually). This also "hides" that a client is using E2EE a bit.
-     *
-     * Note that this operates on the full frame, i.e. for VP8 the data described in
-     *   https://tools.ietf.org/html/rfc6386#section-9.1
-     *
      * The VP8 payload descriptor described in
-     *   https://tools.ietf.org/html/rfc7741#section-4.2
-     * is part of the RTP packet and not part of the encoded frame and is therefore not
-     * controllable by us. This is fine as the SFU keeps having access to it for routing.
+     * https://tools.ietf.org/html/rfc7741#section-4.2
+     * is part of the RTP packet and not part of the frame and is not controllable by us.
+     * This is fine as the SFU keeps having access to it for routing.
+     *
+     * The encrypted frame is formed as follows:
+     * 1) Leave the first (10, 3, 1) bytes unencrypted, depending on the frame type and kind.
+     * 2) Form the GCM IV for the frame as described above.
+     * 3) Encrypt the rest of the frame using AES-GCM.
+     * 4) Allocate space for the encrypted frame.
+     * 5) Copy the unencrypted bytes to the start of the encrypted frame.
+     * 6) Append the ciphertext to the encrypted frame.
+     * 7) Append the IV.
+     * 8) Append a single byte for the key identifier.
+     * 9) Enqueue the encrypted frame for sending.
      */
     encodeFunction(encodedFrame, controller) {
         const keyIndex = this._currentKeyIndex;
 
         if (this._cryptoKeyRing[keyIndex]) {
-            this._sendCount++;
+            const iv = this._makeIV(encodedFrame.getMetadata().synchronizationSource, encodedFrame.timestamp);
 
             // Thіs is not encrypted and contains the VP8 payload descriptor or the Opus TOC byte.
             const frameHeader = new Uint8Array(encodedFrame.data, 0, UNENCRYPTED_BYTES[encodedFrame.type]);
 
+            // Frame trailer contains the R|IV_LENGTH and key index
+            const frameTrailer = new Uint8Array(2);
+
+            frameTrailer[0] = IV_LENGTH;
+            frameTrailer[1] = keyIndex;
+
             // Construct frame trailer. Similar to the frame header described in
             // https://tools.ietf.org/html/draft-omara-sframe-00#section-4.2
             // but we put it at the end.
-            //                                             0 1 2 3 4 5 6 7
-            // ---------+---------------------------------+-+-+-+-+-+-+-+-+
-            // payload  |    CTR... (length=LEN)          |S|LEN  |KID    |
-            // ---------+---------------------------------+-+-+-+-+-+-+-+-+
-            const counter = new Uint8Array(16);
-            const counterView = new DataView(counter.buffer);
-
-            // The counter is encoded as a variable-length field.
-            counterView.setBigUint64(8, this._sendCount);
-            let counterLength = 8;
-
-            for (let i = 8; i < counter.byteLength; i++ && counterLength--) {
-                if (counterView.getUint8(i) !== 0) {
-                    break;
-                }
-            }
-
-            const frameTrailer = new Uint8Array(counterLength + 1);
-
-            frameTrailer.set(new Uint8Array(counter.buffer, counter.byteLength - counterLength));
-
-            // Since we never send a counter of 0 we send counterLength - 1 on the wire.
-            // This is different from the sframe draft, increases the key space and lets us
-            // ignore the case of a zero-length counter at the receiver.
-            frameTrailer[frameTrailer.byteLength - 1] = keyIndex | ((counterLength - 1) << 4);
-
-            // XOR the counter with the saltKey to construct the AES CTR.
-            const saltKey = new DataView(this._cryptoKeyRing[keyIndex].saltKey);
-
-            for (let i = 0; i < counter.byteLength; i++) {
-                counterView.setUint8(i, counterView.getUint8(i) ^ saltKey.getUint8(i));
-            }
+            //
+            // ---------+-------------------------+-+---------+----
+            // payload  |IV...(length = IV_LENGTH)|R|IV_LENGTH|KID |
+            // ---------+-------------------------+-+---------+----
 
             return crypto.subtle.encrypt({
                 name: ENCRYPTION_ALGORITHM,
-                counter,
-                length: CTR_LENGTH
+                iv,
+                additionalData: new Uint8Array(encodedFrame.data, 0, frameHeader.byteLength)
             }, this._cryptoKeyRing[keyIndex].encryptionKey, new Uint8Array(encodedFrame.data,
                 UNENCRYPTED_BYTES[encodedFrame.type]))
             .then(cipherText => {
                 const newData = new ArrayBuffer(frameHeader.byteLength + cipherText.byteLength
-                    + DIGEST_LENGTH[encodedFrame.type] + frameTrailer.byteLength);
+                    + iv.byteLength + frameTrailer.byteLength);
                 const newUint8 = new Uint8Array(newData);
 
                 newUint8.set(frameHeader); // copy first bytes.
-                newUint8.set(new Uint8Array(cipherText), UNENCRYPTED_BYTES[encodedFrame.type]); // add ciphertext.
-                // Leave some space for the authentication tag. This is filled with 0s initially, similar to
-                // STUN message-integrity described in https://tools.ietf.org/html/rfc5389#section-15.4
-                newUint8.set(frameTrailer, frameHeader.byteLength + cipherText.byteLength
-                    + DIGEST_LENGTH[encodedFrame.type]); // append trailer.
-
-                return crypto.subtle.sign(AUTHENTICATIONTAG_OPTIONS, this._cryptoKeyRing[keyIndex].authenticationKey,
-                    new Uint8Array(newData)).then(async authTag => {
-                    const truncatedAuthTag = new Uint8Array(authTag, 0, DIGEST_LENGTH[encodedFrame.type]);
-
+                newUint8.set(
+                    new Uint8Array(cipherText), frameHeader.byteLength); // add ciphertext.
+                newUint8.set(
+                    new Uint8Array(iv), frameHeader.byteLength + cipherText.byteLength); // append IV.
+                newUint8.set(
+                        frameTrailer,
+                        frameHeader.byteLength + cipherText.byteLength + iv.byteLength); // append frame trailer.
 
-                    // Set the truncated authentication tag.
-                    newUint8.set(truncatedAuthTag, UNENCRYPTED_BYTES[encodedFrame.type] + cipherText.byteLength);
-
-                    encodedFrame.data = newData;
+                encodedFrame.data = newData;
 
-                    return controller.enqueue(encodedFrame);
-                });
+                return controller.enqueue(encodedFrame);
             }, e => {
                 // TODO: surface this to the app.
                 console.error(e);
@@ -224,109 +178,147 @@ export class Context {
      */
     async decodeFunction(encodedFrame, controller) {
         const data = new Uint8Array(encodedFrame.data);
-        const keyIndex = data[encodedFrame.data.byteLength - 1] & 0xf; // lower four bits.
+        const keyIndex = data[encodedFrame.data.byteLength - 1];
+
+        if (this._cryptoKeyRing[keyIndex]) {
+
+            const decodedFrame = await this._decryptFrame(
+                encodedFrame,
+                keyIndex);
+
+            return controller.enqueue(decodedFrame);
+        }
+
+        // TODO: this just passes through to the decoder. Is that ok? If we don't know the key yet
+        // we might want to buffer a bit but it is still unclear how to do that (and for how long etc).
+        controller.enqueue(encodedFrame);
+    }
 
-        if (this._cryptoKeyRing[this._currentKeyIndex] && this._cryptoKeyRing[keyIndex]) {
-            const counterLength = 1 + ((data[encodedFrame.data.byteLength - 1] >> 4) & 0x7);
+    /**
+     * Function that will decrypt the given encoded frame. If the decryption fails, it will
+     * ratchet the key for up to RATCHET_WINDOW_SIZE times.
+     *
+     * @param {RTCEncodedVideoFrame|RTCEncodedAudioFrame} encodedFrame - Encoded video frame.
+     * @param {number} keyIndex - the index of the decryption data in _cryptoKeyRing array.
+     * @param {number} ratchetCount - the number of retries after ratcheting the key.
+     * @returns {RTCEncodedVideoFrame|RTCEncodedAudioFrame} - The decrypted frame.
+     * @private
+     */
+    async _decryptFrame(
+            encodedFrame,
+            keyIndex,
+            ratchetCount = 0) {
+
+        const { encryptionKey } = this._cryptoKeyRing[keyIndex];
+        let { material } = this._cryptoKeyRing[keyIndex];
+
+        // Construct frame trailer. Similar to the frame header described in
+        // https://tools.ietf.org/html/draft-omara-sframe-00#section-4.2
+        // but we put it at the end.
+        //
+        // ---------+-------------------------+-+---------+----
+        // payload  |IV...(length = IV_LENGTH)|R|IV_LENGTH|KID |
+        // ---------+-------------------------+-+---------+----
+
+        try {
             const frameHeader = new Uint8Array(encodedFrame.data, 0, UNENCRYPTED_BYTES[encodedFrame.type]);
+            const frameTrailer = new Uint8Array(encodedFrame.data, encodedFrame.data.byteLength - 2, 2);
 
-            // Extract the truncated authentication tag.
-            const authTagOffset = encodedFrame.data.byteLength - (DIGEST_LENGTH[encodedFrame.type]
-                + counterLength + 1);
-            const authTag = encodedFrame.data.slice(authTagOffset, authTagOffset
-                + DIGEST_LENGTH[encodedFrame.type]);
-
-            // Set authentication tag bytes to 0.
-            data.set(new Uint8Array(DIGEST_LENGTH[encodedFrame.type]), encodedFrame.data.byteLength
-                - (DIGEST_LENGTH[encodedFrame.type] + counterLength + 1));
-
-            // Do truncated hash comparison of the authentication tag.
-            // If the hash does not match we might have to advance the ratchet a limited number
-            // of times. See (even though the description there is odd)
-            // https://tools.ietf.org/html/draft-omara-sframe-00#section-4.3.5.1
-            let { authenticationKey, material } = this._cryptoKeyRing[keyIndex];
-            let validAuthTag = false;
-            let newKeys = null;
-
-            for (let distance = 0; distance < RATCHET_WINDOW_SIZE; distance++) {
-                const calculatedTag = await crypto.subtle.sign(AUTHENTICATIONTAG_OPTIONS,
-                    authenticationKey, encodedFrame.data);
-
-                if (isArrayEqual(new Uint8Array(authTag),
-                        new Uint8Array(calculatedTag.slice(0, DIGEST_LENGTH[encodedFrame.type])))) {
-                    validAuthTag = true;
-                    if (distance > 0) {
-                        this._setKeys(newKeys, keyIndex);
-                    }
-                    break;
-                }
-
-                // Attempt to ratchet and generate the next set of keys.
-                material = await importKey(await ratchet(material));
-                newKeys = await deriveKeys(material);
-                authenticationKey = newKeys.authenticationKey;
-            }
+            const ivLength = frameTrailer[0];
+            const iv = new Uint8Array(
+                encodedFrame.data,
+                encodedFrame.data.byteLength - ivLength - frameTrailer.byteLength,
+                ivLength);
 
-            // Check whether we found a valid authentication tag.
-            if (!validAuthTag) {
-                // TODO: return an error to the app.
+            const cipherTextStart = frameHeader.byteLength;
+            const cipherTextLength = encodedFrame.data.byteLength
+                    - (frameHeader.byteLength + ivLength + frameTrailer.byteLength);
 
-                console.error('Authentication tag mismatch');
+            const plainText = await crypto.subtle.decrypt({
+                name: 'AES-GCM',
+                iv,
+                additionalData: new Uint8Array(encodedFrame.data, 0, frameHeader.byteLength)
+            },
+                encryptionKey,
+                new Uint8Array(encodedFrame.data, cipherTextStart, cipherTextLength));
 
-                return;
-            }
+            const newData = new ArrayBuffer(frameHeader.byteLength + plainText.byteLength);
+            const newUint8 = new Uint8Array(newData);
+
+            newUint8.set(new Uint8Array(encodedFrame.data, 0, frameHeader.byteLength));
+            newUint8.set(new Uint8Array(plainText), frameHeader.byteLength);
 
-            // Extract the counter.
-            const counter = new Uint8Array(16);
+            encodedFrame.data = newData;
+        } catch (error) {
+            console.error(error);
+
+            if (ratchetCount < RATCHET_WINDOW_SIZE) {
+                material = await importKey(await ratchet(material));
 
-            counter.set(data.slice(encodedFrame.data.byteLength - (counterLength + 1),
-                encodedFrame.data.byteLength - 1), 16 - counterLength);
-            const counterView = new DataView(counter.buffer);
+                const newKey = await deriveKeys(material);
 
-            // XOR the counter with the saltKey to construct the AES CTR.
-            const saltKey = new DataView(this._cryptoKeyRing[keyIndex].saltKey);
+                this._setKeys(newKey);
 
-            for (let i = 0; i < counter.byteLength; i++) {
-                counterView.setUint8(i,
-                    counterView.getUint8(i) ^ saltKey.getUint8(i));
+                return await this._decryptFrame(
+                    encodedFrame,
+                    keyIndex,
+                    ratchetCount + 1);
             }
 
-            return crypto.subtle.decrypt({
-                name: ENCRYPTION_ALGORITHM,
-                counter,
-                length: CTR_LENGTH
-            }, this._cryptoKeyRing[keyIndex].encryptionKey, new Uint8Array(encodedFrame.data,
-                    UNENCRYPTED_BYTES[encodedFrame.type],
-                    encodedFrame.data.byteLength - (UNENCRYPTED_BYTES[encodedFrame.type]
-                    + DIGEST_LENGTH[encodedFrame.type] + counterLength + 1))
-            ).then(plainText => {
-                const newData = new ArrayBuffer(UNENCRYPTED_BYTES[encodedFrame.type] + plainText.byteLength);
+            // TODO: notify the application about error status.
+
+            // TODO: For video we need a better strategy since we do not want to based any
+            // non-error frames on a garbage keyframe.
+            if (encodedFrame.type === undefined) { // audio, replace with silence.
+                const newData = new ArrayBuffer(3);
                 const newUint8 = new Uint8Array(newData);
 
-                newUint8.set(frameHeader);
-                newUint8.set(new Uint8Array(plainText), UNENCRYPTED_BYTES[encodedFrame.type]);
+                newUint8.set([ 0xd8, 0xff, 0xfe ]); // opus silence frame.
                 encodedFrame.data = newData;
+            }
+        }
 
-                return controller.enqueue(encodedFrame);
-            }, e => {
-                console.error(e);
+        return encodedFrame;
+    }
 
-                // TODO: notify the application about error status.
-                // TODO: For video we need a better strategy since we do not want to based any
-                // non-error frames on a garbage keyframe.
-                if (encodedFrame.type === undefined) { // audio, replace with silence.
-                    const newData = new ArrayBuffer(3);
-                    const newUint8 = new Uint8Array(newData);
-
-                    newUint8.set([ 0xd8, 0xff, 0xfe ]); // opus silence frame.
-                    encodedFrame.data = newData;
-                    controller.enqueue(encodedFrame);
-                }
-            });
+
+    /**
+     * Construct the IV used for AES-GCM and sent (in plain) with the packet similar to
+     * https://tools.ietf.org/html/rfc7714#section-8.1
+     * It concatenates
+     * - the 32 bit synchronization source (SSRC) given on the encoded frame,
+     * - the 32 bit rtp timestamp given on the encoded frame,
+     * - a send counter that is specific to the SSRC. Starts at a random number.
+     * The send counter is essentially the pictureId but we currently have to implement this ourselves.
+     * There is no XOR with a salt. Note that this IV leaks the SSRC to the receiver but since this is
+     * randomly generated and SFUs may not rewrite this is considered acceptable.
+     * The SSRC is used to allow demultiplexing multiple streams with the same key, as described in
+     *   https://tools.ietf.org/html/rfc3711#section-4.1.1
+     * The RTP timestamp is 32 bits and advances by the codec clock rate (90khz for video, 48khz for
+     * opus audio) every second. For video it rolls over roughly every 13 hours.
+     * The send counter will advance at the frame rate (30fps for video, 50fps for 20ms opus audio)
+     * every second. It will take a long time to roll over.
+     *
+     * See also https://developer.mozilla.org/en-US/docs/Web/API/AesGcmParams
+     */
+    _makeIV(synchronizationSource, timestamp) {
+        const iv = new ArrayBuffer(IV_LENGTH);
+        const ivView = new DataView(iv);
+
+        // having to keep our own send count (similar to a picture id) is not ideal.
+        if (!this._sendCounts.has(synchronizationSource)) {
+            // Initialize with a random offset, similar to the RTP sequence number.
+            this._sendCounts.set(synchronizationSource, Math.floor(Math.random() * 0xFFFF));
         }
 
-        // TODO: this just passes through to the decoder. Is that ok? If we don't know the key yet
-        // we might want to buffer a bit but it is still unclear how to do that (and for how long etc).
-        controller.enqueue(encodedFrame);
+        const sendCount = this._sendCounts.get(synchronizationSource);
+
+        ivView.setUint32(0, synchronizationSource);
+        ivView.setUint32(4, timestamp);
+        ivView.setUint32(8, sendCount % 0xFFFF);
+
+        this._sendCounts.set(synchronizationSource, sendCount + 1);
+
+        return iv;
     }
 }

modules/e2ee/Context.spec.js

@@ -81,9 +81,9 @@ describe('E2EE Context', () => {
                 enqueue: encodedFrame => {
                     const data = new Uint8Array(encodedFrame.data);
 
-                    // An audio frame will have an overhead of 6 bytes with this counter and key size:
-                    //   4 bytes truncated signature, counter (1 byte) and 1 byte trailer.
-                    expect(data.byteLength).toEqual(audioBytes.length + 6);
+                    // An audio frame will have an overhead of 30 bytes and key size:
+                    // 16 bytes authentication tag, 12 bytes iv, iv length (1 byte) and 1 byte key index.
+                    expect(data.byteLength).toEqual(audioBytes.length + 30);
 
                     // TODO: provide test vector.
                     done();
@@ -98,10 +98,9 @@ describe('E2EE Context', () => {
                 enqueue: encodedFrame => {
                     const data = new Uint8Array(encodedFrame.data);
 
-                    // A video frame will have an overhead of 12 bytes with this counter and key size:
-                    //   10 bytes signature, counter (1 byte) and 1 byte trailer.
-
-                    expect(data.byteLength).toEqual(videoBytes.length + 12);
+                    // A video frame will have an overhead of 30 bytes and key size:
+                    // 16 bytes authentication tag, 12 bytes iv, iv length (1 byte) and 1 byte key index.
+                    expect(data.byteLength).toEqual(videoBytes.length + 30);
 
                     // TODO: provide test vector.
                     done();

modules/e2ee/crypto-utils.js

@@ -16,30 +16,13 @@ export async function deriveKeys(material) {
         hash: 'SHA-256',
         info
     }, material, {
-        name: 'AES-CTR',
+        name: 'AES-GCM',
         length: 128
     }, false, [ 'encrypt', 'decrypt' ]);
-    const authenticationKey = await crypto.subtle.deriveKey({
-        name: 'HKDF',
-        salt: textEncoder.encode('JFrameAuthenticationKey'),
-        hash: 'SHA-256',
-        info
-    }, material, {
-        name: 'HMAC',
-        hash: 'SHA-256'
-    }, false, [ 'sign' ]);
-    const saltKey = await crypto.subtle.deriveBits({
-        name: 'HKDF',
-        salt: textEncoder.encode('JFrameSaltKey'),
-        hash: 'SHA-256',
-        info
-    }, material, 128);
 
     return {
         material,
-        encryptionKey,
-        authenticationKey,
-        saltKey
+        encryptionKey
     };
 }