[PM-6211] Create key generation service (#7939)

* create key generation service

* replace old key generation service and add references

* use key generation service in key connector service

* use key generation service in send service

* user key generation service in access service

* use key generation service in device trust service

* fix tests

* fix browser

* add createKeyFromMaterial and tests

* create ephemeral key

* fix tests

* rename method and add returns docs

* ignore material in destructure

* modify test

* specify material as key material

* pull out magic strings to properties

* make salt optional and generate if not provided

* fix test

* fix parameters

* update docs to include link to HKDF rfc

libs/common/src/platform/abstractions/key-generation.service.ts

@@ -0,0 +1,59 @@
+import { KdfConfig } from "../../auth/models/domain/kdf-config";
+import { CsprngArray } from "../../types/csprng";
+import { KdfType } from "../enums";
+import { SymmetricCryptoKey } from "../models/domain/symmetric-crypto-key";
+
+export abstract class KeyGenerationService {
+  /**
+   * Generates a key of the given length suitable for use in AES encryption
+   * @param bitLength Length of key.
+   * 256 bits = 32 bytes
+   * 512 bits = 64 bytes
+   * @returns Generated key.
+   */
+  createKey: (bitLength: 256 | 512) => Promise<SymmetricCryptoKey>;
+  /**
+   * Generates key material from CSPRNG and derives a 64 byte key from it.
+   * Uses HKDF, see {@link https://datatracker.ietf.org/doc/html/rfc5869 RFC 5869}
+   * for details.
+   * @param bitLength Length of key material.
+   * @param purpose Purpose for the key derivation function.
+   * Different purposes results in different keys, even with the same material.
+   * @param salt Optional. If not provided will be generated from CSPRNG.
+   * @returns An object containing the salt, key material, and derived key.
+   */
+  createKeyWithPurpose: (
+    bitLength: 128 | 192 | 256 | 512,
+    purpose: string,
+    salt?: string,
+  ) => Promise<{ salt: string; material: CsprngArray; derivedKey: SymmetricCryptoKey }>;
+  /**
+   * Derives a 64 byte key from key material.
+   * @remark The key material should be generated from {@link createKey}, or {@link createKeyWithPurpose}.
+   * Uses HKDF, see {@link https://datatracker.ietf.org/doc/html/rfc5869 RFC 5869} for details.
+   * @param material key material.
+   * @param salt Salt for the key derivation function.
+   * @param purpose Purpose for the key derivation function.
+   * Different purposes results in different keys, even with the same material.
+   * @returns 64 byte derived key.
+   */
+  deriveKeyFromMaterial: (
+    material: CsprngArray,
+    salt: string,
+    purpose: string,
+  ) => Promise<SymmetricCryptoKey>;
+  /**
+   * Derives a 32 byte key from a password using a key derivation function.
+   * @param password Password to derive the key from.
+   * @param salt Salt for the key derivation function.
+   * @param kdf Key derivation function to use.
+   * @param kdfConfig Configuration for the key derivation function.
+   * @returns 32 byte derived key.
+   */
+  deriveKeyFromPassword: (
+    password: string | Uint8Array,
+    salt: string | Uint8Array,
+    kdf: KdfType,
+    kdfConfig: KdfConfig,
+  ) => Promise<SymmetricCryptoKey>;
+}

libs/common/src/platform/services/crypto.service.spec.ts

@@ -10,6 +10,7 @@ import { UserId } from "../../types/guid";
 import { UserKey, MasterKey, PinKey } from "../../types/key";
 import { CryptoFunctionService } from "../abstractions/crypto-function.service";
 import { EncryptService } from "../abstractions/encrypt.service";
+import { KeyGenerationService } from "../abstractions/key-generation.service";
 import { LogService } from "../abstractions/log.service";
 import { PlatformUtilsService } from "../abstractions/platform-utils.service";
 import { StateService } from "../abstractions/state.service";
@@ -23,6 +24,7 @@ import { USER_EVER_HAD_USER_KEY, USER_KEY } from "./key-state/user-key.state";
 describe("cryptoService", () => {
   let cryptoService: CryptoService;
 
+  const keyGenerationService = mock<KeyGenerationService>();
   const cryptoFunctionService = mock<CryptoFunctionService>();
   const encryptService = mock<EncryptService>();
   const platformUtilService = mock<PlatformUtilsService>();
@@ -38,6 +40,7 @@ describe("cryptoService", () => {
     stateProvider = new FakeStateProvider(accountService);
 
     cryptoService = new CryptoService(
+      keyGenerationService,
       cryptoFunctionService,
       encryptService,
       platformUtilService,

libs/common/src/platform/services/crypto.service.ts

@@ -9,6 +9,7 @@ import { AccountService } from "../../auth/abstractions/account.service";
 import { AuthenticationStatus } from "../../auth/enums/authentication-status";
 import { KdfConfig } from "../../auth/models/domain/kdf-config";
 import { Utils } from "../../platform/misc/utils";
+import { CsprngArray } from "../../types/csprng";
 import { OrganizationId, ProviderId, UserId } from "../../types/guid";
 import {
   OrgKey,
@@ -23,6 +24,7 @@ import {
 import { CryptoFunctionService } from "../abstractions/crypto-function.service";
 import { CryptoService as CryptoServiceAbstraction } from "../abstractions/crypto.service";
 import { EncryptService } from "../abstractions/encrypt.service";
+import { KeyGenerationService } from "../abstractions/key-generation.service";
 import { LogService } from "../abstractions/log.service";
 import { PlatformUtilsService } from "../abstractions/platform-utils.service";
 import { StateService } from "../abstractions/state.service";
@@ -80,6 +82,7 @@ export class CryptoService implements CryptoServiceAbstraction {
   readonly everHadUserKey$: Observable<boolean>;
 
   constructor(
+    protected keyGenerationService: KeyGenerationService,
     protected cryptoFunctionService: CryptoFunctionService,
     protected encryptService: EncryptService,
     protected platformUtilService: PlatformUtilsService,
@@ -219,8 +222,8 @@ export class CryptoService implements CryptoServiceAbstraction {
       throw new Error("No Master Key found.");
     }
 
-    const newUserKey = await this.cryptoFunctionService.aesGenerateKey(512);
-    return this.buildProtectedSymmetricKey(masterKey, newUserKey);
+    const newUserKey = await this.keyGenerationService.createKey(512);
+    return this.buildProtectedSymmetricKey(masterKey, newUserKey.key);
   }
 
   async clearUserKey(clearStoredKeys = true, userId?: UserId): Promise<void> {
@@ -294,7 +297,12 @@ export class CryptoService implements CryptoServiceAbstraction {
     kdf: KdfType,
     KdfConfig: KdfConfig,
   ): Promise<MasterKey> {
-    return (await this.makeKey(password, email, kdf, KdfConfig)) as MasterKey;
+    return (await this.keyGenerationService.deriveKeyFromPassword(
+      password,
+      email,
+      kdf,
+      KdfConfig,
+    )) as MasterKey;
   }
 
   async clearMasterKey(userId?: UserId): Promise<void> {
@@ -452,8 +460,8 @@ export class CryptoService implements CryptoServiceAbstraction {
       throw new Error("No key provided");
     }
 
-    const newSymKey = await this.cryptoFunctionService.aesGenerateKey(512);
-    return this.buildProtectedSymmetricKey(key, newSymKey);
+    const newSymKey = await this.keyGenerationService.createKey(512);
+    return this.buildProtectedSymmetricKey(key, newSymKey.key);
   }
 
   async clearOrgKeys(memoryOnly?: boolean, userId?: UserId): Promise<void> {
@@ -522,10 +530,10 @@ export class CryptoService implements CryptoServiceAbstraction {
   }
 
   async makeOrgKey<T extends OrgKey | ProviderKey>(): Promise<[EncString, T]> {
-    const shareKey = await this.cryptoFunctionService.aesGenerateKey(512);
+    const shareKey = await this.keyGenerationService.createKey(512);
     const publicKey = await this.getPublicKey();
-    const encShareKey = await this.rsaEncrypt(shareKey, publicKey);
-    return [encShareKey, new SymmetricCryptoKey(shareKey) as T];
+    const encShareKey = await this.rsaEncrypt(shareKey.key, publicKey);
+    return [encShareKey, shareKey as T];
   }
 
   async setPrivateKey(encPrivateKey: EncryptedString): Promise<void> {
@@ -588,7 +596,7 @@ export class CryptoService implements CryptoServiceAbstraction {
   }
 
   async makePinKey(pin: string, salt: string, kdf: KdfType, kdfConfig: KdfConfig): Promise<PinKey> {
-    const pinKey = await this.makeKey(pin, salt, kdf, kdfConfig);
+    const pinKey = await this.keyGenerationService.deriveKeyFromPassword(pin, salt, kdf, kdfConfig);
     return (await this.stretchKey(pinKey)) as PinKey;
   }
 
@@ -636,20 +644,16 @@ export class CryptoService implements CryptoServiceAbstraction {
     return new SymmetricCryptoKey(masterKey) as MasterKey;
   }
 
-  async makeSendKey(keyMaterial: Uint8Array): Promise<SymmetricCryptoKey> {
-    const sendKey = await this.cryptoFunctionService.hkdf(
+  async makeSendKey(keyMaterial: CsprngArray): Promise<SymmetricCryptoKey> {
+    return await this.keyGenerationService.deriveKeyFromMaterial(
       keyMaterial,
       "bitwarden-send",
       "send",
-      64,
-      "sha256",
     );
-    return new SymmetricCryptoKey(sendKey);
   }
 
   async makeCipherKey(): Promise<CipherKey> {
-    const randomBytes = await this.cryptoFunctionService.aesGenerateKey(512);
-    return new SymmetricCryptoKey(randomBytes) as CipherKey;
+    return (await this.keyGenerationService.createKey(512)) as CipherKey;
   }
 
   async clearKeys(userId?: UserId): Promise<any> {
@@ -802,8 +806,7 @@ export class CryptoService implements CryptoServiceAbstraction {
     publicKey: string;
     privateKey: EncString;
   }> {
-    const rawKey = await this.cryptoFunctionService.aesGenerateKey(512);
-    const userKey = new SymmetricCryptoKey(rawKey) as UserKey;
+    const userKey = (await this.keyGenerationService.createKey(512)) as UserKey;
     const [publicKey, privateKey] = await this.makeKeyPair(userKey);
     await this.setUserKey(userKey);
     await this.activeUserEncryptedPrivateKeyState.update(() => privateKey.encryptedString);
@@ -986,46 +989,6 @@ export class CryptoService implements CryptoServiceAbstraction {
     return [new SymmetricCryptoKey(newSymKey) as T, protectedSymKey];
   }
 
-  private async makeKey(
-    password: string,
-    salt: string,
-    kdf: KdfType,
-    kdfConfig: KdfConfig,
-  ): Promise<SymmetricCryptoKey> {
-    let key: Uint8Array = null;
-    if (kdf == null || kdf === KdfType.PBKDF2_SHA256) {
-      if (kdfConfig.iterations == null) {
-        kdfConfig.iterations = PBKDF2_ITERATIONS.defaultValue;
-      }
-
-      key = await this.cryptoFunctionService.pbkdf2(password, salt, "sha256", kdfConfig.iterations);
-    } else if (kdf == KdfType.Argon2id) {
-      if (kdfConfig.iterations == null) {
-        kdfConfig.iterations = ARGON2_ITERATIONS.defaultValue;
-      }
-
-      if (kdfConfig.memory == null) {
-        kdfConfig.memory = ARGON2_MEMORY.defaultValue;
-      }
-
-      if (kdfConfig.parallelism == null) {
-        kdfConfig.parallelism = ARGON2_PARALLELISM.defaultValue;
-      }
-
-      const saltHash = await this.cryptoFunctionService.hash(salt, "sha256");
-      key = await this.cryptoFunctionService.argon2(
-        password,
-        saltHash,
-        kdfConfig.iterations,
-        kdfConfig.memory * 1024, // convert to KiB from MiB
-        kdfConfig.parallelism,
-      );
-    } else {
-      throw new Error("Unknown Kdf.");
-    }
-    return new SymmetricCryptoKey(key);
-  }
-
   // --LEGACY METHODS--
   // We previously used the master key for additional keys, but now we use the user key.
   // These methods support migrating the old keys to the new ones.

libs/common/src/platform/services/key-generation.service.spec.ts

@@ -0,0 +1,102 @@
+import { mock } from "jest-mock-extended";
+
+import { KdfConfig } from "../../auth/models/domain/kdf-config";
+import { CsprngArray } from "../../types/csprng";
+import { CryptoFunctionService } from "../abstractions/crypto-function.service";
+import { KdfType } from "../enums";
+
+import { KeyGenerationService } from "./key-generation.service";
+
+describe("KeyGenerationService", () => {
+  let sut: KeyGenerationService;
+
+  const cryptoFunctionService = mock<CryptoFunctionService>();
+
+  beforeEach(() => {
+    sut = new KeyGenerationService(cryptoFunctionService);
+  });
+
+  describe("createKey", () => {
+    test.each([256, 512])(
+      "it should delegate key creation to crypto function service",
+      async (bitLength: 256 | 512) => {
+        cryptoFunctionService.aesGenerateKey
+          .calledWith(bitLength)
+          .mockResolvedValue(new Uint8Array(bitLength / 8) as CsprngArray);
+
+        await sut.createKey(bitLength);
+
+        expect(cryptoFunctionService.aesGenerateKey).toHaveBeenCalledWith(bitLength);
+      },
+    );
+  });
+
+  describe("createMaterialAndKey", () => {
+    test.each([128, 192, 256, 512])(
+      "should create a 64 byte key from different material lengths",
+      async (bitLength: 128 | 192 | 256 | 512) => {
+        const inputMaterial = new Uint8Array(bitLength / 8) as CsprngArray;
+        const inputSalt = "salt";
+        const purpose = "purpose";
+
+        cryptoFunctionService.aesGenerateKey.calledWith(bitLength).mockResolvedValue(inputMaterial);
+        cryptoFunctionService.hkdf
+          .calledWith(inputMaterial, inputSalt, purpose, 64, "sha256")
+          .mockResolvedValue(new Uint8Array(64));
+
+        const { salt, material, derivedKey } = await sut.createKeyWithPurpose(
+          bitLength,
+          purpose,
+          inputSalt,
+        );
+
+        expect(salt).toEqual(inputSalt);
+        expect(material).toEqual(inputMaterial);
+        expect(derivedKey.key.length).toEqual(64);
+      },
+    );
+  });
+
+  describe("deriveKeyFromMaterial", () => {
+    it("should derive a 64 byte key from material", async () => {
+      const material = new Uint8Array(32) as CsprngArray;
+      const salt = "salt";
+      const purpose = "purpose";
+
+      cryptoFunctionService.hkdf.mockResolvedValue(new Uint8Array(64));
+
+      const key = await sut.deriveKeyFromMaterial(material, salt, purpose);
+
+      expect(key.key.length).toEqual(64);
+    });
+  });
+
+  describe("deriveKeyFromPassword", () => {
+    it("should derive a 32 byte key from a password using pbkdf2", async () => {
+      const password = "password";
+      const salt = "salt";
+      const kdf = KdfType.PBKDF2_SHA256;
+      const kdfConfig = new KdfConfig(600_000);
+
+      cryptoFunctionService.pbkdf2.mockResolvedValue(new Uint8Array(32));
+
+      const key = await sut.deriveKeyFromPassword(password, salt, kdf, kdfConfig);
+
+      expect(key.key.length).toEqual(32);
+    });
+
+    it("should derive a 32 byte key from a password using argon2id", async () => {
+      const password = "password";
+      const salt = "salt";
+      const kdf = KdfType.Argon2id;
+      const kdfConfig = new KdfConfig(600_000, 15);
+
+      cryptoFunctionService.hash.mockResolvedValue(new Uint8Array(32));
+      cryptoFunctionService.argon2.mockResolvedValue(new Uint8Array(32));
+
+      const key = await sut.deriveKeyFromPassword(password, salt, kdf, kdfConfig);
+
+      expect(key.key.length).toEqual(32);
+    });
+  });
+});

libs/common/src/platform/services/key-generation.service.ts

@@ -0,0 +1,85 @@
+import { KdfConfig } from "../../auth/models/domain/kdf-config";
+import { CsprngArray } from "../../types/csprng";
+import { CryptoFunctionService } from "../abstractions/crypto-function.service";
+import { KeyGenerationService as KeyGenerationServiceAbstraction } from "../abstractions/key-generation.service";
+import {
+  ARGON2_ITERATIONS,
+  ARGON2_MEMORY,
+  ARGON2_PARALLELISM,
+  KdfType,
+  PBKDF2_ITERATIONS,
+} from "../enums";
+import { Utils } from "../misc/utils";
+import { SymmetricCryptoKey } from "../models/domain/symmetric-crypto-key";
+
+export class KeyGenerationService implements KeyGenerationServiceAbstraction {
+  constructor(private cryptoFunctionService: CryptoFunctionService) {}
+
+  async createKey(bitLength: 256 | 512): Promise<SymmetricCryptoKey> {
+    const key = await this.cryptoFunctionService.aesGenerateKey(bitLength);
+    return new SymmetricCryptoKey(key);
+  }
+
+  async createKeyWithPurpose(
+    bitLength: 128 | 192 | 256 | 512,
+    purpose: string,
+    salt?: string,
+  ): Promise<{ salt: string; material: CsprngArray; derivedKey: SymmetricCryptoKey }> {
+    if (salt == null) {
+      const bytes = await this.cryptoFunctionService.randomBytes(32);
+      salt = Utils.fromBufferToUtf8(bytes);
+    }
+    const material = await this.cryptoFunctionService.aesGenerateKey(bitLength);
+    const key = await this.cryptoFunctionService.hkdf(material, salt, purpose, 64, "sha256");
+    return { salt, material, derivedKey: new SymmetricCryptoKey(key) };
+  }
+
+  async deriveKeyFromMaterial(
+    material: CsprngArray,
+    salt: string,
+    purpose: string,
+  ): Promise<SymmetricCryptoKey> {
+    const key = await this.cryptoFunctionService.hkdf(material, salt, purpose, 64, "sha256");
+    return new SymmetricCryptoKey(key);
+  }
+
+  async deriveKeyFromPassword(
+    password: string | Uint8Array,
+    salt: string | Uint8Array,
+    kdf: KdfType,
+    kdfConfig: KdfConfig,
+  ): Promise<SymmetricCryptoKey> {
+    let key: Uint8Array = null;
+    if (kdf == null || kdf === KdfType.PBKDF2_SHA256) {
+      if (kdfConfig.iterations == null) {
+        kdfConfig.iterations = PBKDF2_ITERATIONS.defaultValue;
+      }
+
+      key = await this.cryptoFunctionService.pbkdf2(password, salt, "sha256", kdfConfig.iterations);
+    } else if (kdf == KdfType.Argon2id) {
+      if (kdfConfig.iterations == null) {
+        kdfConfig.iterations = ARGON2_ITERATIONS.defaultValue;
+      }
+
+      if (kdfConfig.memory == null) {
+        kdfConfig.memory = ARGON2_MEMORY.defaultValue;
+      }
+
+      if (kdfConfig.parallelism == null) {
+        kdfConfig.parallelism = ARGON2_PARALLELISM.defaultValue;
+      }
+
+      const saltHash = await this.cryptoFunctionService.hash(salt, "sha256");
+      key = await this.cryptoFunctionService.argon2(
+        password,
+        saltHash,
+        kdfConfig.iterations,
+        kdfConfig.memory * 1024, // convert to KiB from MiB
+        kdfConfig.parallelism,
+      );
+    } else {
+      throw new Error("Unknown Kdf.");
+    }
+    return new SymmetricCryptoKey(key);
+  }
+}