@matter/protocol 0.15.0-alpha.0-20250616-4b3754906 → 0.15.0-alpha.0-20250619-df2264f15

package/src/certificate/kinds/X509Base.ts

@@ -0,0 +1,380 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Bytes,
+    ContextTagged,
+    Crypto,
+    DatatypeOverride,
+    DerBitString,
+    DerCodec,
+    DerKey,
+    DerType,
+    Key,
+    PublicKey,
+    RawBytes,
+    X509,
+    X520,
+    X962,
+} from "#general";
+import { CaseAuthenticatedTag, FabricId, NodeId, TypeFromPartialBitSchema, VendorId } from "#types";
+import { assertCertificateDerSize, CertificateError, Unsigned } from "./common.js";
+import {
+    FabricId_Matter,
+    FirmwareSigningId_Matter,
+    IcacId_Matter,
+    matterToJsDate,
+    NocCat_Matter,
+    NodeId_Matter,
+    ProductId_Matter,
+    RcacId_Matter,
+    VendorId_Matter,
+} from "./definitions/asn.js";
+import { ExtensionKeyUsageBitmap, ExtensionKeyUsageSchema, X509Certificate } from "./definitions/base.js";
+import { CertificateExtension } from "./definitions/operational.js";
+
+/**
+ * Abstract definition of a X.509 certificate that can be signed and converted to ASN.1 DER format.
+ * It also provides two static methods to create a certificate signing request (CSR) and to extract the public key
+ * from a CSR.
+ */
+export abstract class X509Base<CT extends X509Certificate> {
+    #signature?: Uint8Array;
+    #cert: Unsigned<CT>;
+
+    constructor(cert: CT | Unsigned<CT>) {
+        this.#cert = cert;
+        if ("signature" in cert) {
+            this.#signature = cert.signature;
+        }
+    }
+
+    get cert(): Unsigned<CT> {
+        return this.#cert;
+    }
+
+    get isSigned() {
+        return this.#signature !== undefined;
+    }
+
+    /**
+     * Get the signature of the certificate.
+     * If the certificate is not signed, it throws a CertificateError.
+     */
+    get signature() {
+        if (this.#signature === undefined) {
+            throw new CertificateError("Certificate is not signed");
+        }
+        return this.#signature;
+    }
+
+    /**
+     * Set the signature of the certificate.
+     * If the certificate is already signed, it throws a CertificateError.
+     */
+    set signature(signature: Uint8Array) {
+        if (this.isSigned) {
+            throw new CertificateError("Certificate is already signed");
+        }
+        this.#signature = signature;
+    }
+
+    /**
+     * Sign the certificate using the provided crypto and key.
+     * It throws a CertificateError if the certificate is already signed.
+     */
+    async sign(crypto: Crypto, key: JsonWebKey) {
+        this.signature = await crypto.signEcdsa(key, this.asUnsignedAsn1());
+    }
+
+    /**
+     * Convert the certificate to ASN.1 DER format without signature.
+     */
+    asUnsignedAsn1(): Uint8Array<ArrayBufferLike> {
+        const certBytes = DerCodec.encode(this.genericBuildAsn1Structure(this.cert));
+        assertCertificateDerSize(certBytes);
+        return certBytes;
+    }
+
+    /**
+     * Convert the subject or issuer field of the certificate to ASN.1 DER format.
+     * Preserve order of keys from original subject and also copy potential custom elements
+     */
+    #subjectOrIssuerToAsn1(data: { [field: string]: any }) {
+        const asn = {} as { [field: string]: any[] };
+        Object.entries(data).forEach(([key, value]) => {
+            if (value === undefined) {
+                return;
+            }
+            switch (key) {
+                case "commonName":
+                    asn.commonName = X520.CommonName(value as string);
+                    break;
+                case "sureName":
+                    asn.sureName = X520.SurName(value as string);
+                    break;
+                case "serialNum":
+                    asn.serialNum = X520.SerialNumber(value as string);
+                    break;
+                case "countryName":
+                    asn.countryName = X520.CountryName(value as string);
+                    break;
+                case "localityName":
+                    asn.localityName = X520.LocalityName(value as string);
+                    break;
+                case "stateOrProvinceName":
+                    asn.stateOrProvinceName = X520.StateOrProvinceName(value as string);
+                    break;
+                case "orgName":
+                    asn.orgName = X520.OrganisationName(value as string);
+                    break;
+                case "orgUnitName":
+                    asn.orgUnitName = X520.OrganizationalUnitName(value as string);
+                    break;
+                case "title":
+                    asn.title = X520.Title(value as string);
+                    break;
+                case "name":
+                    asn.name = X520.Name(value as string);
+                    break;
+                case "givenName":
+                    asn.givenName = X520.GivenName(value as string);
+                    break;
+                case "initials":
+                    asn.initials = X520.Initials(value as string);
+                    break;
+                case "genQualifier":
+                    asn.genQualifier = X520.GenerationQualifier(value as string);
+                    break;
+                case "dnQualifier":
+                    asn.dnQualifier = X520.DnQualifier(value as string);
+                    break;
+                case "pseudonym":
+                    asn.pseudonym = X520.Pseudonym(value as string);
+                    break;
+                case "domainComponent":
+                    asn.domainComponent = X520.DomainComponent(value as string);
+                    break;
+                case "nodeId":
+                    asn.nodeId = NodeId_Matter(value as NodeId);
+                    break;
+                case "firmwareSigningId":
+                    asn.firmwareSigningId = FirmwareSigningId_Matter(value as number);
+                    break;
+                case "icacId":
+                    asn.icacId = IcacId_Matter(value as number | bigint);
+                    break;
+                case "rcacId":
+                    asn.rcacId = RcacId_Matter(value as number | bigint);
+                    break;
+                case "fabricId":
+                    asn.fabricId = FabricId_Matter(value as FabricId);
+                    break;
+                case "caseAuthenticatedTags":
+                    // In theory if someone mixes multiple caseAuthenticatedTag fields with other fields we currently would
+                    // code them in ASN.1 as fields at the first position from the original data which might fail
+                    // certificate validation. Changing this would require to change Tlv decoding, so lets try that way for now.
+                    const caseAuthenticatedTags = value as CaseAuthenticatedTag[];
+                    CaseAuthenticatedTag.validateNocTagList(caseAuthenticatedTags);
+
+                    const cat0 = caseAuthenticatedTags[0];
+                    const cat1 = caseAuthenticatedTags[1];
+                    const cat2 = caseAuthenticatedTags[2];
+                    if (cat0 !== undefined) {
+                        asn.caseAuthenticatedTag0 = NocCat_Matter(cat0);
+                    }
+                    if (cat1 !== undefined) {
+                        asn.caseAuthenticatedTag1 = NocCat_Matter(cat1);
+                    }
+                    if (cat2 !== undefined) {
+                        asn.caseAuthenticatedTag2 = NocCat_Matter(cat2);
+                    }
+                    break;
+                case "vendorId": // Only relevant for ASN.1 encoding of DAC/PAA/PAI certificates
+                    asn.vendorId = VendorId_Matter(value as VendorId);
+                    break;
+                case "productId": // Only relevant for ASN.1 encoding of DAC/PAA/PAI certificates
+                    asn.productId = ProductId_Matter(value as number);
+                    break;
+                case "commonNamePs":
+                    asn.commonNamePs = X520.CommonName(value as string, true);
+                    break;
+                case "sureNamePs":
+                    asn.sureNamePs = X520.SurName(value as string, true);
+                    break;
+                case "serialNumPs":
+                    asn.serialNumPs = X520.SerialNumber(value as string, true);
+                    break;
+                case "countryNamePs":
+                    asn.countryNamePs = X520.CountryName(value as string, true);
+                    break;
+                case "localityNamePs":
+                    asn.localityNamePs = X520.LocalityName(value as string, true);
+                    break;
+                case "stateOrProvinceNamePs":
+                    asn.stateOrProvinceNamePs = X520.StateOrProvinceName(value as string, true);
+                    break;
+                case "orgNamePs":
+                    asn.orgNamePs = X520.OrganisationName(value as string, true);
+                    break;
+                case "orgUnitNamePs":
+                    asn.orgUnitNamePs = X520.OrganizationalUnitName(value as string, true);
+                    break;
+                case "titlePs":
+                    asn.titlePs = X520.Title(value as string, true);
+                    break;
+                case "namePs":
+                    asn.namePs = X520.Name(value as string, true);
+                    break;
+                case "givenNamePs":
+                    asn.givenNamePs = X520.GivenName(value as string, true);
+                    break;
+                case "initialsPs":
+                    asn.initialsPs = X520.Initials(value as string, true);
+                    break;
+                case "genQualifierPs":
+                    asn.genQualifierPs = X520.GenerationQualifier(value as string, true);
+                    break;
+                case "dnQualifierPs":
+                    asn.dnQualifierPs = X520.DnQualifier(value as string, true);
+                    break;
+                case "pseudonymPs":
+                    asn.pseudonymPs = X520.Pseudonym(value as string, true);
+                    break;
+            }
+        });
+        return asn;
+    }
+
+    /**
+     * Convert the extensions of the certificate to ASN.1 DER format.
+     */
+    #extensionsToAsn1(extensions: CertificateExtension) {
+        const asn = {} as { [field: string]: any[] | any };
+        Object.entries(extensions).forEach(([key, value]) => {
+            if (value === undefined) {
+                return;
+            }
+            switch (key) {
+                case "basicConstraints":
+                    asn.basicConstraints = X509.BasicConstraints(value);
+                    break;
+                case "keyUsage":
+                    asn.keyUsage = X509.KeyUsage(
+                        ExtensionKeyUsageSchema.encode(
+                            value as TypeFromPartialBitSchema<typeof ExtensionKeyUsageBitmap>,
+                        ),
+                    );
+                    break;
+                case "extendedKeyUsage":
+                    asn.extendedKeyUsage = X509.ExtendedKeyUsage(value as number[] | undefined);
+                    break;
+                case "subjectKeyIdentifier":
+                    asn.subjectKeyIdentifier = X509.SubjectKeyIdentifier(value as Uint8Array);
+                    break;
+                case "authorityKeyIdentifier":
+                    asn.authorityKeyIdentifier = X509.AuthorityKeyIdentifier(value as Uint8Array);
+                    break;
+                case "futureExtension":
+                    asn.futureExtension = RawBytes(Bytes.concat(...((value as Uint8Array[] | undefined) ?? [])));
+                    break;
+            }
+        });
+        return asn;
+    }
+
+    /**
+     * Build the ASN.1 DER structure for the certificate.
+     */
+    protected genericBuildAsn1Structure({
+        serialNumber,
+        notBefore,
+        notAfter,
+        issuer,
+        subject,
+        ellipticCurvePublicKey,
+        extensions,
+    }: Unsigned<CT>) {
+        const {
+            basicConstraints: { isCa, pathLen },
+        } = extensions;
+        if (!isCa && pathLen !== undefined) {
+            throw new CertificateError("Path length must be undefined for non-CA certificates.");
+        }
+        return {
+            version: ContextTagged(0, 2), // v3
+            serialNumber: DatatypeOverride(DerType.Integer, serialNumber),
+            signatureAlgorithm: X962.EcdsaWithSHA256,
+            issuer: this.#subjectOrIssuerToAsn1(issuer),
+            validity: {
+                notBefore: matterToJsDate(notBefore),
+                notAfter: matterToJsDate(notAfter),
+            },
+            subject: this.#subjectOrIssuerToAsn1(subject),
+            publicKey: X962.PublicKeyEcPrime256v1(ellipticCurvePublicKey),
+            extensions: ContextTagged(3, this.#extensionsToAsn1(extensions)),
+        };
+    }
+
+    /**
+     * Create a Certificate Signing Request (CSR) in ASN.1 DER format.
+     */
+    static async createCertificateSigningRequest(crypto: Crypto, key: Key) {
+        const request = {
+            version: 0,
+            subject: { organization: X520.OrganisationName("CSR") },
+            publicKey: X962.PublicKeyEcPrime256v1(key.publicKey),
+            endSignedBytes: ContextTagged(0),
+        };
+
+        return DerCodec.encode({
+            request,
+            signAlgorithm: X962.EcdsaWithSHA256,
+            signature: DerBitString(await crypto.signEcdsa(key, DerCodec.encode(request), "der")),
+        });
+    }
+
+    /**
+     * Extract the public key from a Certificate Signing Request (CSR) in ASN.1 DER format.
+     */
+    static async getPublicKeyFromCsr(crypto: Crypto, csr: Uint8Array) {
+        const { [DerKey.Elements]: rootElements } = DerCodec.decode(csr);
+        if (rootElements?.length !== 3) throw new CertificateError("Invalid CSR data");
+        const [requestNode, signAlgorithmNode, signatureNode] = rootElements;
+
+        // Extract the public key
+        const { [DerKey.Elements]: requestElements } = requestNode;
+        if (requestElements?.length !== 4) throw new CertificateError("Invalid CSR data");
+        const [versionNode, _subjectNode, publicKeyNode] = requestElements;
+        const requestVersion = versionNode[DerKey.Bytes][0];
+        if (requestVersion !== 0) throw new CertificateError(`Unsupported request version ${requestVersion}`);
+        // TODO: verify subject = { OrganisationName: "CSR" }
+
+        const { [DerKey.Elements]: publicKeyElements } = publicKeyNode;
+        if (publicKeyElements?.length !== 2) throw new CertificateError("Invalid CSR data");
+        const [_publicKeyTypeNode, publicKeyBytesNode] = publicKeyElements;
+        // TODO: verify publicKey algorithm
+        const publicKey = publicKeyBytesNode[DerKey.Bytes];
+
+        // Verify the CSR signature
+        if (
+            signAlgorithmNode[DerKey.Elements]?.[0]?.[DerKey.Bytes] === undefined ||
+            !Bytes.areEqual(
+                X962.EcdsaWithSHA256[DerKey.ObjectId][DerKey.Bytes],
+                signAlgorithmNode[DerKey.Elements]?.[0]?.[DerKey.Bytes],
+            )
+        )
+            throw new CertificateError("Unsupported signature type");
+        await crypto.verifyEcdsa(
+            PublicKey(publicKey),
+            DerCodec.encode(requestNode),
+            signatureNode[DerKey.Bytes],
+            "der",
+        );
+
+        return publicKey;
+    }
+}

package/src/certificate/kinds/common.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ImplementationError, MatterError } from "#general";
+
+/**
+ * Matter specific Certificate Sizes
+ * @see {@link MatterSpecification.v13.Core} 6.1.3.
+ */
+export const MAX_DER_CERTIFICATE_SIZE = 600;
+
+export class CertificateError extends MatterError {}
+
+export type Unsigned<Type> = { [Property in keyof Type as Exclude<Property, "signature">]: Type[Property] };
+
+export function assertCertificateDerSize(certBytes: Uint8Array) {
+    if (certBytes.length > MAX_DER_CERTIFICATE_SIZE) {
+        throw new ImplementationError(
+            `Certificate to generate is too big: ${certBytes.length} bytes instead of max ${MAX_DER_CERTIFICATE_SIZE} bytes`,
+        );
+    }
+}

package/src/certificate/kinds/definitions/asn.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, DerObject, X520 } from "#general";
+import { FabricId, NodeId, VendorId } from "#types";
+
+const YEAR_S = 365 * 24 * 60 * 60;
+const EPOCH_OFFSET_S = 10957 * 24 * 60 * 60;
+
+// TODO replace usage of Date by abstraction
+
+export function matterToJsDate(date: number) {
+    return date === 0 ? X520.NON_WELL_DEFINED_DATE : new Date((date + EPOCH_OFFSET_S) * 1000);
+}
+
+export function jsToMatterDate(date: Date, addYears = 0) {
+    return date.getTime() === X520.NON_WELL_DEFINED_DATE.getTime()
+        ? 0
+        : Math.floor(date.getTime() / 1000) - EPOCH_OFFSET_S + addYears * YEAR_S;
+}
+
+function intTo16Chars(value: bigint | number) {
+    const byteArray = new Uint8Array(8);
+    const dataView = Bytes.dataViewOf(byteArray);
+    dataView.setBigUint64(0, typeof value === "bigint" ? value : BigInt(value));
+    return Bytes.toHex(byteArray).toUpperCase();
+}
+
+function uInt16To8Chars(value: number) {
+    const byteArray = new Uint8Array(4);
+    const dataView = Bytes.dataViewOf(byteArray);
+    dataView.setUint32(0, value);
+    return Bytes.toHex(byteArray).toUpperCase();
+}
+
+function uInt16To4Chars(value: number) {
+    const byteArray = new Uint8Array(2);
+    const dataView = Bytes.dataViewOf(byteArray);
+    dataView.setUint16(0, value);
+    return Bytes.toHex(byteArray).toUpperCase();
+}
+
+/**
+ * Matter specific ASN.1 OIDs
+ * @see {@link MatterSpecification.v12.Core} Appendix E
+ */
+
+/**
+ * Generator function to create a specific ASN field for a Matter OpCert DN with the OID base 1.3.6.1.4.1.37244.1.*.
+ * The returned function takes the value and returns the ASN.1 DER object.
+ */
+const GenericMatterOpCertObject =
+    <T>(id: number, valueConverter?: (value: T) => string) =>
+    (value: T) => [
+        DerObject(`2b0601040182a27c01${id.toString(16).padStart(2, "0")}`, {
+            value: (valueConverter ?? intTo16Chars)(value as any),
+        }),
+    ];
+
+/**
+ * Generator function to create a specific ASN field for a Matter AttCert DN with the OID base 1.3.6.1.4.1.37244.2.*.
+ * The returned function takes the value and returns the ASN.1 DER object.
+ */
+const GenericMatterAttCertObject =
+    <T>(id: number, valueConverter?: (value: T) => string) =>
+    (value: T) => [
+        DerObject(`2b0601040182a27c02${id.toString(16).padStart(2, "0")}`, {
+            value: (valueConverter ?? intTo16Chars)(value as any),
+        }),
+    ];
+
+/** matter-node-id = ASN.1 OID 1.3.6.1.4.1.37244.1.1 */
+export const NodeId_Matter = GenericMatterOpCertObject<NodeId>(1);
+
+/** matter-firmware-signing-id = ASN.1 OID 1.3.6.1.4.1.37244.1.2 */
+export const FirmwareSigningId_Matter = GenericMatterOpCertObject<number>(2);
+
+/** matter-icac-id = ASN.1 OID 1.3.6.1.4.1.37244.1.3 */
+export const IcacId_Matter = GenericMatterOpCertObject<bigint | number>(3);
+
+/** matter-rcac-id = ASN.1 OID 1.3.6.1.4.1.37244.1.4 */
+export const RcacId_Matter = GenericMatterOpCertObject<bigint | number>(4);
+
+/** matter-fabric-id = ASN.1 OID 1.3.6.1.4.1.37244.1.5 */
+export const FabricId_Matter = GenericMatterOpCertObject<FabricId>(5);
+
+/** matter-noc-cat = ASN.1 OID 1.3.6.1.4.1.37244.1.6 */
+export const NocCat_Matter = GenericMatterOpCertObject<number>(6, uInt16To8Chars);
+
+/** matter-oid-vid = ASN.1 OID 1.3.6.1.4.1.37244.2.1 */
+export const VendorId_Matter = GenericMatterAttCertObject<VendorId>(1, uInt16To4Chars);
+
+/** matter-oid-pid = ASN.1 OID 1.3.6.1.4.1.37244.2.2 */
+export const ProductId_Matter = GenericMatterAttCertObject<number>(2, uInt16To4Chars);

package/src/certificate/kinds/definitions/attestation.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { VendorId } from "#types";
+import { X509Certificate } from "./base.js";
+
+/** Definitions for Matter Attestation certificates (PAA, PAI, DAC) */
+export namespace AttestationCertificate {
+    export interface Dac extends X509Certificate {
+        issuer: {
+            commonName: string;
+            productId?: number;
+            vendorId: VendorId;
+        };
+        subject: {
+            commonName: string;
+            productId: number;
+            vendorId: VendorId;
+        };
+    }
+
+    export interface Pai extends X509Certificate {
+        issuer: {
+            commonName: string;
+            vendorId?: VendorId;
+        };
+        subject: {
+            commonName: string;
+            productId?: number;
+            vendorId: VendorId;
+        };
+    }
+
+    export interface Paa extends X509Certificate {
+        issuer: {
+            commonName: string;
+            vendorId?: VendorId;
+        };
+        subject: {
+            commonName: string;
+            vendorId?: VendorId;
+        };
+    }
+}

package/src/certificate/kinds/definitions/base.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BitFlag, BitmapSchema, TypeFromPartialBitSchema } from "#types";
+
+export const ExtensionKeyUsageBitmap = {
+    digitalSignature: BitFlag(0),
+    nonRepudiation: BitFlag(1),
+    keyEncipherment: BitFlag(2),
+    dataEncipherment: BitFlag(3),
+    keyAgreement: BitFlag(4),
+    keyCertSign: BitFlag(5),
+    cRLSign: BitFlag(6),
+    encipherOnly: BitFlag(7),
+    decipherOnly: BitFlag(8),
+};
+export const ExtensionKeyUsageSchema = BitmapSchema(ExtensionKeyUsageBitmap);
+
+export interface X509Certificate {
+    serialNumber: Uint8Array;
+    signatureAlgorithm: number;
+    issuer: {};
+    notBefore: number;
+    notAfter: number;
+    subject: {};
+    publicKeyAlgorithm: number;
+    ellipticCurveIdentifier: number;
+    ellipticCurvePublicKey: Uint8Array;
+    extensions: {
+        basicConstraints: {
+            isCa: boolean;
+            pathLen?: number;
+        };
+        keyUsage: TypeFromPartialBitSchema<typeof ExtensionKeyUsageBitmap>;
+        extendedKeyUsage?: number[];
+        subjectKeyIdentifier: Uint8Array;
+        authorityKeyIdentifier: Uint8Array;
+        futureExtension?: Uint8Array[];
+    };
+    signature: Uint8Array;
+}

package/src/certificate/kinds/definitions/certification-declaration.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+    TlvArray,
+    TlvByteString,
+    TlvField,
+    TlvObject,
+    TlvOptionalField,
+    TlvString,
+    TlvUInt16,
+    TlvUInt32,
+    TlvUInt8,
+    TlvVendorId,
+} from "#types";
+
+/** Definitions for Matter Certification Declaration */
+export namespace CertificationDeclaration {
+    export const TlvDc = TlvObject({
+        formatVersion: TlvField(0, TlvUInt16),
+        vendorId: TlvField(1, TlvVendorId),
+        produceIdArray: TlvField(2, TlvArray(TlvUInt16, { minLength: 1, maxLength: 100 })),
+        deviceTypeId: TlvField(3, TlvUInt32),
+        certificateId: TlvField(4, TlvString.bound({ length: 19 })),
+        securityLevel: TlvField(5, TlvUInt8),
+        securityInformation: TlvField(6, TlvUInt16),
+        versionNumber: TlvField(7, TlvUInt16),
+        certificationType: TlvField(8, TlvUInt8),
+        dacOriginVendorId: TlvOptionalField(9, TlvVendorId),
+        dacOriginProductId: TlvOptionalField(10, TlvUInt16),
+        authorizedPaaList: TlvOptionalField(
+            11,
+            TlvArray(TlvByteString.bound({ length: 20 }), { minLength: 1, maxLength: 10 }),
+        ),
+    });
+}