@matter/general 0.14.1-alpha.0-20250606-a9bcd03f9 → 0.15.0-alpha.0-20250612-ddd428561

package/src/crypto/Key.ts

@@ -9,14 +9,13 @@ import { DerCodec, DerNode, DerType } from "../codec/DerCodec.js";
 import { MatterError, NotImplementedError } from "../MatterError.js";
 import { Bytes } from "../util/Bytes.js";
 import { ec } from "./Crypto.js";
+import { KeyInputError } from "./CryptoError.js";
 
 const {
     numberToBytesBE,
     p256: { ProjectivePoint },
 } = ec;
 
-class KeyError extends MatterError {}
-
 const JWK_KEYS = [
     "crv",
     "d",
@@ -228,7 +227,7 @@ function checkDerVersion(type: string, node: DerNode | undefined, version: numbe
         node && node._tag === DerType.Integer && node._bytes && node._bytes.length === 1 && node._bytes[0];
 
     if (derVersion !== version) {
-        throw new KeyError(`${type} key version mismatch`);
+        throw new KeyInputError(`${type} key version mismatch`);
     }
 }
 
@@ -237,14 +236,14 @@ function getDerObjectID(type: string, node?: DerNode) {
 
     if (id) return id;
 
-    throw new KeyError(`Missing object in ${type} key`);
+    throw new KeyInputError(`Missing object in ${type} key`);
 }
 
 function getDerCurve(type: string, node?: DerNode) {
     const oid = getDerObjectID(type, node);
     const curve = (<any>CurveLookup)[Bytes.toHex(oid)];
     if (curve) return curve;
-    throw new KeyError(`Unsupported ${type} EC curve`);
+    throw new KeyInputError(`Unsupported ${type} EC curve`);
 }
 
 function getDerKey(type: string, node?: DerNode, derType: DerType = DerType.OctetString) {
@@ -297,7 +296,7 @@ namespace Translators {
             const algorithmElements = outer?._elements?.[1]?._elements;
             const algorithm = getDerObjectID("PKCS #8", algorithmElements?.[0]);
             if (Bytes.toHex(algorithm) !== Asn1ObjectID.ecPublicKey) {
-                throw new KeyError("Unsupported PKCS #8 decryption algorithm");
+                throw new KeyInputError("Unsupported PKCS #8 decryption algorithm");
             }
 
             // Curve
@@ -306,7 +305,7 @@ namespace Translators {
             // Private key
             const innerBytes = outer?._elements?.[2]._bytes;
             if (innerBytes === undefined || innerBytes === null) {
-                throw new KeyError("Invalid PKCS #8 key");
+                throw new KeyInputError("Invalid PKCS #8 key");
             }
             const inner = DerCodec.decode(innerBytes);
             const key = getDerKey("PKCS #8", inner?._elements?.[1]);
@@ -331,7 +330,7 @@ namespace Translators {
             // Algorithm
             const algorithm = getDerObjectID("SPKI", algorithmElements?.[0]);
             if (Bytes.toHex(algorithm) !== Asn1ObjectID.ecPublicKey) {
-                throw new KeyError("Unsupported SPKI decryption algorithm");
+                throw new KeyInputError("Unsupported SPKI decryption algorithm");
             }
 
             // Curve
@@ -354,19 +353,19 @@ namespace Translators {
     export const publicBits = {
         set: function (this: Key, input: Uint8Array) {
             if (!(input.length % 2)) {
-                throw new KeyError("Invalid public key encoding");
+                throw new KeyInputError("Invalid public key encoding");
             }
 
             switch (input[0]) {
                 case 2:
                 case 3:
-                    throw new KeyError("Unsupported public key compression");
+                    throw new KeyInputError("Unsupported public key compression");
 
                 case 4:
                     break;
 
                 case 5:
-                    throw new KeyError("Illegal public key format specifier");
+                    throw new KeyInputError("Illegal public key format specifier");
             }
 
             const coordinateLength = (input.length - 1) / 2;
@@ -446,7 +445,7 @@ function inferCurve(key: Key, bytes: number) {
                 break;
 
             default:
-                throw new KeyError(`Cannot infer named curve from key length ${bytes}`);
+                throw new KeyInputError(`Cannot infer named curve from key length ${bytes}`);
         }
     }
 }
@@ -502,7 +501,7 @@ export function Key(properties: Partial<Key>) {
             get: () => {
                 const result = that[target];
                 if (result === undefined) {
-                    throw new KeyError(`Key field ${target} is not defined`);
+                    throw new KeyInputError(`Key field ${target} is not defined`);
                 }
                 return result;
             },
@@ -517,8 +516,8 @@ export function Key(properties: Partial<Key>) {
 
     /** Compute public point from private EC key */
     function derivePublicFromPrivate() {
-        if (that.type !== KeyType.EC) throw new KeyError("EC key type required to compute public point");
-        if (!that.private) throw new KeyError("EC private key required to compute public point");
+        if (that.type !== KeyType.EC) throw new KeyInputError("EC key type required to compute public point");
+        if (!that.private) throw new KeyInputError("EC private key required to compute public point");
 
         const crv = that.crv;
         let keyLength: number;
@@ -532,7 +531,7 @@ export function Key(properties: Partial<Key>) {
                 break;
 
             default:
-                throw new KeyError(`Unsupported elliptic curve ${crv}`);
+                throw new KeyInputError(`Unsupported elliptic curve ${crv}`);
         }
 
         // Compute
@@ -559,7 +558,7 @@ export function Key(properties: Partial<Key>) {
 }
 
 /**
- * Private key factory.
+ * EC private key factory.
  */
 export function PrivateKey(privateKey: Uint8Array | BinaryKeyPair, options?: Partial<Key>) {
     let priv, pub;
@@ -578,7 +577,7 @@ export function PrivateKey(privateKey: Uint8Array | BinaryKeyPair, options?: Par
 }
 
 /**
- * Public key factory.
+ * EC public key factory.
  */
 export function PublicKey(publicKey: Uint8Array, options?: Partial<Key>) {
     return Key({

package/src/crypto/Spake2p.ts

@@ -32,7 +32,7 @@ export class Spake2p {
     static async computeW0W1({ iterations, salt }: PbkdfParameters, pin: number) {
         const pinWriter = new DataWriter(Endian.Little);
         pinWriter.writeUInt32(pin);
-        const ws = await Crypto.pbkdf2(pinWriter.toByteArray(), salt, iterations, CRYPTO_W_SIZE_BYTES * 2);
+        const ws = await Crypto.createPbkdf2Key(pinWriter.toByteArray(), salt, iterations, CRYPTO_W_SIZE_BYTES * 2);
         const w0 = mod(bytesToNumberBE(ws.slice(0, 40)), P256_CURVE.n);
         const w1 = mod(bytesToNumberBE(ws.slice(40, 80)), P256_CURVE.n);
         return { w0, w1 };
@@ -96,12 +96,12 @@ export class Spake2p {
         const Ka = TT_HASH.slice(0, 16);
         const Ke = TT_HASH.slice(16, 32);
 
-        const KcAB = await Crypto.hkdf(Ka, new Uint8Array(0), Bytes.fromString("ConfirmationKeys"), 32);
+        const KcAB = await Crypto.createHkdfKey(Ka, new Uint8Array(0), Bytes.fromString("ConfirmationKeys"), 32);
         const KcA = KcAB.slice(0, 16);
         const KcB = KcAB.slice(16, 32);
 
-        const hAY = await Crypto.hmac(KcA, Y);
-        const hBX = await Crypto.hmac(KcB, X);
+        const hAY = await Crypto.signHmac(KcA, Y);
+        const hBX = await Crypto.signHmac(KcB, X);
 
         return { Ke, hAY, hBX };
     }
@@ -118,7 +118,7 @@ export class Spake2p {
         this.addToContext(TTwriter, Z);
         this.addToContext(TTwriter, V);
         this.addToContext(TTwriter, numberToBytesBE(this.w0, 32));
-        return Crypto.hash(TTwriter.toByteArray());
+        return Crypto.computeSha256(TTwriter.toByteArray());
     }
 
     private addToContext(TTwriter: DataWriter<Endian.Little>, data: Uint8Array) {

package/src/crypto/StandardCrypto.ts

@@ -0,0 +1,252 @@
+/**
+ * @license
+ *
+ * Portions copyright 2022-2023 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DerBigUint, DerCodec, DerError } from "#codec/DerCodec.js";
+import { Boot } from "#util/Boot.js";
+import { Bytes } from "#util/Bytes.js";
+import { Ccm } from "./aes/Ccm.js";
+import { Crypto, CRYPTO_SYMMETRIC_KEY_LENGTH, CryptoDsaEncoding } from "./Crypto.js";
+import { CryptoVerifyError, KeyInputError } from "./CryptoError.js";
+import { CurveType, Key, KeyType, PrivateKey, PublicKey } from "./Key.js";
+
+const subtle = globalThis.crypto.subtle;
+
+const SIGNATURE_ALGORITHM = <EcdsaParams>{
+    name: "ECDSA",
+    namedCurve: "P-256",
+    hash: { name: "SHA-256" },
+};
+
+/**
+ * A {@link Crypto} implementation based on standard "crypto.subtle" with missing portions implemented using JS.
+ *
+ * WARNING: This code is unaudited.  Use a trusted native alternative where available.
+ *
+ * This module is mostly based on  {@link crypto.subtle}.  This should be a reliable native implementation.  However,
+ * Web Crypto doesn't support AES-CCM required by Matter so fall back to a JS implementation for that.  See relevant
+ * warnings in the "aes" subdirectory.
+ */
+export class StandardCrypto implements Crypto {
+    implementationName = "JS";
+
+    static provider() {
+        return new StandardCrypto();
+    }
+
+    getRandomData(length: number): Uint8Array {
+        const result = new Uint8Array(length);
+        crypto.getRandomValues(result);
+        return result;
+    }
+
+    encrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, associatedData?: Uint8Array) {
+        const ccm = Ccm(key);
+        return ccm.encrypt({ pt: data, nonce, adata: associatedData });
+    }
+
+    decrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, associatedData?: Uint8Array) {
+        const ccm = Ccm(key);
+        return ccm.decrypt({ ct: data, nonce, adata: associatedData });
+    }
+
+    async computeSha256(buffer: Uint8Array | Uint8Array[]) {
+        if (Array.isArray(buffer)) {
+            buffer = Bytes.concat(...buffer);
+        }
+        return new Uint8Array(await subtle.digest("SHA-256", buffer));
+    }
+
+    async createPbkdf2Key(secret: Uint8Array, salt: Uint8Array, iteration: number, keyLength: number) {
+        const key = await importKey("raw", secret, "PBKDF2", false, ["deriveBits"]);
+        const bits = await subtle.deriveBits(
+            {
+                name: "PBKDF2",
+                hash: "SHA-256",
+                salt: salt,
+                iterations: iteration,
+            },
+            key,
+            keyLength * 8,
+        );
+        return new Uint8Array(bits);
+    }
+
+    async createHkdfKey(
+        secret: Uint8Array,
+        salt: Uint8Array,
+        info: Uint8Array,
+        length: number = CRYPTO_SYMMETRIC_KEY_LENGTH,
+    ) {
+        const key = await importKey("raw", secret, "HKDF", false, ["deriveBits"]);
+        const bits = await subtle.deriveBits(
+            {
+                name: "HKDF",
+                hash: "SHA-256",
+                salt: salt,
+                info: info,
+            },
+            key,
+            8 * length,
+        );
+        return new Uint8Array(bits);
+    }
+
+    async signHmac(secret: Uint8Array, data: Uint8Array) {
+        const key = await importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        return new Uint8Array(await subtle.sign("HMAC", key, data));
+    }
+
+    async signEcdsa(key: JsonWebKey, data: Uint8Array | Uint8Array[], dsaEncoding?: CryptoDsaEncoding) {
+        if (Array.isArray(data)) {
+            data = Bytes.concat(...data);
+        }
+
+        const { crv, kty, d, x, y } = key;
+
+        key = {
+            kty,
+            crv,
+            d,
+            x,
+            y,
+            ext: true, // Required by some subtle implementations to sign
+            key_ops: ["sign"],
+        };
+
+        const subtleKey = await importKey("jwk", key, SIGNATURE_ALGORITHM, false, ["sign"]);
+
+        const ieeeP1363 = await subtle.sign(SIGNATURE_ALGORITHM, subtleKey, data);
+
+        if (dsaEncoding !== "der") return new Uint8Array(ieeeP1363);
+
+        const bytesPerComponent = ieeeP1363.byteLength / 2;
+
+        return DerCodec.encode({
+            r: DerBigUint(ieeeP1363.slice(0, bytesPerComponent)),
+            s: DerBigUint(ieeeP1363.slice(bytesPerComponent)),
+        });
+    }
+
+    async verifyEcdsa(key: JsonWebKey, data: Uint8Array, signature: Uint8Array, dsaEncoding?: CryptoDsaEncoding) {
+        const { crv, kty, x, y } = key;
+        key = { crv, kty, x, y };
+        const subtleKey = await importKey("jwk", key, SIGNATURE_ALGORITHM, false, ["verify"]);
+
+        if (dsaEncoding === "der") {
+            try {
+                const decoded = DerCodec.decode(signature);
+
+                const r = DerCodec.decodeBigUint(decoded?._elements?.[0], 32);
+                const s = DerCodec.decodeBigUint(decoded?._elements?.[1], 32);
+
+                signature = Bytes.concat(r, s);
+            } catch (cause) {
+                DerError.accept(cause);
+
+                throw new CryptoVerifyError("Invalid DER signature", { cause });
+            }
+        }
+
+        const verified = await subtle.verify(SIGNATURE_ALGORITHM, subtleKey, signature, data);
+
+        if (!verified) {
+            throw new CryptoVerifyError("Signature verification failed");
+        }
+    }
+
+    async createKeyPair() {
+        const subtleKey = await subtle.generateKey(
+            {
+                // We must specify either ECDH or ECDSA to get an EC key but we may use the key for either (but not for
+                // both)
+                name: "ECDH",
+                namedCurve: "P-256",
+            },
+            true,
+
+            // We must also specify usage but will drop this on export
+            ["deriveKey"],
+        );
+
+        // Do not export as JWK because we do not want to inherit the algorithm and key_ops
+        const key = await subtle.exportKey("jwk", subtleKey.privateKey);
+
+        // Extract only private and public fields; we do not want key_ops
+        return Key({
+            kty: KeyType.EC,
+            crv: CurveType.p256,
+            d: key.d,
+            x: key.x,
+            y: key.y,
+        }) as PrivateKey;
+    }
+
+    async generateDhSecret(key: PrivateKey, peerKey: PublicKey) {
+        const subtleKey = await importKey(
+            "jwk",
+            key,
+            {
+                name: "ECDH",
+                namedCurve: "P-256",
+            },
+            false,
+            ["deriveBits"],
+        );
+
+        const subtlePeerKey = await importKey(
+            "jwk",
+            peerKey,
+            {
+                name: "ECDH",
+                namedCurve: "P-256",
+            },
+            false,
+            [],
+        );
+
+        const secret = await subtle.deriveBits(
+            {
+                name: "ECDH",
+                public: subtlePeerKey,
+            },
+            subtleKey,
+            256,
+        );
+
+        return new Uint8Array(secret);
+    }
+}
+
+// Only install if VM supports Web Crypto
+if ((globalThis.crypto as any)?.subtle?.[Symbol.toStringTag] === "SubtleCrypto") {
+    Boot.init(() => {
+        Crypto.provider = StandardCrypto.provider;
+    });
+}
+
+function importKey(
+    format: "jwk",
+    keyData: JsonWebKey,
+    algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm,
+    extractable: boolean,
+    keyUsages: ReadonlyArray<KeyUsage>,
+): Promise<CryptoKey>;
+function importKey(
+    format: Exclude<KeyFormat, "jwk">,
+    keyData: BufferSource,
+    algorithm: AlgorithmIdentifier | RsaHashedImportParams | EcKeyImportParams | HmacImportParams | AesKeyAlgorithm,
+    extractable: boolean,
+    keyUsages: KeyUsage[],
+): Promise<CryptoKey>;
+
+async function importKey(...params: unknown[]) {
+    try {
+        return await crypto.subtle.importKey(...(params as Parameters<SubtleCrypto["importKey"]>));
+    } catch (cause) {
+        throw new KeyInputError("Invalid key", { cause });
+    }
+}

package/src/crypto/aes/Aes.ts

@@ -0,0 +1,210 @@
+/**
+ * @license
+ * Copyright 2022-2025 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * SJCL: https://github.com/bitwiseshiftleft/sjcl/blob/master/core/aes.js
+ *
+ * OpenSSL: https://github.com/openssl/openssl/blob/master/crypto/aes/aes_core.c
+ */
+
+import { WordArray } from "./WordArray.js";
+
+/**
+ * AES core block cipher implementation.
+ *
+ * WARNING: Unaudited.  Consider platform replacement if available.
+ */
+export function Aes(key: Uint8Array) {
+    const { encryptKey, decryptKey } = expandKey(key);
+
+    return {
+        encrypt(pt: WordArray, ct = pt) {
+            return crypt(pt, ct, encryptKey, Tables.enc);
+        },
+
+        decrypt(ct: WordArray, pt = ct) {
+            return crypt(ct, pt, decryptKey, Tables.dec);
+        },
+    };
+}
+
+/**
+ * Precomputed tables for AES algorithm.
+ */
+interface Tables {
+    mix1: WordArray;
+    mix2: WordArray;
+    mix3: WordArray;
+    mix4: WordArray;
+    sbox: WordArray;
+}
+
+let etabs: Tables | undefined, dtabs: Tables | undefined;
+
+const Tables = {
+    get enc() {
+        if (!etabs) {
+            generateTables();
+        }
+        return etabs!;
+    },
+
+    get dec() {
+        if (!dtabs) {
+            generateTables();
+        }
+        return dtabs!;
+    },
+};
+
+const mixNames = ["mix1", "mix2", "mix3", "mix4"] as const;
+
+/**
+ * Generate tables used by {@link crypt}.
+ *
+ * These tables hold static data used during encryption and decryption.
+ */
+function generateTables() {
+    etabs = Tables();
+    dtabs = Tables();
+
+    const d = Table(),
+        th = Table();
+    let i: number, x: number, xInv: number, x2: number, x4: number, x8: number, s: number, tEnc: number, tDec: number;
+
+    for (i = 0; i < 256; i++) {
+        th[(d[i] = (i << 1) ^ ((i >> 7) * 283)) ^ i] = i;
+    }
+
+    for (x = xInv = 0; !etabs.sbox[x]; x ^= x2 || 1, xInv = th[xInv] || 1) {
+        s = xInv ^ (xInv << 1) ^ (xInv << 2) ^ (xInv << 3) ^ (xInv << 4);
+        s = (s >> 8) ^ (s & 255) ^ 99;
+        etabs.sbox[x] = s;
+        dtabs.sbox[s] = x;
+
+        x8 = d[(x4 = d[(x2 = d[x])])];
+        tDec = (x8 * 0x1010101) ^ (x4 * 0x10001) ^ (x2 * 0x101) ^ (x * 0x1010100);
+        tEnc = (d[s] * 0x101) ^ (s * 0x1010100);
+
+        for (const name of mixNames) {
+            etabs[name][x] = tEnc = (tEnc << 24) ^ (tEnc >>> 8);
+            dtabs[name][s] = tDec = (tDec << 24) ^ (tDec >>> 8);
+        }
+    }
+
+    function Tables() {
+        return Object.fromEntries([...mixNames, "sbox"].map(k => [k, Table()])) as unknown as Tables;
+    }
+
+    function Table() {
+        return WordArray(256);
+    }
+}
+
+/**
+ * AES computation.
+ *
+ * Performs encryption/decryption of one or more blocks in {@link data}.
+ *
+ * {@link input} and {@link output} may be the same buffer to operate in place.
+ */
+function crypt(input: WordArray, output: WordArray, roundKeys: WordArray, tabs: Tables) {
+    const decrypt = tabs === dtabs,
+        numRounds = roundKeys.length / 4 - 2;
+
+    // These are the precomputed tables generated in generateTables
+    const { mix1, mix2, mix3, mix4, sbox } = tabs;
+
+    // Allocate working variables for each word in the block
+    let a = input[0] ^ roundKeys[0],
+        b = input[decrypt ? 3 : 1] ^ roundKeys[1],
+        c = input[2] ^ roundKeys[2],
+        d = input[decrypt ? 1 : 3] ^ roundKeys[3],
+        roundKeyAt = 4;
+
+    // Perform computation (sub bytes, shift rows, mix columns & add round key) for each round
+    for (let i = 0; i < numRounds; i++) {
+        // Note that we need to use unsigned bit shift (>>>) for the most significant byte because JS integers are
+        // 32-bit unsigned and the sign will otherwise mess us up
+        const atemp =
+            mix1[a >>> 24] ^ mix2[(b >> 16) & 255] ^ mix3[(c >> 8) & 255] ^ mix4[d & 255] ^ roundKeys[roundKeyAt++];
+        const btemp =
+            mix1[b >>> 24] ^ mix2[(c >> 16) & 255] ^ mix3[(d >> 8) & 255] ^ mix4[a & 255] ^ roundKeys[roundKeyAt++];
+        const ctemp =
+            mix1[c >>> 24] ^ mix2[(d >> 16) & 255] ^ mix3[(a >> 8) & 255] ^ mix4[b & 255] ^ roundKeys[roundKeyAt++];
+        d = mix1[d >>> 24] ^ mix2[(a >> 16) & 255] ^ mix3[(b >> 8) & 255] ^ mix4[c & 255] ^ roundKeys[roundKeyAt++];
+        a = atemp;
+        b = btemp;
+        c = ctemp;
+    }
+
+    // Write working blocks into output buffer
+    for (let i = 0; i < 4; i++) {
+        output[decrypt ? 3 & -i : i] =
+            (sbox[a >>> 24] << 24) ^
+            (sbox[(b >> 16) & 255] << 16) ^
+            (sbox[(c >> 8) & 255] << 8) ^
+            sbox[d & 255] ^
+            roundKeys[roundKeyAt++];
+        const atemp = a;
+        a = b;
+        b = c;
+        c = d;
+        d = atemp;
+    }
+
+    return output;
+}
+
+/**
+ * Schedule the key used for encryption.
+ *
+ * This generates keys for each round based off of the input key.
+ */
+function expandKey(key: Uint8Array) {
+    const inputLength = key.length / 4,
+        roundsNeeded = inputLength + 7,
+        wordsNeeded = roundsNeeded * 4,
+        encryptKey = WordArray.fromByteArray(key, wordsNeeded),
+        sbox = Tables.enc.sbox;
+
+    for (let i = inputLength, rcon = 1; i < wordsNeeded; i++) {
+        let temp = encryptKey[i - 1];
+
+        if (i % inputLength === 0 || (inputLength === 8 && i % inputLength === 4)) {
+            temp =
+                (sbox[temp >>> 24] << 24) ^
+                (sbox[(temp >> 16) & 255] << 16) ^
+                (sbox[(temp >> 8) & 255] << 8) ^
+                sbox[temp & 255];
+
+            if (i % inputLength === 0) {
+                temp = (temp << 8) ^ (temp >>> 24) ^ (rcon << 24);
+                rcon = (rcon << 1) ^ ((rcon >> 7) * 283);
+            }
+        }
+
+        encryptKey[i] = encryptKey[i - inputLength] ^ temp;
+    }
+
+    const { mix1, mix2, mix3, mix4 } = Tables.dec,
+        decryptKey = WordArray(encryptKey.length);
+
+    for (let i = encryptKey.length, j = 0; i; j++, i--) {
+        const tmp = encryptKey[j & 3 ? i : i - 4];
+        if (i <= 4 || j < 4) {
+            decryptKey[j] = tmp;
+        } else {
+            decryptKey[j] =
+                mix1[sbox[tmp >>> 24]] ^
+                mix2[sbox[(tmp >> 16) & 255]] ^
+                mix3[sbox[(tmp >> 8) & 255]] ^
+                mix4[sbox[tmp & 255]];
+        }
+    }
+
+    return { encryptKey, decryptKey };
+}