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

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

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+    TlvArray,
+    TlvBitmap,
+    TlvBoolean,
+    TlvByteString,
+    TlvCaseAuthenticatedTag,
+    TlvFabricId,
+    TlvField,
+    TlvNodeId,
+    TlvObject,
+    TlvObjectWithMaxSize,
+    TlvOptionalField,
+    TlvOptionalRepeatedField,
+    TlvString,
+    TlvTaggedList,
+    TlvUInt16,
+    TlvUInt32,
+    TlvUInt64,
+    TlvUInt8,
+    TypeFromSchema,
+} from "#types";
+import { ExtensionKeyUsageBitmap } from "./base.js";
+
+/**
+ * Matter specific Certificate Sizes
+ * @see {@link MatterSpecification.v13.Core} 6.1.3.
+ */
+export const MAX_TLV_CERTIFICATE_SIZE = 400;
+
+export const TlvCertificateExtension = TlvTaggedList({
+    basicConstraints: TlvField(
+        1,
+        TlvObject({
+            isCa: TlvField(1, TlvBoolean),
+            pathLen: TlvOptionalField(2, TlvUInt8),
+        }),
+    ),
+    keyUsage: TlvField(2, TlvBitmap(TlvUInt16, ExtensionKeyUsageBitmap)),
+    extendedKeyUsage: TlvOptionalField(3, TlvArray(TlvUInt8)),
+    subjectKeyIdentifier: TlvField(4, TlvByteString.bound({ length: 20 })),
+    authorityKeyIdentifier: TlvField(5, TlvByteString.bound({ length: 20 })),
+    futureExtension: TlvOptionalRepeatedField(6, TlvByteString),
+});
+
+export type CertificateExtension = TypeFromSchema<typeof TlvCertificateExtension>;
+
+/** Definitions for Matter Operational Certificates (RCAC, ICAC, NOC) */
+export namespace OperationalCertificate {
+    /** All defined Matter fields for subject and issuer that we always allow optionally to be encoded */
+    const AllowedSubjectAndIssuerMatterFields = {
+        nodeId: TlvOptionalField(17, TlvNodeId),
+        firmwareSigningId: TlvOptionalField(18, TlvUInt32),
+        icacId: TlvOptionalField(19, TlvUInt64),
+        rcacId: TlvOptionalField(20, TlvUInt64),
+        fabricId: TlvOptionalField(21, TlvFabricId),
+        caseAuthenticatedTags: TlvOptionalRepeatedField(22, TlvCaseAuthenticatedTag, { maxLength: 3 }),
+    };
+
+    /**
+     * TLV schema for a generic subject or issuer field in a certificate. We handle all fields as optional here for the TLV
+     * parsing and check required fields in the logic to make sure we return the correct errors.
+     */
+    const TlvGenericMatterSubjectOrIssuerTaggedList = <T>(matterFields: T) => {
+        const fields = {
+            // Standard DNs
+            commonName: TlvOptionalField(1, TlvString),
+            sureName: TlvOptionalField(2, TlvString),
+            serialNum: TlvOptionalField(3, TlvString),
+            countryName: TlvOptionalField(4, TlvString),
+            localityName: TlvOptionalField(5, TlvString),
+            stateOrProvinceName: TlvOptionalField(6, TlvString),
+            orgName: TlvOptionalField(7, TlvString),
+            orgUnitName: TlvOptionalField(8, TlvString),
+            title: TlvOptionalField(9, TlvString),
+            name: TlvOptionalField(10, TlvString),
+            givenName: TlvOptionalField(11, TlvString),
+            initials: TlvOptionalField(12, TlvString),
+            genQualifier: TlvOptionalField(13, TlvString),
+            dnQualifier: TlvOptionalField(14, TlvString),
+            pseudonym: TlvOptionalField(15, TlvString),
+            domainComponent: TlvOptionalField(16, TlvString),
+
+            // Matter specific DNs
+            ...matterFields,
+
+            // Standard DNs when encoded as Printable String
+            commonNamePs: TlvOptionalField(129, TlvString),
+            sureNamePs: TlvOptionalField(130, TlvString),
+            serialNumPs: TlvOptionalField(131, TlvString),
+            countryNamePs: TlvOptionalField(132, TlvString),
+            localityNamePs: TlvOptionalField(133, TlvString),
+            stateOrProvinceNamePs: TlvOptionalField(134, TlvString),
+            orgNamePs: TlvOptionalField(135, TlvString),
+            orgUnitNamePs: TlvOptionalField(136, TlvString),
+            titlePs: TlvOptionalField(137, TlvString),
+            namePs: TlvOptionalField(138, TlvString),
+            givenNamePs: TlvOptionalField(139, TlvString),
+            initialsPs: TlvOptionalField(140, TlvString),
+            genQualifierPs: TlvOptionalField(141, TlvString),
+            dnQualifierPs: TlvOptionalField(142, TlvString),
+            pseudonymPs: TlvOptionalField(143, TlvString),
+        };
+        return TlvTaggedList(fields);
+    };
+
+    /**
+     * This generator enhances the generic Matter Certificate definition by allowing to override the subject and issuer
+     * fields. The overriding serves two needs:
+     * 1. to make some fields mandatory for the Tlv parsing and definition for the typescript types
+     * 2. have typing guidance when generating certificates ourself in code
+     *
+     * On Tlv definition level also all not specified allowed Matter Fields are optionally allowed and are decoded,
+     * re-encoded into Tlv and also encoded into ASN if the certificate is converted. Just the typing system do not know
+     * about them.
+     */
+    const BaseMatterCertificate = <S, I>(matterFields?: { subject?: S; issuer?: I }) =>
+        TlvObjectWithMaxSize(
+            {
+                serialNumber: TlvField(1, TlvByteString.bound({ maxLength: 20 })),
+                signatureAlgorithm: TlvField(2, TlvUInt8),
+                issuer: TlvField(
+                    3,
+                    TlvGenericMatterSubjectOrIssuerTaggedList<I>({
+                        ...AllowedSubjectAndIssuerMatterFields,
+                        ...(matterFields?.issuer ?? {}),
+                    } as I),
+                ),
+                notBefore: TlvField(4, TlvUInt32),
+                notAfter: TlvField(5, TlvUInt32),
+                subject: TlvField(
+                    6,
+                    TlvGenericMatterSubjectOrIssuerTaggedList<S>({
+                        ...AllowedSubjectAndIssuerMatterFields,
+                        ...(matterFields?.subject ?? {}),
+                    } as S),
+                ),
+                publicKeyAlgorithm: TlvField(7, TlvUInt8),
+                ellipticCurveIdentifier: TlvField(8, TlvUInt8),
+                ellipticCurvePublicKey: TlvField(9, TlvByteString),
+                extensions: TlvField(10, TlvCertificateExtension),
+                signature: TlvField(11, TlvByteString),
+            },
+            MAX_TLV_CERTIFICATE_SIZE,
+        );
+
+    export const TlvRcac = BaseMatterCertificate({
+        subject: {
+            rcacId: TlvField(20, TlvUInt64),
+            fabricId: TlvOptionalField(21, TlvFabricId),
+        },
+        issuer: AllowedSubjectAndIssuerMatterFields,
+    });
+
+    export const TlvNoc = BaseMatterCertificate({
+        subject: {
+            nodeId: TlvField(17, TlvNodeId),
+            fabricId: TlvField(21, TlvFabricId),
+            caseAuthenticatedTags: TlvOptionalRepeatedField(22, TlvCaseAuthenticatedTag, { maxLength: 3 }),
+        },
+        issuer: AllowedSubjectAndIssuerMatterFields,
+    });
+
+    export const TlvIcac = BaseMatterCertificate({
+        subject: {
+            icacId: TlvField(19, TlvUInt64),
+            fabricId: TlvOptionalField(21, TlvFabricId),
+        },
+        issuer: AllowedSubjectAndIssuerMatterFields,
+    });
+
+    export type Rcac = TypeFromSchema<typeof TlvRcac>;
+    export type Icac = TypeFromSchema<typeof TlvIcac>;
+    export type Noc = TypeFromSchema<typeof TlvNoc>;
+}

package/src/certificate/kinds/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./AttestationCertificates.js";
+export * from "./CertificationDeclaration.js";
+export * from "./Icac.js";
+export * from "./Noc.js";
+export * from "./Rcac.js";
+export * from "./X509Base.js";

package/src/fabric/Fabric.ts

@@ -4,12 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {
-    CertificateManager,
-    TlvIntermediateCertificate,
-    TlvOperationalCertificate,
-    TlvRootCertificate,
-} from "#certificate/CertificateManager.js";
+import { Icac, Noc, Rcac, X509Base } from "#certificate/index.js";
 import {
     BinaryKeyPair,
     Bytes,
@@ -49,7 +44,7 @@ export type ExposedFabricInformation = {
 };
 
 export class Fabric {
-    readonly #certs: CertificateManager;
+    readonly #crypto: Crypto;
     readonly fabricIndex: FabricIndex;
     readonly fabricId: FabricId;
     readonly nodeId: NodeId;
@@ -71,11 +66,8 @@ export class Fabric {
     #persistCallback: ((isUpdate?: boolean) => MaybePromise<void>) | undefined;
     #storage?: StorageContext;
 
-    constructor(certs: CertificateManager | Crypto, config: Fabric.Config) {
-        if (!(certs instanceof CertificateManager)) {
-            certs = new CertificateManager(certs);
-        }
-        this.#certs = certs;
+    constructor(crypto: Crypto, config: Fabric.Config) {
+        this.#crypto = crypto;
         this.fabricIndex = config.fabricIndex;
         this.fabricId = config.fabricId;
         this.nodeId = config.nodeId;
@@ -95,7 +87,7 @@ export class Fabric {
     }
 
     get crypto() {
-        return this.#certs.crypto;
+        return this.#crypto;
     }
 
     get config(): Fabric.Config {
@@ -154,20 +146,19 @@ export class Fabric {
     }
 
     sign(data: Uint8Array) {
-        return this.#certs.crypto.signEcdsa(this.#keyPair, data);
+        return this.crypto.signEcdsa(this.#keyPair, data);
     }
 
     async verifyCredentials(operationalCert: Uint8Array, intermediateCACert?: Uint8Array) {
-        const rootCert = TlvRootCertificate.decode(this.rootCert);
-        const nocCert = TlvOperationalCertificate.decode(operationalCert);
-        const icaCert =
-            intermediateCACert !== undefined ? TlvIntermediateCertificate.decode(intermediateCACert) : undefined;
+        const rootCert = Rcac.fromTlv(this.rootCert);
+        const nocCert = Noc.fromTlv(operationalCert);
+        const icaCert = intermediateCACert !== undefined ? Icac.fromTlv(intermediateCACert) : undefined;
         if (icaCert !== undefined) {
             // Validate ICACertificate against Root Certificate
-            await this.#certs.verifyIntermediateCaCertificate(rootCert, icaCert);
+            await icaCert.verify(this.#crypto, rootCert);
         }
         // Validate NOC Certificate against ICA Certificate
-        await this.#certs.verifyNodeOperationalCertificate(nocCert, rootCert, icaCert);
+        await nocCert.verify(this.#crypto, rootCert, icaCert);
     }
 
     matchesFabricIdAndRootPublicKey(fabricId: FabricId, rootPublicKey: Uint8Array) {
@@ -195,7 +186,7 @@ export class Fabric {
      * returns the time-wise valid operational keys for that groupId.
      */
     async currentDestinationIdFor(nodeId: NodeId, random: Uint8Array) {
-        return await this.#certs.crypto.signHmac(
+        return await this.#crypto.signHmac(
             this.groups.keySets.currentKeyForId(0).key,
             this.#generateSalt(nodeId, random),
         );
@@ -208,9 +199,7 @@ export class Fabric {
     async destinationIdsFor(nodeId: NodeId, random: Uint8Array) {
         const salt = this.#generateSalt(nodeId, random);
         // Check all keys of keyset 0 - typically it is only the IPK
-        const destinationIds = this.groups.keySets
-            .allKeysForId(0)
-            .map(({ key }) => this.#certs.crypto.signHmac(key, salt));
+        const destinationIds = this.groups.keySets.allKeysForId(0).map(({ key }) => this.#crypto.signHmac(key, salt));
         return await Promise.all(destinationIds);
     }
 
@@ -274,7 +263,7 @@ export class Fabric {
 }
 
 export class FabricBuilder {
-    #certs: CertificateManager;
+    #crypto: Crypto;
     #keyPair: PrivateKey;
     #rootVendorId?: VendorId;
     #rootCert?: Uint8Array;
@@ -289,7 +278,7 @@ export class FabricBuilder {
     #label = "";
 
     constructor(crypto: Crypto, key: PrivateKey) {
-        this.#certs = new CertificateManager(crypto);
+        this.#crypto = crypto;
         this.#keyPair = key;
     }
 
@@ -306,14 +295,14 @@ export class FabricBuilder {
     }
 
     createCertificateSigningRequest() {
-        return this.#certs.createCertificateSigningRequest(this.#keyPair);
+        return X509Base.createCertificateSigningRequest(this.#crypto, this.#keyPair);
     }
 
     async setRootCert(rootCert: Uint8Array) {
-        const decodedRootCertificate = TlvRootCertificate.decode(rootCert);
-        await this.#certs.verifyRootCertificate(decodedRootCertificate);
+        const root = Rcac.fromTlv(rootCert);
+        await root.verify(this.#crypto);
         this.#rootCert = rootCert;
-        this.#rootPublicKey = decodedRootCertificate.ellipticCurvePublicKey;
+        this.#rootPublicKey = root.cert.ellipticCurvePublicKey;
         return this;
     }
 
@@ -328,7 +317,7 @@ export class FabricBuilder {
         const {
             subject: { nodeId, fabricId, caseAuthenticatedTags },
             ellipticCurvePublicKey,
-        } = TlvOperationalCertificate.decode(operationalCert);
+        } = Noc.fromTlv(operationalCert).cert;
         logger.debug(
             "Installing operational certificate",
             Diagnostic.dict({ nodeId, fabricId, caseAuthenticatedTags }),
@@ -345,14 +334,13 @@ export class FabricBuilder {
             throw new MatterFlowError("Root certificate needs to be set first");
         }
 
-        const rootCert = TlvRootCertificate.decode(this.#rootCert);
-        const nocCert = TlvOperationalCertificate.decode(operationalCert);
-        const icaCert =
-            intermediateCACert !== undefined ? TlvIntermediateCertificate.decode(intermediateCACert) : undefined;
+        const rootCert = Rcac.fromTlv(this.#rootCert);
+        const nocCert = Noc.fromTlv(operationalCert);
+        const icaCert = intermediateCACert !== undefined ? Icac.fromTlv(intermediateCACert) : undefined;
         if (icaCert !== undefined) {
-            await this.#certs.verifyIntermediateCaCertificate(rootCert, icaCert);
+            await icaCert.verify(this.#crypto, rootCert);
         }
-        await this.#certs.verifyNodeOperationalCertificate(nocCert, rootCert, icaCert);
+        await nocCert.verify(this.#crypto, rootCert, icaCert);
 
         this.#operationalCert = operationalCert;
         this.#intermediateCACert = intermediateCACert;
@@ -426,14 +414,14 @@ export class FabricBuilder {
         this.#fabricIndex = fabricIndex;
         const saltWriter = new DataWriter();
         saltWriter.writeUInt64(this.#fabricId);
-        const operationalId = await this.#certs.crypto.createHkdfKey(
+        const operationalId = await this.#crypto.createHkdfKey(
             this.#rootPublicKey.slice(1),
             saltWriter.toByteArray(),
             COMPRESSED_FABRIC_ID_INFO,
             8,
         );
 
-        return new Fabric(this.#certs, {
+        return new Fabric(this.#crypto, {
             fabricIndex: this.#fabricIndex,
             fabricId: this.#fabricId,
             nodeId: this.#nodeId,
@@ -444,7 +432,7 @@ export class FabricBuilder {
             rootVendorId: this.#rootVendorId,
             rootCert: this.#rootCert,
             identityProtectionKey: this.#identityProtectionKey, // Epoch Key
-            operationalIdentityProtectionKey: await this.#certs.crypto.createHkdfKey(
+            operationalIdentityProtectionKey: await this.#crypto.createHkdfKey(
                 this.#identityProtectionKey,
                 operationalId,
                 GROUP_SECURITY_INFO,

package/src/peer/ControllerCommissioningFlow.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { X509Base } from "#certificate/index.js";
 import { BasicInformation } from "#clusters/basic-information";
 import { Descriptor } from "#clusters/descriptor";
 import { GeneralCommissioning } from "#clusters/general-commissioning";
@@ -808,7 +809,7 @@ export class ControllerCommissioningFlow {
         }
         // TODO: validate csrSignature using device public key
         const { certSigningRequest } = TlvCertSigningRequest.decode(nocsrElements);
-        const operationalPublicKey = await this.ca.certs.getPublicKeyFromCsr(certSigningRequest);
+        const operationalPublicKey = await X509Base.getPublicKeyFromCsr(this.ca.crypto, certSigningRequest);
 
         await operationalCredentialsClusterClient.addTrustedRootCertificate(
             {

package/src/session/case/CaseClient.ts

@@ -4,11 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Icac, Noc } from "#certificate/index.js";
 import { Bytes, Logger, PublicKey, UnexpectedDataError } from "#general";
 import { ChannelStatusResponseError } from "#securechannel/index.js";
 import { SessionManager } from "#session/SessionManager.js";
 import { NodeId, ProtocolStatusCode } from "#types";
-import { TlvIntermediateCertificate, TlvOperationalCertificate } from "../../certificate/CertificateManager.js";
 import { Fabric } from "../../fabric/Fabric.js";
 import { MessageExchange } from "../../protocol/MessageExchange.js";
 import {
@@ -171,7 +171,7 @@ export class CaseClient {
             const {
                 ellipticCurvePublicKey: peerPublicKey,
                 subject: { fabricId: peerFabricIdNOCert, nodeId: peerNodeIdNOCert },
-            } = TlvOperationalCertificate.decode(peerNoc);
+            } = Noc.fromTlv(peerNoc).cert;
 
             await crypto.verifyEcdsa(PublicKey(peerPublicKey), peerSignatureData, peerSignature);
 
@@ -188,7 +188,7 @@ export class CaseClient {
             if (peerIcac !== undefined) {
                 const {
                     subject: { fabricId: peerFabricIdIcaCert },
-                } = TlvIntermediateCertificate.decode(peerIcac);
+                } = Icac.fromTlv(peerIcac).cert;
 
                 if (peerFabricIdIcaCert !== undefined && peerFabricIdIcaCert !== fabric.fabricId) {
                     throw new UnexpectedDataError(

package/src/session/case/CaseServer.ts

@@ -4,11 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Noc } from "#certificate/index.js";
 import { Bytes, Crypto, CryptoDecryptError, Logger, PublicKey, UnexpectedDataError } from "#general";
 import { TlvSessionParameters } from "#session/pase/PaseMessages.js";
 import { ResumptionRecord, SessionManager } from "#session/SessionManager.js";
 import { NodeId, ProtocolStatusCode, SECURE_CHANNEL_PROTOCOL_ID, TypeFromSchema } from "#types";
-import { TlvOperationalCertificate } from "../../certificate/CertificateManager.js";
 import { FabricManager, FabricNotFoundError } from "../../fabric/FabricManager.js";
 import { MessageExchange } from "../../protocol/MessageExchange.js";
 import { ProtocolHandler } from "../../protocol/ProtocolHandler.js";
@@ -248,7 +248,7 @@ export class CaseServer implements ProtocolHandler {
         const {
             ellipticCurvePublicKey: peerPublicKey,
             subject: { fabricId: peerFabricId, nodeId: peerNodeId, caseAuthenticatedTags },
-        } = TlvOperationalCertificate.decode(peerNewOpCert);
+        } = Noc.fromTlv(peerNewOpCert).cert;
 
         if (fabric.fabricId !== peerFabricId) {
             throw new UnexpectedDataError(`Fabric ID mismatch: ${fabric.fabricId} !== ${peerFabricId}`);