@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/session/pase/PaseClient.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Crypto, ec, Logger, PbkdfParameters, Spake2p, UnexpectedDataError } from "#general";
+import { SessionManager } from "#session/SessionManager.js";
+import { CommissioningOptions, NodeId } from "#types";
+import { MessageExchange } from "../../protocol/MessageExchange.js";
+import { SessionParameters } from "../Session.js";
+import { DEFAULT_PASSCODE_ID, PaseClientMessenger, SPAKE_CONTEXT } from "./PaseMessenger.js";
+
+const { numberToBytesBE } = ec;
+
+const logger = Logger.get("PaseClient");
+
+export class PaseClient {
+    #sessions: SessionManager;
+
+    constructor(sessions: SessionManager) {
+        this.#sessions = sessions;
+    }
+
+    static async generatePakePasscodeVerifier(setupPinCode: number, pbkdfParameters: PbkdfParameters) {
+        const { w0, L } = await Spake2p.computeW0L(pbkdfParameters, setupPinCode);
+        return Bytes.concat(numberToBytesBE(w0, 32), L);
+    }
+
+    static generateRandomPasscode() {
+        let passcode: number;
+        passcode = (Crypto.getRandomUInt32() % 99999998) + 1; // prevents 00000000 and 99999999
+        if (CommissioningOptions.FORBIDDEN_PASSCODES.includes(passcode)) {
+            passcode += 1; // With current forbidden passcode list can never collide
+        }
+        return passcode;
+    }
+
+    static generateRandomDiscriminator() {
+        return Crypto.getRandomUInt16() % 4096;
+    }
+
+    async pair(sessionParameters: SessionParameters, exchange: MessageExchange, setupPin: number) {
+        const messenger = new PaseClientMessenger(exchange);
+        const initiatorRandom = Crypto.getRandom();
+        const initiatorSessionId = await this.#sessions.getNextAvailableSessionId(); // Initiator Session Id
+
+        // Send pbkdfRequest and Read pbkdfResponse
+        const requestPayload = await messenger.sendPbkdfParamRequest({
+            initiatorRandom,
+            initiatorSessionId,
+            passcodeId: DEFAULT_PASSCODE_ID,
+            hasPbkdfParameters: false,
+            initiatorSessionParams: sessionParameters,
+        });
+        const {
+            responsePayload,
+            response: { pbkdfParameters, responderSessionId, responderSessionParams },
+        } = await messenger.readPbkdfParamResponse();
+        if (pbkdfParameters === undefined)
+            throw new UnexpectedDataError("Missing requested PbkdfParameters in the response.");
+
+        // This includes the Fallbacks for the session parameters overridden by what was sent by the device in PbkdfResponse
+        sessionParameters = {
+            ...exchange.session.parameters,
+            ...(responderSessionParams ?? {}),
+        };
+
+        // Compute pake1 and read pake2
+        const { w0, w1 } = await Spake2p.computeW0W1(pbkdfParameters, setupPin);
+        const spake2p = Spake2p.create(Crypto.hash([SPAKE_CONTEXT, requestPayload, responsePayload]), w0);
+        const X = spake2p.computeX();
+        await messenger.sendPasePake1({ x: X });
+
+        // Process pack2 and send pake3
+        const { y: Y, verifier } = await messenger.readPasePake2();
+        const { Ke, hAY, hBX } = await spake2p.computeSecretAndVerifiersFromY(w1, X, Y);
+        if (!Bytes.areEqual(verifier, hBX))
+            throw new UnexpectedDataError("Received incorrect key confirmation from the receiver.");
+        await messenger.sendPasePake3({ verifier: hAY });
+
+        // All good! Creating the secure session
+        await messenger.waitForSuccess("Success after PASE Pake3");
+        const secureSession = await this.#sessions.createSecureSession({
+            sessionId: initiatorSessionId,
+            fabric: undefined,
+            peerNodeId: NodeId.UNSPECIFIED_NODE_ID,
+            peerSessionId: responderSessionId,
+            sharedSecret: Ke,
+            salt: new Uint8Array(0),
+            isInitiator: true,
+            isResumption: false,
+            peerSessionParameters: sessionParameters,
+        });
+        await messenger.close();
+        logger.info(`Pase client: Paired successfully with ${messenger.getChannelName()}.`);
+
+        return secureSession;
+    }
+}

package/src/session/pase/PaseMessages.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { CRYPTO_HASH_LEN_BYTES, CRYPTO_PUBLIC_KEY_SIZE_BYTES } from "#general";
+import { TlvBoolean, TlvByteString, TlvField, TlvObject, TlvOptionalField, TlvUInt16, TlvUInt32 } from "#types";
+
+/** @see {@link MatterSpecification.v13.Core} § 4.12.8 */
+export const TlvSessionParameters = TlvObject({
+    /** Maximum sleep interval of node when in idle mode. */
+    idleIntervalMs: TlvOptionalField(1, TlvUInt32) /* default: SESSION_IDLE_INTERVAL */,
+
+    /** Maximum sleep interval of node when in active mode. */
+    activeIntervalMs: TlvOptionalField(2, TlvUInt32) /* default: SESSION_ACTIVE_INTERVAL */,
+
+    /** Minimum amount of time the node SHOULD stay active after network activity. */
+    activeThresholdMs: TlvOptionalField(3, TlvUInt16) /* default: SESSION_ACTIVE_THRESHOLD */,
+
+    /** Data model revision. */
+    dataModelRevision: TlvOptionalField(4, TlvUInt16) /* default: 16 OR 17, we choose 17 aka Matter 1.2 */,
+
+    /** Interaction model revision. */
+    interactionModelRevision: TlvOptionalField(5, TlvUInt16) /* default 10 OR 11, we choose 11 aka Matter 1.2 */,
+
+    /** Specification version. */
+    specificationVersion: TlvOptionalField(6, TlvUInt32) /* default: STRICTLY SMALLER THAN 0x01030000, we choose 0 */,
+
+    /** Maximum Paths pert Invoke */
+    maxPathsPerInvoke: TlvOptionalField(7, TlvUInt16) /* default: 1 */,
+});
+
+/** @see {@link MatterSpecification.v13.Core} § 4.14.1.2 */
+export const TlvPbkdfParamRequest = TlvObject({
+    initiatorRandom: TlvField(1, TlvByteString.bound({ length: 32 })),
+    initiatorSessionId: TlvField(2, TlvUInt16), // Specs: range: 16bits
+    passcodeId: TlvField(3, TlvUInt16), // Specs: length: 16bits so min is 0x8000?
+    hasPbkdfParameters: TlvField(4, TlvBoolean),
+    initiatorSessionParams: TlvOptionalField(5, TlvSessionParameters),
+});
+
+/** @see {@link MatterSpecification.v13.Core} § 4.14.1.2 */
+export const TlvPbkdfParamResponse = TlvObject({
+    initiatorRandom: TlvField(1, TlvByteString.bound({ length: 32 })),
+    responderRandom: TlvField(2, TlvByteString.bound({ length: 32 })),
+    responderSessionId: TlvField(3, TlvUInt16),
+    pbkdfParameters: TlvOptionalField(
+        4,
+        TlvObject({
+            iterations: TlvField(1, TlvUInt32),
+            salt: TlvField(2, TlvByteString.bound({ minLength: 16, maxLength: 32 })),
+        }),
+    ),
+    responderSessionParams: TlvOptionalField(5, TlvSessionParameters),
+});
+
+/** @see {@link MatterSpecification.v13.Core} § 4.14.1.2 */
+export const TlvPasePake1 = TlvObject({
+    x: TlvField(1, TlvByteString.bound({ length: CRYPTO_PUBLIC_KEY_SIZE_BYTES })), // pA
+});
+
+/** @see {@link MatterSpecification.v13.Core} § 4.14.1.2 */
+export const TlvPasePake2 = TlvObject({
+    y: TlvField(1, TlvByteString.bound({ length: CRYPTO_PUBLIC_KEY_SIZE_BYTES })), // pB
+    verifier: TlvField(2, TlvByteString.bound({ length: CRYPTO_HASH_LEN_BYTES })), // cB
+});
+
+/** @see {@link MatterSpecification.v13.Core} § 4.14.1.2 */
+export const TlvPasePake3 = TlvObject({
+    verifier: TlvField(1, TlvByteString.bound({ length: CRYPTO_HASH_LEN_BYTES })), // cA
+});

package/src/session/pase/PaseMessenger.ts

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "#general";
+import { SecureMessageType, TypeFromSchema } from "#types";
+import {
+    DEFAULT_NORMAL_PROCESSING_TIME_MS,
+    SecureChannelMessenger,
+} from "../../securechannel/SecureChannelMessenger.js";
+import {
+    TlvPasePake1,
+    TlvPasePake2,
+    TlvPasePake3,
+    TlvPbkdfParamRequest,
+    TlvPbkdfParamResponse,
+} from "./PaseMessages.js";
+
+export const DEFAULT_PASSCODE_ID = 0;
+export const SPAKE_CONTEXT = Bytes.fromString("CHIP PAKE V1 Commissioning");
+
+type PbkdfParamRequest = TypeFromSchema<typeof TlvPbkdfParamRequest>;
+type PbkdfParamResponse = TypeFromSchema<typeof TlvPbkdfParamResponse>;
+type PasePake1 = TypeFromSchema<typeof TlvPasePake1>;
+type PasePake2 = TypeFromSchema<typeof TlvPasePake2>;
+type PasePake3 = TypeFromSchema<typeof TlvPasePake3>;
+
+export class PaseServerMessenger extends SecureChannelMessenger {
+    async readPbkdfParamRequest() {
+        const { payload } = await this.nextMessage(
+            "PASE PbkdfParamRequest",
+            SecureMessageType.PbkdfParamRequest,
+            DEFAULT_NORMAL_PROCESSING_TIME_MS,
+        );
+        return { requestPayload: payload, request: TlvPbkdfParamRequest.decode(payload) };
+    }
+
+    async sendPbkdfParamResponse(response: PbkdfParamResponse) {
+        return this.send(response, SecureMessageType.PbkdfParamResponse, TlvPbkdfParamResponse, {
+            expectedProcessingTimeMs: DEFAULT_NORMAL_PROCESSING_TIME_MS,
+        });
+    }
+
+    readPasePake1() {
+        return this.nextMessageDecoded(SecureMessageType.PasePake1, TlvPasePake1, "PASE Pake1");
+    }
+
+    sendPasePake2(pasePake2: PasePake2) {
+        return this.send(pasePake2, SecureMessageType.PasePake2, TlvPasePake2);
+    }
+
+    readPasePake3() {
+        return this.nextMessageDecoded(SecureMessageType.PasePake3, TlvPasePake3, "PASE Pake3");
+    }
+}
+
+export class PaseClientMessenger extends SecureChannelMessenger {
+    sendPbkdfParamRequest(request: PbkdfParamRequest) {
+        return this.send(request, SecureMessageType.PbkdfParamRequest, TlvPbkdfParamRequest, {
+            expectedProcessingTimeMs: DEFAULT_NORMAL_PROCESSING_TIME_MS,
+        });
+    }
+
+    async readPbkdfParamResponse() {
+        const { payload } = await this.nextMessage(
+            "PASE PbkdfParamResponse",
+            SecureMessageType.PbkdfParamResponse,
+            DEFAULT_NORMAL_PROCESSING_TIME_MS,
+        );
+        return { responsePayload: payload, response: TlvPbkdfParamResponse.decode(payload) };
+    }
+
+    sendPasePake1(pasePake1: PasePake1) {
+        return this.send(pasePake1, SecureMessageType.PasePake1, TlvPasePake1);
+    }
+
+    readPasePake2() {
+        return this.nextMessageDecoded(SecureMessageType.PasePake2, TlvPasePake2, "PASE Pake2");
+    }
+
+    sendPasePake3(pasePake3: PasePake3) {
+        return this.send(pasePake3, SecureMessageType.PasePake3, TlvPasePake3);
+    }
+}

package/src/session/pase/PaseServer.ts

@@ -0,0 +1,187 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Bytes,
+    Crypto,
+    ec,
+    Logger,
+    MatterFlowError,
+    PbkdfParameters,
+    Spake2p,
+    Time,
+    Timer,
+    UnexpectedDataError,
+} from "#general";
+import { SessionManager } from "#session/SessionManager.js";
+import { NodeId, ProtocolStatusCode, SECURE_CHANNEL_PROTOCOL_ID } from "#types";
+import { MessageExchange } from "../../protocol/MessageExchange.js";
+import { ProtocolHandler } from "../../protocol/ProtocolHandler.js";
+import { ChannelStatusResponseError } from "../../securechannel/SecureChannelMessenger.js";
+import { DEFAULT_PASSCODE_ID, PaseServerMessenger, SPAKE_CONTEXT } from "./PaseMessenger.js";
+
+const { bytesToNumberBE } = ec;
+
+const logger = Logger.get("PaseServer");
+
+const PASE_PAIRING_TIMEOUT_MS = 60_000;
+const PASE_COMMISSIONING_MAX_ERRORS = 20;
+
+export class MaximumPasePairingErrorsReachedError extends MatterFlowError {}
+
+export class PaseServer implements ProtocolHandler {
+    private pairingTimer: Timer | undefined;
+    private pairingErrors = 0;
+
+    static async fromPin(sessions: SessionManager, setupPinCode: number, pbkdfParameters: PbkdfParameters) {
+        const { w0, L } = await Spake2p.computeW0L(pbkdfParameters, setupPinCode);
+        return new PaseServer(sessions, w0, L, pbkdfParameters);
+    }
+
+    static fromVerificationValue(
+        sessions: SessionManager,
+        verificationValue: Uint8Array,
+        pbkdfParameters?: PbkdfParameters,
+    ) {
+        const w0 = bytesToNumberBE(verificationValue.slice(0, 32));
+        const L = verificationValue.slice(32, 32 + 65);
+        return new PaseServer(sessions, w0, L, pbkdfParameters);
+    }
+
+    constructor(
+        private sessions: SessionManager,
+        private readonly w0: bigint,
+        private readonly L: Uint8Array,
+        private readonly pbkdfParameters?: PbkdfParameters,
+    ) {}
+
+    getId(): number {
+        return SECURE_CHANNEL_PROTOCOL_ID;
+    }
+
+    async onNewExchange(exchange: MessageExchange) {
+        const messenger = new PaseServerMessenger(exchange);
+        try {
+            await this.handlePairingRequest(messenger);
+        } catch (error) {
+            this.pairingErrors++;
+            logger.error(
+                `An error occurred during the PASE commissioning (${this.pairingErrors}/${PASE_COMMISSIONING_MAX_ERRORS}):`,
+                error,
+            );
+
+            // If we received a ChannelStatusResponseError we do not need to send one back, so just cancel pairing
+            const sendError = !(error instanceof ChannelStatusResponseError);
+            await this.cancelPairing(messenger, sendError);
+
+            if (this.pairingErrors >= PASE_COMMISSIONING_MAX_ERRORS) {
+                throw new MaximumPasePairingErrorsReachedError(
+                    `Pase server: Too many errors during PASE commissioning, aborting commissioning window`,
+                );
+            }
+        } finally {
+            // Destroy the unsecure session used to establish the secure Case session
+            await exchange.session.destroy();
+        }
+    }
+
+    private async handlePairingRequest(messenger: PaseServerMessenger) {
+        // When a Commissioner is either in the process of establishing a PASE session with the Commissionee or has
+        // successfully established a session, the Commissionee SHALL NOT accept any more requests for new PASE
+        // sessions until session establishment fails or the successfully established PASE session is terminated on
+        // the commissioning channel.
+        if (this.sessions.getPaseSession()) {
+            throw new MatterFlowError(
+                "Pase server: Pairing already in progress (PASE session exists), ignoring new exchange.",
+            );
+        }
+
+        if (this.pairingTimer !== undefined && this.pairingTimer.isRunning) {
+            throw new MatterFlowError(
+                "Pase server: Pairing already in progress (PASE establishment Timer running), ignoring new exchange.",
+            );
+        }
+
+        logger.info(`Received pairing request from ${messenger.getChannelName()}.`);
+
+        this.pairingTimer = Time.getTimer("PASE pairing timeout", PASE_PAIRING_TIMEOUT_MS, () =>
+            this.cancelPairing(messenger),
+        ).start();
+
+        // Read pbkdfRequest and send pbkdfResponse
+        const {
+            requestPayload,
+            request: {
+                initiatorRandom,
+                initiatorSessionParams,
+                passcodeId,
+                hasPbkdfParameters,
+                initiatorSessionId: peerSessionId,
+            },
+        } = await messenger.readPbkdfParamRequest();
+        if (passcodeId !== DEFAULT_PASSCODE_ID) {
+            throw new UnexpectedDataError(`Unsupported passcode ID ${passcodeId}.`);
+        }
+
+        const responderSessionId = await this.sessions.getNextAvailableSessionId(); // Responder Session Id
+        const responderRandom = Crypto.getRandom();
+
+        const responsePayload = await messenger.sendPbkdfParamResponse({
+            initiatorRandom,
+            responderRandom,
+            responderSessionId,
+            pbkdfParameters: hasPbkdfParameters ? undefined : this.pbkdfParameters,
+            responderSessionParams: this.sessions.sessionParameters, // responder session parameters
+        });
+
+        // Process pake1 and send pake2
+        const spake2p = Spake2p.create(Crypto.hash([SPAKE_CONTEXT, requestPayload, responsePayload]), this.w0);
+        const { x: X } = await messenger.readPasePake1();
+        const Y = spake2p.computeY();
+        const { Ke, hAY, hBX } = await spake2p.computeSecretAndVerifiersFromX(this.L, X, Y);
+        await messenger.sendPasePake2({ y: Y, verifier: hBX });
+
+        // Read and process pake3
+        const { verifier } = await messenger.readPasePake3();
+        if (!Bytes.areEqual(verifier, hAY)) {
+            throw new UnexpectedDataError("Received incorrect key confirmation from the initiator.");
+        }
+
+        // All good! Creating the secure PASE session
+        await this.sessions.createSecureSession({
+            sessionId: responderSessionId,
+            fabric: undefined,
+            peerNodeId: NodeId.UNSPECIFIED_NODE_ID,
+            peerSessionId,
+            sharedSecret: Ke,
+            salt: new Uint8Array(0),
+            isInitiator: false,
+            isResumption: false,
+            peerSessionParameters: initiatorSessionParams,
+        });
+        logger.info(`Session ${responderSessionId} created with ${messenger.getChannelName()}.`);
+
+        await messenger.sendSuccess();
+        await messenger.close();
+
+        this.pairingTimer?.stop();
+        this.pairingTimer = undefined;
+    }
+
+    async cancelPairing(messenger: PaseServerMessenger, sendError = true) {
+        this.pairingTimer?.stop();
+        this.pairingTimer = undefined;
+
+        if (sendError) {
+            await messenger.sendError(ProtocolStatusCode.InvalidParam);
+        }
+        await messenger.close();
+    }
+
+    async close() {
+        // Nothing to do
+    }
+}

package/src/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "extends": "../../tools/tsc/tsconfig.lib.json",
+    "compilerOptions": {
+        "types": [
+            "@matter/tools",
+            "globals"
+        ]
+    },
+    "references": [
+        {
+            "path": "../../general/src"
+        },
+        {
+            "path": "../../model/src"
+        },
+        {
+            "path": "../../types/src"
+        }
+    ]
+}