Key Service

libs/key-management/src/abstractions/key.service.ts

abstract userKey$(userId: UserId): Observable<UserKey | null>;

const userKey$ = keyService.userKey$(userId);
userKey$.subscribe(key => {
  if (key) {
    // User is unlocked
  } else {
    // User is locked or logged out
  }
});

abstract getUserKey(userId?: string): Promise<UserKey | null>;

abstract setUserKey(key: UserKey, userId: UserId): Promise<void>;

abstract hasUserKey(userId: UserId): Promise<boolean>;

abstract clearStoredUserKey(userId: string): Promise<void>;

abstract makeUserKey(masterKey: MasterKey): Promise<[UserKey, EncString]>;

abstract makeMasterKey(
  password: string,
  email: string,
  kdfConfig: KdfConfig
): Promise<MasterKey>;

abstract makeCipherKey(): Promise<CipherKey>;

const cipherKey = await keyService.makeCipherKey();

abstract makeDataEncKey<T extends UserKey | OrgKey>(
  key: T,
): Promise<[SymmetricCryptoKey, EncString]>;

abstract makeSendKey(keyMaterial: Uint8Array): Promise<SymmetricCryptoKey>;

abstract makeKeyPair(key: SymmetricCryptoKey): Promise<[string, EncString]>;

abstract makeOrgKey<T extends OrgKey | ProviderKey>(
  userId: UserId
): Promise<[EncString, T]>;

abstract userPrivateKey$(userId: UserId): Observable<UserPrivateKey | null>;

abstract userPublicKey$(userId: UserId): Observable<Uint8Array | null>;

abstract userEncryptionKeyPair$(
  userId: UserId,
): Observable<{ privateKey: UserPrivateKey; publicKey: UserPublicKey } | null>;

abstract getFingerprint(
  fingerprintMaterial: string,
  publicKey: Uint8Array
): Promise<string[]>;

abstract getOrDeriveMasterKey(
  password: string,
  userId: UserId
): Promise<MasterKey>;

abstract encryptUserKeyWithMasterKey(
  masterKey: MasterKey,
  userKey: UserKey,
): Promise<[UserKey, EncString]>;

abstract hashMasterKey(
  password: string,
  key: MasterKey,
  hashPurpose?: HashPurpose,
): Promise<string>;

enum HashPurpose {
  ServerAuthorization = 1,  // For server authentication
  LocalAuthorization = 2,   // For local authentication
}

abstract setOrgKeys(
  orgs: ProfileOrganizationResponse[],
  providerOrgs: ProfileProviderOrganizationResponse[],
  userId: UserId,
): Promise<void>;

abstract getOrgKey(orgId: string): Promise<OrgKey | null>;

abstract orgKeys$(
  userId: UserId
): Observable<Record<OrganizationId, OrgKey> | null>;

abstract setProviderKeys(
  providers: ProfileProviderResponse[],
  userId: UserId
): Promise<void>;

abstract providerKeys$(
  userId: UserId
): Observable<Record<ProviderId, ProviderKey> | null>;

abstract cipherDecryptionKeys$(
  userId: UserId,
  legacySupport?: boolean,
): Observable<CipherDecryptionKeys | null>;

type CipherDecryptionKeys = {
  userKey: UserKey;
  orgKeys: Record<OrganizationId, OrgKey> | null;
};

abstract initAccount(userId: UserId): Promise<{
  userKey: UserKey;
  publicKey: string;
  privateKey: EncString;
}>;

abstract validateUserKey(key: UserKey, userId: UserId): Promise<boolean>;

abstract clearKeys(userId: UserId): Promise<void>;

// Symmetric keys
type UserKey = Opaque<SymmetricCryptoKey, "UserKey">;
type MasterKey = Opaque<SymmetricCryptoKey, "MasterKey">;
type OrgKey = Opaque<SymmetricCryptoKey, "OrgKey">;
type ProviderKey = Opaque<SymmetricCryptoKey, "ProviderKey">;
type CipherKey = Opaque<SymmetricCryptoKey, "CipherKey">;
type DeviceKey = Opaque<SymmetricCryptoKey, "DeviceKey">;
type PrfKey = Opaque<SymmetricCryptoKey, "PrfKey">;

// Asymmetric keys
type UserPrivateKey = Opaque<Uint8Array, "UserPrivateKey">;
type UserPublicKey = Opaque<UnsignedPublicKey, "UserPublicKey">;

type KdfConfig = PBKDF2KdfConfig | Argon2KdfConfig;

class PBKDF2KdfConfig {
  kdfType: KdfType.PBKDF2_SHA256;
  iterations: number;  // 600,000 - 2,000,000 (default: 600,000)
}

const kdfConfig = new PBKDF2KdfConfig(600_000);

class Argon2KdfConfig {
  kdfType: KdfType.Argon2id;
  iterations: number;   // 2-10 (default: 3)
  memory: number;       // 16-1024 MB (default: 64)
  parallelism: number;  // 1-16 (default: 4)
}

const kdfConfig = new Argon2KdfConfig(3, 64, 4);

enum KdfType {
  PBKDF2_SHA256 = 0,
  Argon2id = 1,
}

import { KeyService } from '@bitwarden/key-management/abstractions/key.service';

// Generate new user key with master key
const [userKey, encryptedUserKey] = await keyService.makeUserKey(masterKey);

// Set the user key
await keyService.setUserKey(userKey, userId);

// Using observable (recommended)
keyService.userKey$(userId).subscribe(async userKey => {
  if (userKey) {
    // User is unlocked, can decrypt data
    const data = await encryptService.decryptString(encrypted, userKey);
  }
});

// Using promise (legacy)
const userKey = await keyService.getUserKey(userId);

import { PBKDF2KdfConfig } from '@bitwarden/key-management/models/kdf-config';

const kdfConfig = new PBKDF2KdfConfig(600_000);
const masterKey = await keyService.makeMasterKey(
  'user-password',
  '[email protected]',
  kdfConfig
);

// Generate new org key
const [encryptedOrgKey, orgKey] = await keyService.makeOrgKey(userId);

// The orgKey can be used for encryption
// The encryptedOrgKey is stored/shared with members

const keys$ = keyService.cipherDecryptionKeys$(userId);
keys$.subscribe(keys => {
  if (keys) {
    const { userKey, orgKeys } = keys;
    // Decrypt personal ciphers with userKey
    // Decrypt org ciphers with orgKeys[orgId]
  }
});

const publicKey = await keyService.userPublicKey$(userId).toPromise();
const fingerprint = await keyService.getFingerprint(
  '[email protected]',
  publicKey
);
console.log('Fingerprint:', fingerprint.join('-'));
// Example output: "alligator-transfer-laziness-macaroni-blue"