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);

keeperapi/src/browser/platform.ts

@@ -48,6 +48,7 @@ export interface DeviceConfig {
     privateKey?: Uint8Array
     publicKey?: Uint8Array
     transmissionKeyId?: number
+    mlKemPublicKeyId?: number  // ML-KEM key ID for QRC encryption (optional)
 }
 
 export interface SessionStorage {
@@ -78,6 +79,21 @@ export interface TransmissionKey {
     encryptedKey: Uint8Array
 }
 
+export interface QrcMessageKey {
+    clientEcPublicKey: Uint8Array
+    mlKemEncapsulatedKey: Uint8Array
+    data: Uint8Array
+    msgVersion: number
+    ecKeyId: number
+}
+
+export interface TransmissionKeyQrc {
+    key: Uint8Array
+    publicKeyId: number  // ML-KEM key ID
+    qrcMessageKey: QrcMessageKey
+    optionalData?: Uint8Array
+}
+
 export interface AuthUI {
     getTwoFactorCode(errorMessage?: string): Promise<string>;
     displayDialog(): Promise<boolean>;

keeperapi/src/configuration.ts

@@ -4,6 +4,7 @@ import {platform} from './platform'
 import {
     formatTimeDiff,
     generateTransmissionKey,
+    generateTransmissionKeyQrc,
     getKeeperUrl,
     isTwoFactorResultCode, log,
     normal64Bytes,
@@ -17,7 +18,7 @@ import {
     registerDeviceInRegionMessage,
     updateDeviceMessage
 } from './restMessages'
-import {ClientConfigurationInternal, TransmissionKey} from './configuration';
+import {ClientConfigurationInternal, TransmissionKey, TransmissionKeyQrc} from './configuration';
 import ApiRequestPayload = Authentication.ApiRequestPayload;
 import ApiRequest = Authentication.ApiRequest;
 import IDeviceResponse = Authentication.IDeviceResponse;
@@ -37,10 +38,10 @@ 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
         }
@@ -159,7 +160,35 @@ 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)
+
+            // Determine whether to use QRC or traditional EC encryption
+            const mlKemPublicKeyId = this.options.deviceConfig.mlKemPublicKeyId || 100
+
+            // Use QRC to wrap the transmission key
+            const ecKeyId = this.options.deviceConfig.transmissionKeyId || 7
+            if (!isAllowedNumber(ecKeyId)) {
+                throw new Error(`Invalid EC key ID: ${ecKeyId}`)
+            }
+
+            const serverEcPublicKey = platform.keys[ecKeyId]
+            const serverMlKemPublicKey = platform.mlKemKeys[mlKemPublicKeyId]
+
+            if (!serverEcPublicKey) {
+                throw new Error(`EC public key not found for ID: ${ecKeyId}`)
+            }
+            if (!serverMlKemPublicKey) {
+                throw new Error(`ML-KEM public key not found for ID: ${mlKemPublicKeyId}`)
+            }
+
+            const requestTransmissionKey = await generateTransmissionKeyQrc(
+                mlKemPublicKeyId,
+                serverEcPublicKey,
+                serverMlKemPublicKey,
+                ecKeyId,
+                true  // use optional data
+            )
+
+            const request = await prepareApiRequest(payload, requestTransmissionKey, 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)
@@ -174,7 +203,7 @@ export class KeeperEndpoint {
                 console.log("Response code:", response.statusCode);
             }
             try {
-                const decrypted = await platform.aesGcmDecrypt(response.data, this._transmissionKey.key)
+                const decrypted = await platform.aesGcmDecrypt(response.data, requestTransmissionKey.key)
                 if ('fromBytes' in message) return message.fromBytes(decrypted)
                 return
             } catch {
@@ -256,7 +285,41 @@ export class KeeperEndpoint {
 
     public async prepareRequest(payload: Uint8Array | unknown, sessionToken?: string, apiVersion?: number): Promise<Uint8Array> {
         this._transmissionKey = await this.getTransmissionKey()
-        return prepareApiRequest(payload, this._transmissionKey, sessionToken, this.locale, apiVersion)
+
+        // Determine whether to use QRC or traditional EC encryption
+        const mlKemPublicKeyId = this.options.deviceConfig.mlKemPublicKeyId
+        let requestTransmissionKey: TransmissionKey | TransmissionKeyQrc
+
+        if (mlKemPublicKeyId) {
+            // Use QRC to wrap the transmission key
+            const ecKeyId = this.options.deviceConfig.transmissionKeyId || 7
+            if (!isAllowedNumber(ecKeyId)) {
+                throw new Error(`Invalid EC key ID: ${ecKeyId}`)
+            }
+
+            const serverEcPublicKey = platform.keys[ecKeyId]
+            const serverMlKemPublicKey = platform.mlKemKeys[mlKemPublicKeyId]
+
+            if (!serverEcPublicKey) {
+                throw new Error(`EC public key not found for ID: ${ecKeyId}`)
+            }
+            if (!serverMlKemPublicKey) {
+                throw new Error(`ML-KEM public key not found for ID: ${mlKemPublicKeyId}`)
+            }
+
+            requestTransmissionKey = await generateTransmissionKeyQrc(
+                mlKemPublicKeyId,
+                serverEcPublicKey,
+                serverMlKemPublicKey,
+                ecKeyId,
+                true  // use optional data
+            )
+        } else {
+            // Use traditional EC encryption
+            requestTransmissionKey = this._transmissionKey
+        }
+
+        return prepareApiRequest(payload, requestTransmissionKey, sessionToken, this.locale, apiVersion)
     }
 
     async decryptPushMessage(pushMessageData: Uint8Array): Promise<WssClientResponse> {
@@ -329,7 +392,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 | TransmissionKeyQrc,
+    sessionToken?: string,
+    locale?: string,
+    apiVersion?: number
+): Promise<Uint8Array> {
     const requestPayload = ApiRequestPayload.create()
     if (payload) {
         requestPayload.payload = payload instanceof Uint8Array
@@ -342,12 +411,37 @@ export async function prepareApiRequest(payload: Uint8Array | unknown, transmiss
     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,
-        encryptedPayload: encryptedRequestPayload,
-        publicKeyId: transmissionKey.publicKeyId,
-        locale: locale || 'en_US'
-    })
+
+    // Check if this is a QRC transmission key
+    const isQrc = 'qrcMessageKey' in transmissionKey;
+
+    let apiRequest: Authentication.IApiRequest;
+    if (isQrc) {
+        // Use QRC encryption
+        const qrcKey = transmissionKey as TransmissionKeyQrc;
+        apiRequest = ApiRequest.create({
+            qrcMessageKey: {
+                clientEcPublicKey: qrcKey.qrcMessageKey.clientEcPublicKey,
+                mlKemEncapsulatedKey: qrcKey.qrcMessageKey.mlKemEncapsulatedKey,
+                data: qrcKey.qrcMessageKey.data,
+                msgVersion: qrcKey.qrcMessageKey.msgVersion,
+                ecKeyId: qrcKey.qrcMessageKey.ecKeyId
+            },
+            encryptedPayload: encryptedRequestPayload,
+            publicKeyId: qrcKey.publicKeyId,  // ML-KEM key ID
+            encryptedTransmissionKey: qrcKey.optionalData || new Uint8Array(0),  // Optional data or empty
+            locale: locale || 'en_US'
+        });
+    } else {
+        // Use traditional EC encryption
+        apiRequest = ApiRequest.create({
+            encryptedTransmissionKey: transmissionKey.encryptedKey,
+            encryptedPayload: encryptedRequestPayload,
+            publicKeyId: transmissionKey.publicKeyId,
+            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);
     }

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