@matter/general 0.16.0-alpha.0-20251111-11cc8c3bd → 0.16.0-alpha.0-20251112-dba1973d5

package/src/crypto/Crypto.ts

@@ -13,6 +13,7 @@ import * as mod from "@noble/curves/abstract/modular.js";
 import { p256 } from "@noble/curves/nist.js";
 import * as utils from "@noble/curves/utils.js";
 import { Entropy } from "../util/Entropy.js";
+import { EcdsaSignature } from "./EcdsaSignature.js";
 import type { PrivateKey, PublicKey } from "./Key.js";
 
 export const ec = {
@@ -27,7 +28,6 @@ export const CRYPTO_EC_CURVE = "prime256v1";
 export const CRYPTO_EC_KEY_BYTES = 32;
 export const CRYPTO_AUTH_TAG_LENGTH = 16;
 export const CRYPTO_SYMMETRIC_KEY_LENGTH = 16;
-export type CryptoDsaEncoding = "ieee-p1363" | "der";
 
 const logger = Logger.get("Crypto");
 
@@ -83,21 +83,12 @@ export abstract class Crypto extends Entropy {
     /**
      * Create an ECDSA signature.
      */
-    abstract signEcdsa(
-        privateKey: JsonWebKey,
-        data: Bytes | Bytes[],
-        dsaEncoding?: CryptoDsaEncoding,
-    ): MaybePromise<Bytes>;
+    abstract signEcdsa(privateKey: JsonWebKey, data: Bytes | Bytes[]): MaybePromise<EcdsaSignature>;
 
     /**
      * Authenticate an ECDSA signature.
      */
-    abstract verifyEcdsa(
-        publicKey: JsonWebKey,
-        data: Bytes,
-        signature: Bytes,
-        dsaEncoding?: CryptoDsaEncoding,
-    ): MaybePromise<void>;
+    abstract verifyEcdsa(publicKey: JsonWebKey, data: Bytes, signature: EcdsaSignature): MaybePromise<void>;
 
     /**
      * Create a general-purpose EC key.

package/src/crypto/CryptoError.ts

@@ -30,3 +30,8 @@ export class CryptoDecryptError extends CryptoError {}
  * Thrown when cryptographic key parameters are invalid.
  */
 export class KeyInputError extends CryptoInputError {}
+
+/**
+ * Thrown when verification fails because of an invalid signature format.
+ */
+export class SignatureEncodingError extends CryptoVerifyError {}

package/src/crypto/EcdsaSignature.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DerCodec, DerError, DerRawUint } from "#codec/DerCodec.js";
+import { Bytes } from "#util/Bytes.js";
+import { SignatureEncodingError } from "./CryptoError.js";
+
+/**
+ * An ECDSA signature.
+ *
+ * Input and output may be IEEE-P1363 or DER encoded.  Matter helpfully mixes and matches so we validate input to ensure
+ * the correct encoding is specified.  Extraction to bytes must explicitly use {@link bytes} or {@link der} to specify
+ * the desired format.
+ *
+ * Currently we only support 256-bit curves.
+ */
+export class EcdsaSignature {
+    #bytes: Bytes;
+
+    constructor(bytes: Bytes, encoding = "ieee-p1363") {
+        if (encoding === "der") {
+            try {
+                const decoded = DerCodec.decode(bytes);
+
+                const r = DerCodec.decodeBigUint(decoded?._elements?.[0], 32);
+                const s = DerCodec.decodeBigUint(decoded?._elements?.[1], 32);
+
+                this.#bytes = Bytes.concat(r, s);
+            } catch (cause) {
+                DerError.accept(cause);
+
+                throw new SignatureEncodingError("Could not decode DER signature", { cause });
+            }
+        } else {
+            // Change this if/when we support more curves
+            if (bytes.byteLength !== 64) {
+                throw new SignatureEncodingError("Invalid IEEE P1364 signature length");
+            }
+            this.#bytes = bytes;
+        }
+    }
+
+    /**
+     * Access signature in IEEE P1363 format.
+     */
+    get bytes() {
+        return this.#bytes;
+    }
+
+    /**
+     * Access signature in DER format.
+     */
+    get der() {
+        const bytes = Bytes.of(this.#bytes);
+        const bytesPerComponent = bytes.length / 2;
+
+        return DerCodec.encode({
+            r: DerRawUint(bytes.slice(0, bytesPerComponent)),
+            s: DerRawUint(bytes.slice(bytesPerComponent)),
+        });
+    }
+}
+
+export namespace EcdsaSignature {
+    /**
+     * IEEE P1363 encoding.
+     *
+     * This is a simple concatenation of the raw R and S elements
+     */
+    export const IEEE_P1363 = "ieee-p1363";
+
+    /**
+     * DER encoding.
+     *
+     * This encodes R and S elements in a sequence of separate integers.
+     */
+    export const DER = "der";
+
+    export type Encoding = typeof IEEE_P1363 | typeof DER;
+}

package/src/crypto/NodeJsStyleCrypto.ts

@@ -17,9 +17,9 @@ import {
     CRYPTO_ENCRYPT_ALGORITHM,
     CRYPTO_HASH_ALGORITHM,
     CRYPTO_SYMMETRIC_KEY_LENGTH,
-    CryptoDsaEncoding,
 } from "./Crypto.js";
 import { CryptoDecryptError, CryptoVerifyError } from "./CryptoError.js";
+import { EcdsaSignature } from "./EcdsaSignature.js";
 import { PrivateKey, PublicKey } from "./Key.js";
 
 // Note that this is a type-only import, not a runtime dependency.
@@ -179,24 +179,26 @@ export class NodeJsStyleCrypto extends Crypto {
         return Bytes.of(hmac.digest());
     }
 
-    signEcdsa(privateKey: JsonWebKey, data: Bytes | Bytes[], dsaEncoding: CryptoDsaEncoding = "ieee-p1363"): Bytes {
+    signEcdsa(privateKey: JsonWebKey, data: Bytes | Bytes[]) {
         const signer = this.#crypto.createSign(CRYPTO_HASH_ALGORITHM);
         if (Array.isArray(data)) {
             data.forEach(chunk => signer.update(Bytes.of(chunk)));
         } else {
             signer.update(Bytes.of(data));
         }
-        return Bytes.of(
-            signer.sign({
-                key: privateKey as any,
-                format: "jwk",
-                type: "pkcs8",
-                dsaEncoding,
-            }),
+        return new EcdsaSignature(
+            Bytes.of(
+                signer.sign({
+                    key: privateKey as any,
+                    format: "jwk",
+                    type: "pkcs8",
+                    dsaEncoding: "ieee-p1363",
+                }),
+            ),
         );
     }
 
-    verifyEcdsa(publicKey: JsonWebKey, data: Bytes, signature: Bytes, dsaEncoding: CryptoDsaEncoding = "ieee-p1363") {
+    verifyEcdsa(publicKey: JsonWebKey, data: Bytes, signature: EcdsaSignature) {
         const verifier = this.#crypto.createVerify(CRYPTO_HASH_ALGORITHM);
         verifier.update(Bytes.of(data));
         const success = verifier.verify(
@@ -204,9 +206,9 @@ export class NodeJsStyleCrypto extends Crypto {
                 key: publicKey as any,
                 format: "jwk",
                 type: "spki",
-                dsaEncoding,
+                dsaEncoding: "ieee-p1363",
             },
-            Bytes.of(signature),
+            Bytes.of(signature.bytes),
         );
         if (!success) throw new CryptoVerifyError("Signature verification failed");
     }

package/src/crypto/StandardCrypto.ts

@@ -5,7 +5,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { DerBigUint, DerCodec, DerError } from "#codec/DerCodec.js";
 import { Environment } from "#environment/Environment.js";
 import { ImplementationError, NotImplementedError } from "#MatterError.js";
 import { Bytes } from "#util/Bytes.js";
@@ -13,8 +12,9 @@ import { Entropy } from "#util/Entropy.js";
 import { MaybePromise } from "#util/Promises.js";
 import { describeList } from "#util/String.js";
 import { Ccm } from "./aes/Ccm.js";
-import { Crypto, CRYPTO_SYMMETRIC_KEY_LENGTH, CryptoDsaEncoding } from "./Crypto.js";
+import { Crypto, CRYPTO_SYMMETRIC_KEY_LENGTH } from "./Crypto.js";
 import { CryptoVerifyError, KeyInputError } from "./CryptoError.js";
+import { EcdsaSignature } from "./EcdsaSignature.js";
 import { CurveType, Key, KeyType, PrivateKey, PublicKey } from "./Key.js";
 import { WebCrypto } from "./WebCrypto.js";
 
@@ -146,7 +146,7 @@ export class StandardCrypto extends Crypto {
         );
     }
 
-    async signEcdsa(key: JsonWebKey, data: Bytes | Bytes[], dsaEncoding?: CryptoDsaEncoding) {
+    async signEcdsa(key: JsonWebKey, data: Bytes | Bytes[]) {
         if (Array.isArray(data)) {
             data = Bytes.concat(...data);
         }
@@ -167,40 +167,18 @@ export class StandardCrypto extends Crypto {
 
         const ieeeP1363 = Bytes.of(await this.#subtle.sign(SIGNATURE_ALGORITHM, subtleKey, Bytes.exclusive(data)));
 
-        if (dsaEncoding !== "der") return ieeeP1363;
-
-        const bytesPerComponent = ieeeP1363.byteLength / 2;
-
-        return DerCodec.encode({
-            r: DerBigUint(ieeeP1363.slice(0, bytesPerComponent)),
-            s: DerBigUint(ieeeP1363.slice(bytesPerComponent)),
-        });
+        return new EcdsaSignature(ieeeP1363);
     }
 
-    async verifyEcdsa(key: JsonWebKey, data: Bytes, signature: Bytes, dsaEncoding?: CryptoDsaEncoding) {
+    async verifyEcdsa(key: JsonWebKey, data: Bytes, signature: EcdsaSignature) {
         const { crv, kty, x, y } = key;
         key = { crv, kty, x, y };
         const subtleKey = await this.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 this.#subtle.verify(
             SIGNATURE_ALGORITHM,
             subtleKey,
-            Bytes.exclusive(signature),
+            Bytes.exclusive(signature.bytes),
             Bytes.exclusive(data),
         );
 

package/src/crypto/index.ts

@@ -7,6 +7,7 @@
 export * from "./Crypto.js";
 export * from "./CryptoConstants.js";
 export * from "./CryptoError.js";
+export * from "./EcdsaSignature.js";
 export * from "./Key.js";
 export * from "./MockCrypto.js";
 export * from "./NodeJsStyleCrypto.js";