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

package/src/certificate/kinds/Noc.ts

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Crypto, Diagnostic, PublicKey } from "#general";
+import { CaseAuthenticatedTag, FabricId, NodeId } from "#types";
+import { CertificateError } from "./common.js";
+import { OperationalCertificate } from "./definitions/operational.js";
+import { Icac } from "./Icac.js";
+import { OperationalBase } from "./OperationalBase.js";
+import { Rcac } from "./Rcac.js";
+
+export class Noc extends OperationalBase<OperationalCertificate.Noc> {
+    /** Construct the class from a Tlv version of the certificate */
+    static fromTlv(tlv: Uint8Array) {
+        return new Noc(OperationalCertificate.TlvNoc.decode(tlv));
+    }
+
+    /** Validates all basic certificate fields on construction. */
+    protected validateFields() {
+        const {
+            issuer: { icacId, rcacId },
+            extensions: {
+                basicConstraints: { isCa },
+            },
+        } = this.cert;
+        if (icacId === undefined && rcacId === undefined) {
+            throw new CertificateError("Issuer RCAC or ICAC ID must be defined for an operational certificate.");
+        }
+        if (isCa) {
+            throw new CertificateError("Node operational certificate must not be a CA.");
+        }
+    }
+
+    /**
+     * Encodes the certificate with the signature as Matter Tlv.
+     * If the certificate is not signed, it throws a CertificateError.
+     */
+    asSignedTlv() {
+        return OperationalCertificate.TlvNoc.encode({ ...this.cert, signature: this.signature });
+    }
+
+    /**
+     * Verify requirements a Matter Node Operational certificate must fulfill.
+     * Rules for this are listed in @see {@link MatterSpecification.v12.Core} §6.5.x
+     */
+    async verify(crypto: Crypto, root: Rcac, ica?: Icac) {
+        this.generalVerify();
+
+        const {
+            subject,
+            extensions: { extendedKeyUsage, subjectKeyIdentifier, authorityKeyIdentifier },
+        } = this.cert;
+        const { nodeId, fabricId, caseAuthenticatedTags } = subject;
+        const {
+            subject: { fabricId: rootFabricId },
+        } = root.cert;
+        const {
+            subject: { fabricId: icaFabricId },
+        } = ica?.cert ?? { subject: {} };
+
+        // The subject DN SHALL encode exactly one matter-node-id attribute.
+        if (nodeId === undefined || Array.isArray(nodeId)) {
+            throw new CertificateError(`Invalid nodeId in NoC certificate: ${Diagnostic.json(nodeId)}`);
+        }
+        // The matter-node-id attribute’s value SHALL be in the Operational Node ID
+        if (!NodeId.isOperationalNodeId(nodeId)) {
+            throw new CertificateError(`Invalid nodeId in NoC certificate: ${Diagnostic.json(nodeId)}`);
+        }
+
+        // The subject DN SHALL encode exactly one matter-fabric-id attribute.
+        if (fabricId === undefined || Array.isArray(fabricId)) {
+            throw new CertificateError(`Invalid fabricId in NoC certificate: ${Diagnostic.json(fabricId)}`);
+        }
+        // The matter-fabric-id attribute’s value SHALL NOT be 0
+        if (fabricId === FabricId(0)) {
+            throw new CertificateError(`Invalid fabricId in NoC certificate: ${Diagnostic.json(fabricId)}`);
+        }
+
+        // The subject DN SHALL NOT encode any matter-icac-id attribute.
+        if ("icacId" in subject) {
+            throw new CertificateError(`Noc certificate must not contain an icacId.`);
+        }
+
+        // The subject DN SHALL NOT encode any matter-rcac-id attribute.
+        if ("rcacId" in subject) {
+            throw new CertificateError(`Noc certificate must not contain an rcacId.`);
+        }
+
+        // The subject DN MAY encode at most three matter-noc-cat attributes.
+        if (caseAuthenticatedTags !== undefined) {
+            CaseAuthenticatedTag.validateNocTagList(caseAuthenticatedTags); // throws ValidationError
+        }
+
+        // When any matter-fabric-id attributes are present in either the Matter Root CA Certificate or the Matter ICA
+        // Certificate, the value SHALL match the one present in the Matter Node Operational Certificate (NOC) within
+        // the same certificate chain.
+        if (rootFabricId !== undefined && rootFabricId !== fabricId) {
+            throw new CertificateError(
+                `FabricId in NoC certificate does not match the fabricId in the parent certificate. ${Diagnostic.json(
+                    rootFabricId,
+                )} !== ${Diagnostic.json(fabricId)}`,
+            );
+        }
+        if (icaFabricId !== undefined && icaFabricId !== fabricId) {
+            throw new CertificateError(
+                `FabricId in NoC certificate does not match the fabricId in the parent certificate. ${Diagnostic.json(
+                    icaFabricId,
+                )} !== ${Diagnostic.json(fabricId)}`,
+            );
+        }
+
+        // The basic constraints extension SHALL be encoded with is-ca set to false.
+        if (this.cert.extensions.basicConstraints.isCa) {
+            throw new CertificateError(`Noc certificate must not have isCa set to true.`);
+        }
+
+        // The key usage extension SHALL be encoded with exactly two flags: keyCertSign (0x0020) and CRLSign (0x0040).
+        // Formally the check should be the following line but Amazon uses a wrong Root cert which also has
+        // digitalCertificate set, so we just check that the two needed are set and ignore additionally set parameters.
+        //if (ExtensionKeyUsageSchema.encode(nocCert.extensions.keyUsage) !== 1) {
+        if (!this.cert.extensions.keyUsage.digitalSignature) {
+            throw new CertificateError(`Noc certificate must have keyUsage set to digitalSignature.`);
+        }
+
+        // The extended key usage extension SHALL be encoded with exactly two key-purpose-id values: serverAuth and clientAuth.
+        if (extendedKeyUsage === undefined || (!extendedKeyUsage.includes(1) && !extendedKeyUsage.includes(2))) {
+            throw new CertificateError(
+                `Noc certificate must have extendedKeyUsage with serverAuth and clientAuth: ${Diagnostic.json(extendedKeyUsage)}`,
+            );
+        }
+
+        // The subject key identifier extension SHALL be present and 160 bit long.
+        if (subjectKeyIdentifier === undefined) {
+            throw new CertificateError(`Noc certificate must have subjectKeyIdentifier set.`);
+        }
+        if (subjectKeyIdentifier.length !== 20) {
+            throw new CertificateError(`Noc certificate subjectKeyIdentifier must be 160 bit.`);
+        }
+
+        // The authority key identifier extension SHALL be present and 160 bit long.
+        if (authorityKeyIdentifier === undefined) {
+            throw new CertificateError(`Noc certificate must have authorityKeyIdentifier set.`);
+        }
+        if (authorityKeyIdentifier.length !== 20) {
+            throw new CertificateError(`Noc certificate authorityKeyIdentifier must be 160 bit.`);
+        }
+
+        // Validate authority key identifier against subject key identifier
+        if (!Bytes.areEqual(authorityKeyIdentifier, (ica?.cert ?? root.cert).extensions.subjectKeyIdentifier)) {
+            throw new CertificateError(
+                `Noc certificate authorityKeyIdentifier must be equal to Root/Ica subjectKeyIdentifier.`,
+            );
+        }
+
+        await crypto.verifyEcdsa(
+            PublicKey((ica?.cert ?? root.cert).ellipticCurvePublicKey),
+            this.asUnsignedAsn1(),
+            this.signature,
+        );
+    }
+}

package/src/certificate/kinds/OperationalBase.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger, Time } from "#general";
+import { X509Base } from "./X509Base.js";
+import { CertificateError, Unsigned } from "./common.js";
+import { X509Certificate } from "./definitions/base.js";
+
+const logger = Logger.get("OperationalBaseCertificate");
+
+/**
+ * Base class for all operational certificates (RCAC, ICAC, NOC)
+ */
+export abstract class OperationalBase<CT extends X509Certificate> extends X509Base<CT> {
+    constructor(cert: CT | Unsigned<CT>) {
+        super(cert);
+        this.validateFields();
+    }
+
+    /** Validates all basic certificate fields on construction. */
+    protected abstract validateFields(): void;
+
+    /** Encodes the signed certificate into the Matter TLV format. */
+    abstract asSignedTlv(signature: Uint8Array<ArrayBufferLike>): Uint8Array;
+
+    /**
+     * Verifies general requirements a Matter certificate fields must fulfill.
+     * Rules for this are listed in @see {@link MatterSpecification.v12.Core} §6.5.x
+     */
+    generalVerify() {
+        const cert = this.cert;
+        if (cert.serialNumber.length > 20)
+            throw new CertificateError(
+                `Serial number must not be longer then 20 octets. Current serial number has ${cert.serialNumber.length} octets.`,
+            );
+
+        if (cert.signatureAlgorithm !== 1) {
+            // ecdsa-with-sha256
+            throw new CertificateError(`Unsupported signature algorithm: ${cert.signatureAlgorithm}`);
+        }
+
+        if (cert.publicKeyAlgorithm !== 1) {
+            // ec-pub-key
+            throw new CertificateError(`Unsupported public key algorithm: ${cert.publicKeyAlgorithm}`);
+        }
+
+        if (cert.ellipticCurveIdentifier !== 1) {
+            // prime256v1
+            throw new CertificateError(`Unsupported elliptic curve identifier: ${cert.ellipticCurveIdentifier}`);
+        }
+
+        // All implementations SHALL reject Matter certificates with more than 5 RDNs in a single DN.
+        if (Object.keys(cert.subject).length > 5) {
+            throw new CertificateError(`Certificate subject must not contain more than 5 RDNs.`);
+        }
+        if (Object.keys(cert.issuer).length > 5) {
+            throw new CertificateError(`Certificate issuer must not contain more than 5 RDNs.`);
+        }
+
+        // notBefore date should be already reached, notAfter is not checked right now
+        // TODO: implement real checks when we add "Last known Good UTC time"
+        if (cert.notBefore * 1000 > Time.nowMs()) {
+            logger.warn(`Certificate notBefore date is in the future: ${cert.notBefore * 1000} vs ${Time.nowMs()}`);
+            /*throw new CertificateError(
+                `Certificate notBefore date is in the future: ${cert.notBefore * 1000} vs ${Time.nowMs()}`,
+            );*/
+        }
+    }
+}

package/src/certificate/kinds/Rcac.ts

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Crypto, Diagnostic, PublicKey } from "#general";
+import { FabricId } from "#types";
+import { CertificateError } from "./common.js";
+import { ExtensionKeyUsageSchema } from "./definitions/base.js";
+import { OperationalCertificate } from "./definitions/operational.js";
+import { OperationalBase } from "./OperationalBase.js";
+
+export class Rcac extends OperationalBase<OperationalCertificate.Rcac> {
+    /** Construct the class from a Tlv version of the certificate */
+    static fromTlv(tlv: Uint8Array): Rcac {
+        return new Rcac(OperationalCertificate.TlvRcac.decode(tlv));
+    }
+
+    /** Validates all basic certificate fields on construction. */
+    protected validateFields() {
+        const {
+            extensions: {
+                basicConstraints: { isCa },
+            },
+        } = this.cert;
+        if (!isCa) {
+            throw new CertificateError("Root certificate must be a CA.");
+        }
+    }
+
+    /**
+     * Encodes the certificate with the signature as Matter Tlv.
+     * If the certificate is not signed, it throws a CertificateError.
+     */
+    asSignedTlv() {
+        return OperationalCertificate.TlvRcac.encode({ ...this.cert, signature: this.signature });
+    }
+
+    /**
+     * Verify requirements a Matter Root certificate must fulfill.
+     * Rules for this are listed in @see {@link MatterSpecification.v12.Core} §6.5.x
+     */
+    async verify(crypto: Crypto) {
+        this.generalVerify();
+
+        const { subject, extensions } = this.cert;
+        const { fabricId, rcacId } = subject;
+        const { basicConstraints, subjectKeyIdentifier, authorityKeyIdentifier } = extensions;
+
+        // The subject DN SHALL NOT encode any matter-node-id attribute.
+        if ("nodeId" in subject) {
+            throw new CertificateError(`Root certificate must not contain a nodeId.`);
+        }
+
+        // The subject DN MAY encode at most one matter-fabric-id attribute.
+        if (fabricId !== undefined) {
+            if (Array.isArray(fabricId)) {
+                throw new CertificateError(`Invalid fabricId in NoC certificate: ${Diagnostic.json(fabricId)}`);
+            }
+            // If present, the matter-fabric-id attribute’s value SHALL NOT be 0
+            if (fabricId === FabricId(0)) {
+                throw new CertificateError(`Invalid fabricId in NoC certificate: ${Diagnostic.json(fabricId)}`);
+            }
+        }
+
+        // The subject DN SHALL NOT encode any matter-icac-id attribute.
+        if ("icacId" in subject) {
+            throw new CertificateError(`Root certificate must not contain an icacId.`);
+        }
+
+        // The subject DN SHALL encode exactly one matter-rcac-id attribute.
+        if (rcacId === undefined || Array.isArray(rcacId)) {
+            throw new CertificateError(`Invalid rcacId in Root certificate: ${Diagnostic.json(rcacId)}`);
+        }
+
+        // The subject DN SHALL NOT encode any matter-noc-cat attribute.
+        if ("caseAuthenticatedTags" in subject) {
+            throw new CertificateError(`Root certificate must not contain a caseAuthenticatedTags.`);
+        }
+
+        // The basic constraints extension SHALL be encoded with is-ca set to true.
+        if (basicConstraints.isCa !== true) {
+            throw new CertificateError(`Root certificate must have isCa set to true.`);
+        }
+
+        // The key usage extension SHALL be encoded with at least two flags: keyCertSign (0x0020) and CRLSign (0x0040)
+        // and optionally with digitalSignature (0x0001).
+        const keyUsage = ExtensionKeyUsageSchema.encode(extensions.keyUsage);
+        if (keyUsage !== 0x0060 && keyUsage !== 0x0061) {
+            throw new CertificateError(
+                `Root certificate keyUsage must have keyCertSign and CRLSign and optionally digitalSignature set.`,
+            );
+        }
+
+        // The extended key usage extension SHALL NOT be present.
+        if (extensions.extendedKeyUsage !== undefined) {
+            throw new CertificateError(`Root certificate must not have extendedKeyUsage set.`);
+        }
+
+        // The subject key identifier extension SHALL be present and 160 bit long.
+        if (subjectKeyIdentifier === undefined) {
+            throw new CertificateError(`Root certificate must have subjectKeyIdentifier set.`);
+        }
+        if (subjectKeyIdentifier.length !== 20) {
+            throw new CertificateError(`Root certificate subjectKeyIdentifier must be 160 bit.`);
+        }
+
+        // The authority key identifier extension SHALL be present and 160 bit long.
+        if (authorityKeyIdentifier === undefined) {
+            throw new CertificateError(`Root certificate must have authorityKeyIdentifier set.`);
+        }
+        if (authorityKeyIdentifier.length !== 20) {
+            throw new CertificateError(`Root certificate authorityKeyIdentifier must be 160 bit.`);
+        }
+
+        // The authority key identifier extension SHALL be equal to the subject key identifier extension.
+        if (!Bytes.areEqual(authorityKeyIdentifier, subjectKeyIdentifier)) {
+            throw new CertificateError(
+                `Root certificate authorityKeyIdentifier must be equal to subjectKeyIdentifier.`,
+            );
+        }
+
+        await crypto.verifyEcdsa(PublicKey(this.cert.ellipticCurvePublicKey), this.asUnsignedAsn1(), this.signature);
+    }
+}