ML-KEM wrapped transmission key MVP

Author: tylerccarson

keeperapi/package-lock.json

@@ -19,6 +19,7 @@
     "publish-to-npm": "npm publish"
   },
   "dependencies": {
+    "@noble/post-quantum": "^0.5.2",
     "asmcrypto.js": "^2.3.2",
     "faye-websocket": "^0.11.3",
     "form-data": "^4.0.4",

keeperapi/package.json

@@ -10,7 +10,7 @@ import {
 } from '../platform'
 import {_asnhex_getHexOfV_AtObj, _asnhex_getPosArrayOfChildren_AtObj} from "./asn1hex";
 import {RSAKey} from "./rsa";
-import {getKeeperKeys} from "../transmissionKeys";
+import {getKeeperKeys, getKeeperMlKemKeys} from "../transmissionKeys";
 import {normal64, normal64Bytes, webSafe64FromBytes} from "../utils";
 import {SocketProxy, socketSendMessage} from '../socket'
 import * as asmCrypto from 'asmcrypto.js'
@@ -45,6 +45,7 @@ export const browserPlatform: Platform = class {
     }
 
     static keys = getKeeperKeys(this.normal64Bytes);
+    static mlKemKeys = getKeeperMlKemKeys(this.base64ToBytes);
 
     static getRandomBytes(length: number): Uint8Array {
         let data = new Uint8Array(length);
@@ -808,7 +809,11 @@ export const browserPlatform: Platform = class {
     }
 
     static async calcAuthVerifier(key: Uint8Array): Promise<Uint8Array> {
-        let digest = await crypto.subtle.digest("SHA-256", key);
+        return this.sha256(key);
+    }
+
+    static async sha256(data: Uint8Array): Promise<Uint8Array> {
+        const digest = await crypto.subtle.digest("SHA-256", data);
         return new Uint8Array(digest);
     }
 

keeperapi/src/browser/platform.ts

@@ -26,6 +26,7 @@ export interface ClientConfiguration {
     useSessionResumption?: boolean
     iterations?: number
     salt?: Uint8Array
+    // TODO: add option here to opt in to use HPKE for transmission key exchange
 }
 export interface ClientConfigurationInternal extends ClientConfiguration {
     deviceConfig: DeviceConfig // v15+ device config
@@ -39,6 +40,7 @@ export type KeeperError = {
     path?: string
     result_code?: string
     key_id?: number
+    qrc_ec_key_id?: number
     region_host?: string
 }
 
@@ -48,6 +50,7 @@ export interface DeviceConfig {
     privateKey?: Uint8Array
     publicKey?: Uint8Array
     transmissionKeyId?: number
+    mlKemPublicKeyId?: number
 }
 
 export interface SessionStorage {
@@ -74,8 +77,23 @@ export interface VendorConfiguration {
 
 export interface TransmissionKey {
     key: Uint8Array
-    publicKeyId: number
-    encryptedKey: Uint8Array
+    ecKeyId: number
+    mlKemKeyId: number
+}
+
+export interface QrcMessageKey {
+    clientEcPublicKey: Uint8Array
+    mlKemEncapsulatedKey: Uint8Array
+    data: Uint8Array
+    msgVersion: number
+    ecKeyId: number
+}
+
+export interface TransmissionKeyHpke {
+    key: Uint8Array
+    publicKeyId: number  // ML-KEM key ID
+    qrcMessageKey: QrcMessageKey
+    optionalData?: Uint8Array
 }
 
 export interface AuthUI {

keeperapi/src/configuration.ts

@@ -4,6 +4,7 @@ import {platform} from './platform'
 import {
     formatTimeDiff,
     generateTransmissionKey,
+    generateHpkeTransmissionKey,
     getKeeperUrl,
     isTwoFactorResultCode, log,
     normal64Bytes,
@@ -26,7 +27,7 @@ import WssClientResponse = Push.WssClientResponse;
 import WssConnectionRequest = Push.WssConnectionRequest;
 import SsoCloudResponse = SsoCloud.SsoCloudResponse;
 import {KeeperHttpResponse, RestCommand} from './commands'
-import { AllowedNumbers, isAllowedNumber } from './transmissionKeys'
+import { AllowedEcKeyIds, AllowedMlKemKeyIds, isAllowedEcKeyId, isAllowedMlKemKeyId } from './transmissionKeys'
 
 export class KeeperEndpoint {
     private _transmissionKey?: TransmissionKey
@@ -37,21 +38,24 @@ export class KeeperEndpoint {
     private onsitePrivateKey: Uint8Array | null = null
     private onsitePublicKey: Uint8Array | null = null
 
-    constructor(private options: ClientConfigurationInternal) {       
+    constructor(private options: ClientConfigurationInternal) {
         if (options.deviceToken) {
             this.deviceToken = options.deviceToken
-        } 
+        }
         if (options.locale) {
             this.locale = options.locale
         }
     }
 
     async getTransmissionKey():Promise<TransmissionKey> {
-        const deviceConfigTransmissionKeyId = this.options.deviceConfig.transmissionKeyId || 7
-        if(!this._transmissionKey && isAllowedNumber(deviceConfigTransmissionKeyId)){
-            this._transmissionKey = await generateTransmissionKey(deviceConfigTransmissionKeyId)
+        const DEFAULT_PROD_EC_KEY_ID = 10
+        const DEFAULT_PROD_ML_KEM_KEY_ID = 100
+        const deviceConfigTransmissionKeyId = this.options.deviceConfig.transmissionKeyId || DEFAULT_PROD_EC_KEY_ID
+        const deviceConfigMlKemKeyId = this.options.deviceConfig.mlKemPublicKeyId || DEFAULT_PROD_ML_KEM_KEY_ID
+        if(!this._transmissionKey && isAllowedEcKeyId(deviceConfigTransmissionKeyId) && isAllowedMlKemKeyId(deviceConfigMlKemKeyId)){
+            this._transmissionKey = await generateTransmissionKey(deviceConfigTransmissionKeyId, deviceConfigMlKemKeyId)
         } else if(!this._transmissionKey){
-            this._transmissionKey = await generateTransmissionKey(7)
+            this._transmissionKey = await generateTransmissionKey(DEFAULT_PROD_EC_KEY_ID, DEFAULT_PROD_ML_KEM_KEY_ID)
         }
 
         return this._transmissionKey
@@ -159,7 +163,8 @@ export class KeeperEndpoint {
         while (true) {
             const payload = 'toBytes' in message ? message.toBytes() : new Uint8Array()
             const apiVersion = message.apiVersion || 0
-            const request = await this.prepareRequest(payload, sessionToken, apiVersion)
+
+            const request = await prepareApiRequest(payload, this._transmissionKey, sessionToken, this.locale, apiVersion)
             log(`Calling REST URL: ${this.getUrl(message.path)}`, 'noCR');
             const startTime = Date.now()
             const response = await platform.post(this.getUrl(message.path), request)
@@ -183,8 +188,9 @@ export class KeeperEndpoint {
                     const errorObj: KeeperError = JSON.parse(errorMessage)
                     switch (errorObj.error) {
                         case 'key':
-                            if(isAllowedNumber(errorObj.key_id!)){
-                                await this.updateTransmissionKey(errorObj.key_id!)
+                            // NOTE: I believe this is subject to change, because the new logic is not backward compatible
+                            if(isAllowedEcKeyId(errorObj.qrc_ec_key_id!) && isAllowedMlKemKeyId(errorObj.key_id!)){
+                                await this.updateTransmissionKey(errorObj.qrc_ec_key_id!, errorObj.key_id!)
                             } else {
                                 throw new Error('Incorrect Transmission Key ID being used.')
                             }
@@ -245,10 +251,11 @@ export class KeeperEndpoint {
         return platform.get(this.getUrl(path), {})
     }
 
-    public async updateTransmissionKey(keyNumber: AllowedNumbers) {
-        this._transmissionKey = await generateTransmissionKey(keyNumber)
+    public async updateTransmissionKey(ecKeyId: AllowedEcKeyIds, mlKemKeyId: AllowedMlKemKeyIds) {
+        this._transmissionKey = await generateTransmissionKey(ecKeyId, mlKemKeyId)
 
-        this.options.deviceConfig.transmissionKeyId = keyNumber
+        this.options.deviceConfig.transmissionKeyId = ecKeyId
+        this.options.deviceConfig.mlKemPublicKeyId = mlKemKeyId
         if (this.options.onDeviceConfig) {
             await this.options.onDeviceConfig(this.options.deviceConfig, this.options.host);
         }
@@ -329,7 +336,13 @@ export async function getPushConnectionRequest(messageSessionUid: Uint8Array, tr
     return webSafe64FromBytes(apiRequest)
 }
 
-export async function prepareApiRequest(payload: Uint8Array | unknown, transmissionKey: TransmissionKey, sessionToken?: string, locale?: string, apiVersion?: number): Promise<Uint8Array> {
+export async function prepareApiRequest(
+    payload: Uint8Array | unknown,
+    transmissionKey: TransmissionKey,
+    sessionToken?: string,
+    locale?: string,
+    apiVersion?: number
+): Promise<Uint8Array> {
     const requestPayload = ApiRequestPayload.create()
     if (payload) {
         requestPayload.payload = payload instanceof Uint8Array
@@ -340,14 +353,23 @@ export async function prepareApiRequest(payload: Uint8Array | unknown, transmiss
         requestPayload.encryptedSessionToken = normal64Bytes(sessionToken);
     }
     requestPayload.apiVersion = apiVersion || 0
-    let requestPayloadBytes = ApiRequestPayload.encode(requestPayload).finish()
-    let encryptedRequestPayload = await platform.aesGcmEncrypt(requestPayloadBytes, transmissionKey.key)
-    let apiRequest = ApiRequest.create({
-        encryptedTransmissionKey: transmissionKey.encryptedKey,
+    const requestPayloadBytes = ApiRequestPayload.encode(requestPayload).finish()
+    const encryptedRequestPayload = await platform.aesGcmEncrypt(requestPayloadBytes, transmissionKey.key)
+
+    // Use QRC to wrap the transmission key
+    const hpkeTransmissionKey = await generateHpkeTransmissionKey(
+        transmissionKey,
+        true  // use optional data
+    )
+
+    const apiRequest = ApiRequest.create({
+        qrcMessageKey: hpkeTransmissionKey.qrcMessageKey,
         encryptedPayload: encryptedRequestPayload,
-        publicKeyId: transmissionKey.publicKeyId,
+        publicKeyId: hpkeTransmissionKey.publicKeyId,  // ML-KEM key ID
+        encryptedTransmissionKey: hpkeTransmissionKey.optionalData || null,  // Optional data or empty
         locale: locale || 'en_US'
-    })
+    });
+
     return ApiRequest.encode(apiRequest).finish()
 }
 

keeperapi/src/endpoint.ts

@@ -15,7 +15,7 @@ import {
     UnwrappedKeyType
 } from "../platform";
 import {RSA_PKCS1_PADDING} from "constants";
-import {getKeeperKeys} from "../transmissionKeys";
+import {getKeeperKeys, getKeeperMlKemKeys} from "../transmissionKeys";
 import {SocketProxy, socketSendMessage} from '../socket'
 import {normal64} from "../utils";
 import type {KeeperHttpResponse} from "../commands";
@@ -35,7 +35,8 @@ export const nodePlatform: Platform = class {
     }
 
     static keys = getKeeperKeys(this.normal64Bytes);
-    
+    static mlKemKeys = getKeeperMlKemKeys(this.base64ToBytes);
+
     static getRandomBytes(length: number): Uint8Array {
         return crypto.randomBytes(length);
     }
@@ -305,7 +306,11 @@ export const nodePlatform: Platform = class {
     }
 
     static calcAuthVerifier(key: Uint8Array): Promise<Uint8Array> {
-        return Promise.resolve(crypto.createHash("SHA256").update(key).digest());
+        return this.sha256(key);
+    }
+
+    static sha256(data: Uint8Array): Promise<Uint8Array> {
+        return Promise.resolve(crypto.createHash("SHA256").update(data).digest());
     }
 
     static get(

keeperapi/src/node/platform.ts

@@ -4,6 +4,7 @@ import type {CryptoWorkerPool, CryptoWorkerPoolConfig} from './cryptoWorker';
 
 export interface Platform {
     keys: Uint8Array[];
+    mlKemKeys: Uint8Array[];  // ML-KEM public keys for QRC encryption
 
     supportsConcurrency: boolean
 
@@ -75,6 +76,8 @@ export interface Platform {
 
     calcAuthVerifier(key: Uint8Array): Promise<Uint8Array>;
 
+    sha256(data: Uint8Array): Promise<Uint8Array>;
+
     get(url: string, headers: any): Promise<KeeperHttpResponse>;
 
     post(url: string, request: Uint8Array, headers?: any): Promise<KeeperHttpResponse>;