livekit-client 2.5.8 → 2.5.9

package/src/e2ee/worker/FrameCryptor.ts

@@ -357,10 +357,15 @@ export class FrameCryptor extends BaseFrameCryptor {
     const data = new Uint8Array(encodedFrame.data);
     const keyIndex = data[encodedFrame.data.byteLength - 1];
 
-    if (this.keys.getKeySet(keyIndex) && this.keys.hasValidKey) {
+    if (this.keys.hasInvalidKeyAtIndex(keyIndex)) {
+      // drop frame
+      return;
+    }
+
+    if (this.keys.getKeySet(keyIndex)) {
       try {
         const decodedFrame = await this.decryptFrame(encodedFrame, keyIndex);
-        this.keys.decryptionSuccess();
+        this.keys.decryptionSuccess(keyIndex);
         if (decodedFrame) {
           return controller.enqueue(decodedFrame);
         }
@@ -369,13 +374,13 @@ export class FrameCryptor extends BaseFrameCryptor {
           // emit an error if the key handler thinks we have a valid key
           if (this.keys.hasValidKey) {
             this.emit(CryptorEvent.Error, error);
-            this.keys.decryptionFailure();
+            this.keys.decryptionFailure(keyIndex);
           }
         } else {
           workerLogger.warn('decoding frame failed', { error });
         }
       }
-    } else if (!this.keys.getKeySet(keyIndex) && this.keys.hasValidKey) {
+    } else {
       // emit an error if the key index is out of bounds but the key handler thinks we still have a valid key
       workerLogger.warn(`skipping decryption due to missing key at index ${keyIndex}`);
       this.emit(
@@ -386,7 +391,7 @@ export class FrameCryptor extends BaseFrameCryptor {
           this.participantIdentity,
         ),
       );
-      this.keys.decryptionFailure();
+      this.keys.decryptionFailure(keyIndex);
     }
   }
 

package/src/e2ee/worker/ParticipantKeyHandler.test.ts

@@ -1,5 +1,6 @@
-import { describe, expect, it } from 'vitest';
-import { KEY_PROVIDER_DEFAULTS } from '../constants';
+import { describe, expect, it, vitest } from 'vitest';
+import { ENCRYPTION_ALGORITHM, KEY_PROVIDER_DEFAULTS } from '../constants';
+import { KeyHandlerEvent } from '../events';
 import { createKeyMaterialFromString } from '../utils';
 import { ParticipantKeyHandler } from './ParticipantKeyHandler';
 
@@ -35,11 +36,38 @@ describe('ParticipantKeyHandler', () => {
     expect(keyHandler.getKeySet(0)?.material).toEqual(materialB);
   });
 
-  it('marks invalid if more than failureTolerance failures', async () => {
+  it('defaults to key index of 0 when setting key', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+      ...KEY_PROVIDER_DEFAULTS,
+    });
+
+    const materialA = await createKeyMaterialFromString('passwordA');
+
+    await keyHandler.setKey(materialA);
+
+    expect(keyHandler.getKeySet(0)?.material).toEqual(materialA);
+  });
+
+  it('defaults to current key index when getting key', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+      ...KEY_PROVIDER_DEFAULTS,
+    });
+
+    const materialA = await createKeyMaterialFromString('passwordA');
+
+    await keyHandler.setKey(materialA, 10);
+
+    expect(keyHandler.getKeySet()?.material).toEqual(materialA);
+  });
+
+  it('marks current key invalid if more than failureTolerance failures', async () => {
     const keyHandler = new ParticipantKeyHandler(participantIdentity, {
       ...KEY_PROVIDER_DEFAULTS,
       failureTolerance: 2,
     });
+
+    keyHandler.setCurrentKeyIndex(10);
+
     expect(keyHandler.hasValidKey).toBe(true);
 
     // 1
@@ -55,13 +83,16 @@ describe('ParticipantKeyHandler', () => {
     expect(keyHandler.hasValidKey).toBe(false);
   });
 
-  it('marks valid on encryption success', async () => {
+  it('marks current key valid on encryption success', async () => {
     const keyHandler = new ParticipantKeyHandler(participantIdentity, {
       ...KEY_PROVIDER_DEFAULTS,
       failureTolerance: 0,
     });
 
+    keyHandler.setCurrentKeyIndex(10);
+
     expect(keyHandler.hasValidKey).toBe(true);
+    expect(keyHandler.hasInvalidKeyAtIndex(0)).toBe(false);
 
     keyHandler.decryptionFailure();
 
@@ -72,13 +103,62 @@ describe('ParticipantKeyHandler', () => {
     expect(keyHandler.hasValidKey).toBe(true);
   });
 
+  it('marks specific key invalid if more than failureTolerance failures', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+      ...KEY_PROVIDER_DEFAULTS,
+      failureTolerance: 2,
+    });
+
+    // set the current key to something different from what we are testing
+    keyHandler.setCurrentKeyIndex(10);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+
+    // 1
+    keyHandler.decryptionFailure(5);
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+
+    // 2
+    keyHandler.decryptionFailure(5);
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+
+    // 3
+    keyHandler.decryptionFailure(5);
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(true);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(10)).toBe(false);
+  });
+
+  it('marks specific key valid on encryption success', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+      ...KEY_PROVIDER_DEFAULTS,
+      failureTolerance: 0,
+    });
+
+    // set the current key to something different from what we are testing
+    keyHandler.setCurrentKeyIndex(10);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+
+    keyHandler.decryptionFailure(5);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(true);
+
+    keyHandler.decryptionSuccess(5);
+
+    expect(keyHandler.hasInvalidKeyAtIndex(5)).toBe(false);
+  });
+
   it('marks valid on new key', async () => {
     const keyHandler = new ParticipantKeyHandler(participantIdentity, {
       ...KEY_PROVIDER_DEFAULTS,
       failureTolerance: 0,
     });
 
+    keyHandler.setCurrentKeyIndex(10);
+
     expect(keyHandler.hasValidKey).toBe(true);
+    expect(keyHandler.hasInvalidKeyAtIndex(0)).toBe(false);
 
     keyHandler.decryptionFailure();
 
@@ -108,7 +188,14 @@ describe('ParticipantKeyHandler', () => {
     expect(keyHandler.getCurrentKeyIndex()).toBe(10);
   });
 
-  it('allows many failures if failureTolerance is -1', async () => {
+  it('allows currentKeyIndex to be explicitly set', async () => {
+    const keyHandler = new ParticipantKeyHandler(participantIdentity, KEY_PROVIDER_DEFAULTS);
+
+    keyHandler.setCurrentKeyIndex(10);
+    expect(keyHandler.getCurrentKeyIndex()).toBe(10);
+  });
+
+  it('allows many failures if failureTolerance is less than zero', async () => {
     const keyHandler = new ParticipantKeyHandler(participantIdentity, {
       ...KEY_PROVIDER_DEFAULTS,
       failureTolerance: -1,
@@ -119,4 +206,81 @@ describe('ParticipantKeyHandler', () => {
       expect(keyHandler.hasValidKey).toBe(true);
     }
   });
+
+  describe('resetKeyStatus', () => {
+    it('marks all keys as valid if no index is provided', () => {
+      const keyHandler = new ParticipantKeyHandler(participantIdentity, {
+        ...KEY_PROVIDER_DEFAULTS,
+        failureTolerance: 0,
+      });
+
+      for (let i = 0; i < KEY_PROVIDER_DEFAULTS.keyringSize; i++) {
+        keyHandler.decryptionFailure(i);
+        expect(keyHandler.hasInvalidKeyAtIndex(i)).toBe(true);
+      }
+
+      keyHandler.resetKeyStatus();
+
+      for (let i = 0; i < KEY_PROVIDER_DEFAULTS.keyringSize; i++) {
+        expect(keyHandler.hasInvalidKeyAtIndex(i)).toBe(false);
+      }
+    });
+  });
+
+  describe('ratchetKey', () => {
+    it('emits event', async () => {
+      const keyHandler = new ParticipantKeyHandler(participantIdentity, KEY_PROVIDER_DEFAULTS);
+
+      const material = await createKeyMaterialFromString('password');
+
+      const keyRatched = vitest.fn();
+
+      keyHandler.on(KeyHandlerEvent.KeyRatcheted, keyRatched);
+
+      await keyHandler.setKey(material);
+
+      await keyHandler.ratchetKey();
+
+      const newMaterial = keyHandler.getKeySet()?.material;
+
+      expect(keyRatched).toHaveBeenCalledWith(newMaterial, participantIdentity, 0);
+    });
+
+    it('ratchets keys predictably', async () => {
+      // we can't extract the keys directly, so we instead use them to encrypt a known plaintext
+      const keyHandler = new ParticipantKeyHandler(participantIdentity, KEY_PROVIDER_DEFAULTS);
+
+      const originalMaterial = await createKeyMaterialFromString('password');
+
+      await keyHandler.setKey(originalMaterial);
+
+      const ciphertexts: Uint8Array[] = [];
+
+      const plaintext = new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]);
+
+      const iv = new Uint8Array(12);
+      const additionalData = new Uint8Array(0);
+
+      for (let i = 0; i < 10; i++) {
+        const { encryptionKey } = keyHandler.getKeySet()!;
+
+        const ciphertext = await crypto.subtle.encrypt(
+          {
+            name: ENCRYPTION_ALGORITHM,
+            iv,
+            additionalData,
+          },
+          encryptionKey,
+          plaintext,
+        );
+        ciphertexts.push(new Uint8Array(ciphertext));
+        await keyHandler.ratchetKey();
+      }
+      // check that all ciphertexts are unique
+      expect(new Set(ciphertexts.map((x) => new TextDecoder().decode(x))).size).toEqual(
+        ciphertexts.length,
+      );
+      expect(ciphertexts).matchSnapshot('ciphertexts');
+    });
+  });
 });

package/src/e2ee/worker/ParticipantKeyHandler.ts

@@ -21,18 +21,19 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
 
   private cryptoKeyRing: Array<KeySet | undefined>;
 
+  private decryptionFailureCounts: Array<number>;
+
   private keyProviderOptions: KeyProviderOptions;
 
   private ratchetPromiseMap: Map<number, Promise<CryptoKey>>;
 
   private participantIdentity: string;
 
-  private decryptionFailureCount = 0;
-
-  private _hasValidKey: boolean = true;
-
-  get hasValidKey() {
-    return this._hasValidKey;
+  /**
+   * true if the current key has not been marked as invalid
+   */
+  get hasValidKey(): boolean {
+    return !this.hasInvalidKeyAtIndex(this.currentKeyIndex);
   }
 
   constructor(participantIdentity: string, keyProviderOptions: KeyProviderOptions) {
@@ -42,35 +43,64 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
       throw new TypeError('Keyring size needs to be between 1 and 256');
     }
     this.cryptoKeyRing = new Array(keyProviderOptions.keyringSize).fill(undefined);
+    this.decryptionFailureCounts = new Array(keyProviderOptions.keyringSize).fill(0);
     this.keyProviderOptions = keyProviderOptions;
     this.ratchetPromiseMap = new Map();
     this.participantIdentity = participantIdentity;
-    this.resetKeyStatus();
   }
 
-  decryptionFailure() {
+  /**
+   * Returns true if the key at the given index is marked as invalid.
+   *
+   * @param keyIndex the index of the key
+   */
+  hasInvalidKeyAtIndex(keyIndex: number): boolean {
+    return (
+      this.keyProviderOptions.failureTolerance >= 0 &&
+      this.decryptionFailureCounts[keyIndex] > this.keyProviderOptions.failureTolerance
+    );
+  }
+
+  /**
+   * Informs the key handler that a decryption failure occurred for an encryption key.
+   * @internal
+   * @param keyIndex the key index for which the failure occurred. Defaults to the current key index.
+   */
+  decryptionFailure(keyIndex: number = this.currentKeyIndex): void {
     if (this.keyProviderOptions.failureTolerance < 0) {
       return;
     }
-    this.decryptionFailureCount += 1;
 
-    if (this.decryptionFailureCount > this.keyProviderOptions.failureTolerance) {
-      workerLogger.warn(`key for ${this.participantIdentity} is being marked as invalid`);
-      this._hasValidKey = false;
+    this.decryptionFailureCounts[keyIndex] += 1;
+
+    if (this.decryptionFailureCounts[keyIndex] > this.keyProviderOptions.failureTolerance) {
+      workerLogger.warn(
+        `key for ${this.participantIdentity} at index ${keyIndex} is being marked as invalid`,
+      );
     }
   }
 
-  decryptionSuccess() {
-    this.resetKeyStatus();
+  /**
+   * Informs the key handler that a frame was successfully decrypted using an encryption key.
+   * @internal
+   * @param keyIndex the key index for which the success occurred. Defaults to the current key index.
+   */
+  decryptionSuccess(keyIndex: number = this.currentKeyIndex): void {
+    this.resetKeyStatus(keyIndex);
   }
 
   /**
    * Call this after user initiated ratchet or a new key has been set in order to make sure to mark potentially
    * invalid keys as valid again
+   *
+   * @param keyIndex the index of the key. Defaults to the current key index.
    */
-  resetKeyStatus() {
-    this.decryptionFailureCount = 0;
-    this._hasValidKey = true;
+  resetKeyStatus(keyIndex?: number): void {
+    if (keyIndex === undefined) {
+      this.decryptionFailureCounts.fill(0);
+    } else {
+      this.decryptionFailureCounts[keyIndex] = 0;
+    }
   }
 
   /**
@@ -103,7 +133,7 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
         );
 
         if (setKey) {
-          this.setKeyFromMaterial(newMaterial, currentKeyIndex, true);
+          await this.setKeyFromMaterial(newMaterial, currentKeyIndex, true);
           this.emit(
             KeyHandlerEvent.KeyRatcheted,
             newMaterial,
@@ -130,7 +160,7 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
    */
   async setKey(material: CryptoKey, keyIndex = 0) {
     await this.setKeyFromMaterial(material, keyIndex);
-    this.resetKeyStatus();
+    this.resetKeyStatus(keyIndex);
   }
 
   /**
@@ -161,7 +191,7 @@ export class ParticipantKeyHandler extends (EventEmitter as new () => TypedEvent
 
   async setCurrentKeyIndex(index: number) {
     this.currentKeyIndex = index % this.cryptoKeyRing.length;
-    this.resetKeyStatus();
+    this.resetKeyStatus(index);
   }
 
   getCurrentKeyIndex() {