@matter/general 0.14.1-alpha.0-20250607-a93593303 → 0.15.0-alpha.0-20250612-ddd428561

package/src/codec/DerCodec.ts

@@ -54,7 +54,7 @@ export const DerObject = (objectId: string, content: any = {}) => ({
     [DerKey.ObjectId]: ObjectId(objectId),
     ...content,
 });
-export const BitByteArray = (data: Uint8Array, padding = 0) => ({
+export const DerBitString = (data: Uint8Array, padding = 0) => ({
     [DerKey.TagId]: DerType.BitString as number,
     [DerKey.Bytes]: data,
     [DerKey.BitsPadding]: padding,
@@ -74,6 +74,23 @@ export const DatatypeOverride = (type: DerType, value: any) => ({
 export const RawBytes = (bytes: Uint8Array) => ({
     [DerKey.Bytes]: bytes,
 });
+export const DerBigUint = (number: Uint8Array | ArrayBuffer) => {
+    // We don't need bigint support currently, but we can translate here if we ever do
+
+    if (!ArrayBuffer.isView(number)) {
+        number = new Uint8Array(number);
+    }
+
+    // Ensure value does not encode as negative
+    if ((number as Uint8Array)[0] & 0x80) {
+        number = Bytes.concat(new Uint8Array([0]), number as Uint8Array);
+    }
+
+    return {
+        [DerKey.TagId]: DerType.Integer,
+        [DerKey.Bytes]: number,
+    };
+};
 
 export type DerNode = {
     [DerKey.TagId]: number;
@@ -83,19 +100,19 @@ export type DerNode = {
 };
 
 export class DerCodec {
-    static encode(value: any): Uint8Array {
+    static encode(value: unknown): Uint8Array {
         if (Array.isArray(value)) {
-            return this.encodeArray(value);
+            return this.#encodeArray(value);
         } else if (value instanceof Uint8Array) {
-            return this.encodeOctetString(value);
+            return this.#encodeOctetString(value);
         } else if (value instanceof Date) {
-            return this.encodeDate(value);
+            return this.#encodeDate(value);
         } else if (typeof value === "string") {
-            return this.encodeString(value);
+            return this.#encodeString(value);
         } else if (typeof value === "number" || typeof value === "bigint") {
-            return this.encodeInteger(value);
+            return this.#encodeInteger(value);
         } else if (typeof value === "boolean") {
-            return this.encodeBoolean(value);
+            return this.#encodeBoolean(value);
         } else if (value === undefined) {
             return new Uint8Array(0);
         } else if (isObject(value)) {
@@ -110,7 +127,7 @@ export class DerCodec {
                 if (bytes === undefined || !ArrayBuffer.isView(bytes)) {
                     throw new DerError("DER bytes is not a byte array");
                 }
-                return this.encodeAsn1(
+                return this.#encodeAsn1(
                     tagId,
                     bitsPadding === undefined
                         ? (bytes as Uint8Array)
@@ -118,24 +135,24 @@ export class DerCodec {
                 );
             } else if (value[DerKey.TypeOverride] !== undefined && value[DerKey.RawData] !== undefined) {
                 if (value[DerKey.TypeOverride] === DerType.Integer && value[DerKey.RawData] instanceof Uint8Array) {
-                    return this.encodeInteger(value[DerKey.RawData]);
+                    return this.#encodeInteger(value[DerKey.RawData]);
                 } else if (
                     value[DerKey.TypeOverride] === DerType.BitString &&
                     typeof value[DerKey.RawData] === "number"
                 ) {
-                    return this.encodeBitString(value[DerKey.RawData]);
+                    return this.#encodeBitString(value[DerKey.RawData]);
                 } else if (
                     value[DerKey.TypeOverride] === DerType.PrintableString &&
                     typeof value[DerKey.RawData] === "string"
                 ) {
-                    return this.encodePrintableString(value[DerKey.RawData]);
+                    return this.#encodePrintableString(value[DerKey.RawData]);
                 } else if (
                     value[DerKey.TypeOverride] === DerType.IA5String &&
                     typeof value[DerKey.RawData] === "string"
                 ) {
-                    return this.encodeIA5String(value[DerKey.RawData]);
+                    return this.#encodeIA5String(value[DerKey.RawData]);
                 } else {
-                    throw new UnexpectedDataError(`Unsupported override type ${value[DerKey.TypeOverride]}`);
+                    throw new DerError(`Unsupported override type ${value[DerKey.TypeOverride]}`);
                 }
             } else if (
                 value[DerKey.Bytes] !== undefined &&
@@ -145,19 +162,59 @@ export class DerCodec {
                 // Raw Data
                 return value[DerKey.Bytes];
             } else if (value[DerKey.TypeOverride] === undefined && value[DerKey.Bytes] === undefined) {
-                return this.encodeObject(value);
+                return this.#encodeObject(value);
             } else {
-                throw new UnexpectedDataError(`Unsupported object type ${typeof value}`);
+                throw new DerError(`Unsupported object type ${typeof value}`);
             }
         } else {
-            throw new UnexpectedDataError(`Unsupported type ${typeof value}`);
+            throw new DerError(`Unsupported type ${typeof value}`);
+        }
+    }
+
+    static decode(data: Uint8Array): DerNode {
+        return this.#decodeRec(new DataReader(data));
+    }
+
+    /**
+     * Extract a large integer value to a byte array with a specific number of bytes.
+     */
+    static decodeBigUint(value: DerNode | undefined, byteLength: number) {
+        if (value === undefined) {
+            throw new DerError("Missing number in DER object");
+        }
+
+        if (value[DerKey.TagId] !== DerType.Integer) {
+            throw new DerError(`Expected integer but DER tag is ${DerType[value[DerKey.TagId]]}`);
         }
+
+        const bytes = value[DerKey.Bytes];
+        if (!ArrayBuffer.isView(bytes)) {
+            throw new DerError("Incorrect DER object type");
+        }
+
+        // The common case
+        if (bytes.length === byteLength) {
+            return bytes;
+        }
+
+        // Handle case where single "0" prefix ensures correct sign
+        if (bytes.length === byteLength + 1 && !bytes[0]) {
+            return bytes.slice(1);
+        }
+
+        // Pad out as necessary
+        if (bytes.length < byteLength) {
+            return Bytes.concat(new Uint8Array(byteLength - bytes.length), bytes);
+        }
+
+        // Invalid
+        throw new DerError("Encoded integer contains too many bytes");
     }
 
-    private static encodeDate(date: Date) {
+    static #encodeDate(date: Date) {
         if (date.getFullYear() > 2049) {
             // Dates 2050+ are encoded as GeneralizedTime. This includes the special Non Well Defined date 9999-12-31.
-            return this.encodeAsn1(
+            return this.#encodeAsn1(
                 DerType.GeneralizedTime,
                 Bytes.fromString(
                     date
@@ -166,8 +223,8 @@ export class DerCodec {
                         .slice(0, 14) + "Z",
                 ),
             );
-        } else
-            return this.encodeAsn1(
+        } else {
+            return this.#encodeAsn1(
                 DerType.UtcDate,
                 Bytes.fromString(
                     date
@@ -176,48 +233,49 @@ export class DerCodec {
                         .slice(2, 14) + "Z",
                 ),
             );
+        }
     }
 
-    private static encodeBoolean(bool: boolean) {
-        return this.encodeAsn1(DerType.Boolean, Uint8Array.of(bool ? 0xff : 0));
+    static #encodeBoolean(bool: boolean) {
+        return this.#encodeAsn1(DerType.Boolean, Uint8Array.of(bool ? 0xff : 0));
     }
 
-    private static encodeArray(array: Array<any>) {
-        return this.encodeAsn1(DerType.Set | CONSTRUCTED, Bytes.concat(...array.map(element => this.encode(element))));
+    static #encodeArray(array: Array<any>) {
+        return this.#encodeAsn1(DerType.Set | CONSTRUCTED, Bytes.concat(...array.map(element => this.encode(element))));
     }
 
-    private static encodeOctetString(value: Uint8Array) {
-        return this.encodeAsn1(DerType.OctetString, value);
+    static #encodeOctetString(value: Uint8Array) {
+        return this.#encodeAsn1(DerType.OctetString, value);
     }
 
-    private static encodeObject(object: any) {
+    static #encodeObject(object: any) {
         const attributes = new Array<Uint8Array>();
         for (const key in object) {
             attributes.push(this.encode(object[key]));
         }
-        return this.encodeAsn1(DerType.Sequence | CONSTRUCTED, Bytes.concat(...attributes));
+        return this.#encodeAsn1(DerType.Sequence | CONSTRUCTED, Bytes.concat(...attributes));
     }
 
-    private static encodeString(value: string) {
-        return this.encodeAsn1(DerType.UTF8String, Bytes.fromString(value));
+    static #encodeString(value: string) {
+        return this.#encodeAsn1(DerType.UTF8String, Bytes.fromString(value));
     }
 
-    private static encodePrintableString(value: string) {
+    static #encodePrintableString(value: string) {
         if (!/^[a-z0-9 '()+,\-./:=?]*$/i.test(value)) {
-            throw new UnexpectedDataError(`String ${value} is not a printable string.`);
+            throw new DerError(`String ${value} is not a printable string.`);
         }
-        return this.encodeAsn1(DerType.PrintableString, Bytes.fromString(value));
+        return this.#encodeAsn1(DerType.PrintableString, Bytes.fromString(value));
     }
 
-    private static encodeIA5String(value: string) {
+    static #encodeIA5String(value: string) {
         /*eslint-disable-next-line no-control-regex */
         if (!/^[\x00-\x7F]*$/.test(value)) {
-            throw new UnexpectedDataError(`String ${value} is not an IA5 string.`);
+            throw new DerError(`String ${value} is not an IA5 string.`);
         }
-        return this.encodeAsn1(DerType.IA5String, Bytes.fromString(value));
+        return this.#encodeAsn1(DerType.IA5String, Bytes.fromString(value));
     }
 
-    private static encodeInteger(value: number | bigint | Uint8Array) {
+    static #encodeInteger(value: number | bigint | Uint8Array) {
         const isByteArray = ArrayBuffer.isView(value);
         let valueBytes: Uint8Array;
         if (isByteArray) {
@@ -234,17 +292,17 @@ export class DerCodec {
             start++;
             if (start === byteArray.length - 1) break;
         }
-        return this.encodeAsn1(DerType.Integer, byteArray.slice(start));
+        return this.#encodeAsn1(DerType.Integer, byteArray.slice(start));
     }
 
-    private static encodeBitString(value: number) {
+    static #encodeBitString(value: number) {
         const reversedBits = value.toString(2).padStart(8, "0");
         const unusedBits = reversedBits.indexOf("1");
         const bitByteArray = Uint8Array.of(parseInt(reversedBits.split("").reverse().join(""), 2));
-        return this.encode(BitByteArray(bitByteArray, unusedBits === -1 ? 8 : unusedBits));
+        return this.encode(DerBitString(bitByteArray, unusedBits === -1 ? 8 : unusedBits));
     }
 
-    private static encodeLengthBytes(value: number) {
+    static #encodeLengthBytes(value: number) {
         const byteArray = new Uint8Array(5);
         const dataView = Bytes.dataViewOf(byteArray);
         dataView.setUint32(1, value);
@@ -262,28 +320,24 @@ export class DerCodec {
         return byteArray.slice(start);
     }
 
-    private static encodeAsn1(tag: number, data: Uint8Array) {
-        return Bytes.concat(Uint8Array.of(tag), this.encodeLengthBytes(data.length), data);
-    }
-
-    static decode(data: Uint8Array): DerNode {
-        return this.decodeRec(new DataReader(data));
+    static #encodeAsn1(tag: number, data: Uint8Array) {
+        return Bytes.concat(Uint8Array.of(tag), this.#encodeLengthBytes(data.length), data);
     }
 
-    private static decodeRec(reader: DataReader): DerNode {
-        const { tag, bytes } = this.decodeAsn1(reader);
+    static #decodeRec(reader: DataReader): DerNode {
+        const { tag, bytes } = this.#decodeAsn1(reader);
         if (tag === DerType.BitString)
             return { [DerKey.TagId]: tag, [DerKey.Bytes]: bytes.slice(1), [DerKey.BitsPadding]: bytes[0] };
         if ((tag & CONSTRUCTED) === 0) return { [DerKey.TagId]: tag, [DerKey.Bytes]: bytes };
         const elementsReader = new DataReader(bytes);
         const elements: DerNode[] = [];
         while (elementsReader.remainingBytesCount > 0) {
-            elements.push(this.decodeRec(elementsReader));
+            elements.push(this.#decodeRec(elementsReader));
         }
         return { [DerKey.TagId]: tag, [DerKey.Bytes]: bytes, [DerKey.Elements]: elements };
     }
 
-    private static decodeAsn1(reader: DataReader): { tag: number; bytes: Uint8Array } {
+    static #decodeAsn1(reader: DataReader): { tag: number; bytes: Uint8Array } {
         const tag = reader.readUInt8();
         let length = reader.readUInt8();
         if ((length & 0x80) !== 0) {

package/src/codec/DerTypes.ts

@@ -5,10 +5,10 @@
  */
 
 import {
-    BitByteArray,
     ContextTagged,
     ContextTaggedBytes,
     DatatypeOverride,
+    DerBitString,
     DerCodec,
     DerError,
     DerObject,
@@ -22,7 +22,7 @@ export namespace X962 {
             algorithm: ObjectId("2A8648CE3D0201") /* EC Public Key */,
             curve: ObjectId("2A8648CE3D030107") /* Curve P256_V1 */,
         },
-        bytes: BitByteArray(key),
+        bytes: DerBitString(key),
     });
     export const EcdsaWithSHA256 = DerObject("2A8648CE3D040302");
 }

package/src/crypto/Crypto.ts

@@ -4,15 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Diagnostic } from "#log/Diagnostic.js";
+import { Logger } from "#log/Logger.js";
 import { Boot } from "#util/Boot.js";
 import { MaybePromise } from "#util/Promises.js";
 import * as mod from "@noble/curves/abstract/modular";
 import * as utils from "@noble/curves/abstract/utils";
 import { p256 } from "@noble/curves/p256";
-import { MatterError, NoProviderError } from "../MatterError.js";
+import { NoProviderError } from "../MatterError.js";
 import { Endian } from "../util/Bytes.js";
 import { DataReader } from "../util/DataReader.js";
-import { PrivateKey } from "./Key.js";
+import { PrivateKey, PublicKey } from "./Key.js";
 
 export const ec = {
     p256,
@@ -29,110 +31,228 @@ export const CRYPTO_AUTH_TAG_LENGTH = 16;
 export const CRYPTO_SYMMETRIC_KEY_LENGTH = 16;
 export type CryptoDsaEncoding = "ieee-p1363" | "der";
 
-export class CryptoVerifyError extends MatterError {}
-export class CryptoDecryptError extends MatterError {}
+const logger = Logger.get("Crypto");
 
-export abstract class Crypto {
-    static get: () => Crypto;
-
-    abstract encrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array): Uint8Array;
-    static readonly encrypt = (key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array): Uint8Array =>
-        Crypto.get().encrypt(key, data, nonce, aad);
-
-    abstract decrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array): Uint8Array;
-    static readonly decrypt = (key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array): Uint8Array =>
-        Crypto.get().decrypt(key, data, nonce, aad);
-
-    abstract getRandomData(length: number): Uint8Array;
-    static readonly getRandomData = (length: number): Uint8Array => Crypto.get().getRandomData(length);
-
-    static readonly getRandom = (): Uint8Array => Crypto.get().getRandomData(CRYPTO_RANDOM_LENGTH);
-
-    static readonly getRandomUInt16 = (): number =>
-        new DataReader(Crypto.get().getRandomData(2), Endian.Little).readUInt16();
-
-    static readonly getRandomUInt32 = (): number =>
-        new DataReader(Crypto.get().getRandomData(4), Endian.Little).readUInt32();
-
-    static readonly getRandomBigUInt64 = (): bigint =>
-        new DataReader(Crypto.get().getRandomData(8), Endian.Little).readUInt64();
-
-    static readonly getRandomBigInt = (size: number, maxValue?: bigint): bigint => {
-        const { bytesToNumberBE } = ec;
-        if (maxValue === undefined) {
-            return bytesToNumberBE(Crypto.getRandomData(size));
-        }
-        while (true) {
-            const random = bytesToNumberBE(Crypto.getRandomData(size));
-            if (random < maxValue) return random;
-        }
-    };
+/**
+ * These are the cryptographic primitives required to implement the Matter protocol.
+ *
+ * We provide a platform-independent implementation that uses Web Crypto via {@link crypto.subtle} and a JS-based
+ * AES-CCM implementation.
+ *
+ * If your platform does not fully implement Web Crypto, or offers a native implementation of AES-CCM, you can replace
+ * {@link Crypto.get} to expose a different implementation.
+ *
+ * WARNING: The standard implementation is unaudited.  See relevant warnings in StandardCrypto.ts.
+ */
+export interface Crypto {
+    /**
+     * The name used in log messages.
+     */
+    implementationName: string;
 
-    abstract ecdhGeneratePublicKey(): MaybePromise<{ publicKey: Uint8Array; ecdh: any }>;
-    static readonly ecdhGeneratePublicKey = () => Crypto.get().ecdhGeneratePublicKey();
+    /**
+     * Encrypt using AES-CCM with constants limited to those required by Matter.
+     */
+    encrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array): Uint8Array;
 
-    abstract ecdhGeneratePublicKeyAndSecret(peerPublicKey: Uint8Array): MaybePromise<{
-        publicKey: Uint8Array;
-        sharedSecret: Uint8Array;
-    }>;
-    static readonly ecdhGeneratePublicKeyAndSecret = (peerPublicKey: Uint8Array) =>
-        Crypto.get().ecdhGeneratePublicKeyAndSecret(peerPublicKey);
+    /**
+     * Decrypt using AES-CCM with constants limited to those required by Matter.
+     */
+    decrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array): Uint8Array;
 
-    abstract ecdhGenerateSecret(peerPublicKey: Uint8Array, ecdh: any): MaybePromise<Uint8Array>;
-    static readonly ecdhGenerateSecret = (peerPublicKey: Uint8Array, ecdh: any) =>
-        Crypto.get().ecdhGenerateSecret(peerPublicKey, ecdh);
+    /**
+     * Obtain random bytes from the most cryptographically-appropriate source available.
+     */
+    getRandomData(length: number): Uint8Array;
 
-    abstract hash(data: Uint8Array | Uint8Array[]): MaybePromise<Uint8Array>;
-    static readonly hash = (data: Uint8Array | Uint8Array[]) => Crypto.get().hash(data);
+    /**
+     * Compute the SHA-256 hash of a buffer.
+     */
+    computeSha256(data: Uint8Array | Uint8Array[]): MaybePromise<Uint8Array>;
 
-    abstract pbkdf2(
+    /**
+     * Create a key from a secret using PBKDF2.
+     */
+    createPbkdf2Key(
         secret: Uint8Array,
         salt: Uint8Array,
         iteration: number,
         keyLength: number,
     ): MaybePromise<Uint8Array>;
-    static readonly pbkdf2 = (secret: Uint8Array, salt: Uint8Array, iteration: number, keyLength: number) =>
-        Crypto.get().pbkdf2(secret, salt, iteration, keyLength);
 
-    abstract hkdf(secret: Uint8Array, salt: Uint8Array, info: Uint8Array, length?: number): MaybePromise<Uint8Array>;
-    static readonly hkdf = (secret: Uint8Array, salt: Uint8Array, info: Uint8Array, length?: number) =>
-        Crypto.get().hkdf(secret, salt, info, length);
+    /**
+     * Create a key from a secret using HKDF.
+     */
+    createHkdfKey(secret: Uint8Array, salt: Uint8Array, info: Uint8Array, length?: number): MaybePromise<Uint8Array>;
 
-    abstract hmac(key: Uint8Array, data: Uint8Array): MaybePromise<Uint8Array>;
-    static readonly hmac = (key: Uint8Array, data: Uint8Array) => Crypto.get().hmac(key, data);
+    /**
+     * Create an HMAC signature.
+     */
+    signHmac(key: Uint8Array, data: Uint8Array): MaybePromise<Uint8Array>;
 
-    abstract sign(
+    /**
+     * Create an ECDSA signature.
+     */
+    signEcdsa(
         privateKey: JsonWebKey,
         data: Uint8Array | Uint8Array[],
         dsaEncoding?: CryptoDsaEncoding,
     ): MaybePromise<Uint8Array>;
-    static readonly sign = (privateKey: JsonWebKey, data: Uint8Array | Uint8Array[], dsaEncoding?: CryptoDsaEncoding) =>
-        Crypto.get().sign(privateKey, data, dsaEncoding);
 
-    abstract verify(
+    /**
+     * Authenticate an ECDSA signature.
+     */
+    verifyEcdsa(
         publicKey: JsonWebKey,
         data: Uint8Array,
         signature: Uint8Array,
         dsaEncoding?: CryptoDsaEncoding,
     ): MaybePromise<void>;
-    static readonly verify = (
-        publicKey: JsonWebKey,
-        data: Uint8Array,
-        signature: Uint8Array,
-        dsaEncoding?: CryptoDsaEncoding,
-    ) => Crypto.get().verify(publicKey, data, signature, dsaEncoding);
 
-    abstract createKeyPair(): MaybePromise<PrivateKey>;
-    static readonly createKeyPair = () => Crypto.get().createKeyPair();
+    /**
+     * Create a general-purpose EC key.
+     */
+    createKeyPair(): MaybePromise<PrivateKey>;
+
+    /**
+     * Compute the shared secret for a Diffie-Hellman exchange.
+     */
+    generateDhSecret(key: PrivateKey, peerKey: PublicKey): MaybePromise<Uint8Array>;
 }
 
+let logImplementationName = true;
+let defaultInstance: undefined | Crypto;
+let defaultProvider: undefined | (() => Crypto);
+
+/**
+ * Crypto support functions.
+ */
+export const Crypto = {
+    /**
+     * The default crypto implementation.
+     */
+    get default() {
+        if (defaultInstance) {
+            return defaultInstance;
+        }
+
+        if (defaultProvider === undefined) {
+            throw new NoProviderError("There is no cryptography implementation installed");
+        }
+
+        defaultInstance = defaultProvider();
+
+        if (logImplementationName) {
+            logger.debug("Using", Diagnostic.strong(defaultInstance.implementationName), "cryptography implementation");
+        }
+
+        return defaultInstance;
+    },
+
+    get provider(): undefined | (() => Crypto) {
+        return defaultProvider;
+    },
+
+    /**
+     * Set the default crypto provider.
+     */
+    set provider(provider: () => Crypto) {
+        if (defaultProvider === provider) {
+            return;
+        }
+        defaultProvider = undefined;
+        defaultProvider = provider;
+    },
+
+    get implementationName() {
+        return Crypto.default.implementationName;
+    },
+
+    encrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array) {
+        return Crypto.default.encrypt(key, data, nonce, aad);
+    },
+
+    decrypt(key: Uint8Array, data: Uint8Array, nonce: Uint8Array, aad?: Uint8Array) {
+        return Crypto.default.decrypt(key, data, nonce, aad);
+    },
+
+    getRandomData(length: number) {
+        return Crypto.default.getRandomData(length);
+    },
+
+    getRandom() {
+        return Crypto.default.getRandomData(CRYPTO_RANDOM_LENGTH);
+    },
+
+    getRandomUInt16() {
+        return new DataReader(Crypto.default.getRandomData(2), Endian.Little).readUInt16();
+    },
+
+    getRandomUInt32() {
+        return new DataReader(Crypto.default.getRandomData(4), Endian.Little).readUInt32();
+    },
+
+    getRandomBigUInt64() {
+        return new DataReader(Crypto.default.getRandomData(8), Endian.Little).readUInt64();
+    },
+
+    getRandomBigInt(size: number, maxValue?: bigint) {
+        const { bytesToNumberBE } = ec;
+        if (maxValue === undefined) {
+            return bytesToNumberBE(Crypto.getRandomData(size));
+        }
+        while (true) {
+            const random = bytesToNumberBE(Crypto.getRandomData(size));
+            if (random < maxValue) return random;
+        }
+    },
+
+    computeSha256(data: Uint8Array | Uint8Array[]) {
+        return Crypto.default.computeSha256(data);
+    },
+
+    createPbkdf2Key(secret: Uint8Array, salt: Uint8Array, iteration: number, keyLength: number) {
+        return Crypto.default.createPbkdf2Key(secret, salt, iteration, keyLength);
+    },
+
+    createHkdfKey(secret: Uint8Array, salt: Uint8Array, info: Uint8Array, length?: number) {
+        return Crypto.default.createHkdfKey(secret, salt, info, length);
+    },
+
+    signHmac(key: Uint8Array, data: Uint8Array) {
+        return Crypto.default.signHmac(key, data);
+    },
+
+    signEcdsa(privateKey: JsonWebKey, data: Uint8Array | Uint8Array[], dsaEncoding?: CryptoDsaEncoding) {
+        return Crypto.default.signEcdsa(privateKey, data, dsaEncoding);
+    },
+
+    verifyEcdsa(publicKey: JsonWebKey, data: Uint8Array, signature: Uint8Array, dsaEncoding?: CryptoDsaEncoding) {
+        return Crypto.default.verifyEcdsa(publicKey, data, signature, dsaEncoding);
+    },
+
+    createKeyPair() {
+        return Crypto.default.createKeyPair();
+    },
+
+    generateDhSecret(key: PrivateKey, peerKey: PublicKey) {
+        return Crypto.default.generateDhSecret(key, peerKey);
+    },
+};
+
+Crypto satisfies Crypto;
+
 Boot.init(() => {
-    Crypto.get = () => {
-        throw new NoProviderError("No provider configured");
-    };
+    logImplementationName = true;
+    defaultInstance = undefined;
+    defaultProvider = undefined;
 
-    // Hook for testing frameworks
+    // Testing framework configuration
     if (typeof MatterHooks !== "undefined") {
+        // Crypto access occurs before log messages are intercepted so do not log implementation in test environment
+        logImplementationName = true;
+
+        // Configure mocking
         MatterHooks.cryptoSetup?.(Crypto);
     }
 });

package/src/crypto/CryptoError.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2025 Project CHIP Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterError } from "#MatterError.js";
+
+/**
+ * Errors thrown by crypto implementations.
+ */
+export class CryptoError extends MatterError {}
+
+/**
+ * Thrown when a crypto algorithm encounters invalid input.
+ */
+export class CryptoInputError extends MatterError {}
+
+/**
+ * Thrown when verification fails.
+ */
+export class CryptoVerifyError extends CryptoError {}
+
+/**
+ * Thrown when decryption fails.
+ */
+export class CryptoDecryptError extends CryptoError {}
+
+/**
+ * Thrown when cryptographic key parameters are invalid.
+ */
+export class KeyInputError extends CryptoInputError {}