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

package/src/protocol/MessageReceptionState.ts

@@ -0,0 +1,207 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError, MatterError } from "#general";
+import { MAX_COUNTER_VALUE_32BIT } from "./MessageCounter.js";
+
+/** 2^31 used for Duplicate detection in some cases. */
+const MAX_COUNTER_INCREASE_2POW31 = Math.pow(2, 31);
+
+/** Maximum number of previously processed message counters to accept from a given Node and key. */
+const MSG_COUNTER_WINDOW_SIZE = 32;
+
+export class DuplicateMessageError extends MatterError {}
+
+export abstract class MessageReceptionState {
+    abstract updateMessageCounter(messageCounter: number): void;
+}
+
+/**
+ * Implements a message reception state for encrypted messages without rollover.
+ * A counter in the range [(max_message_counter + 1) to (232 - 1)] SHALL be considered new, and cause the
+ * max_message_counter value to be updated.
+ * Message counters within the range of the bitmap SHALL be considered duplicate if the corresponding bit
+ * offset is set to true. All other message counters SHALL be considered duplicate.
+ */
+export class MessageReceptionStateEncryptedWithoutRollover extends MessageReceptionState {
+    protected maximumMessageCounter: number | undefined;
+    private messageCounterBitmap = 0xffffffff; // All bits set to 1
+
+    constructor(messageCounter?: number) {
+        super();
+        if (messageCounter !== undefined) {
+            this.initialize(messageCounter);
+        }
+    }
+
+    /** Initialize the message counter state. */
+    private initialize(messageCounter: number) {
+        this.maximumMessageCounter = messageCounter;
+        this.messageCounterBitmap = 0xffffffff; // All bits set to 1
+    }
+
+    /**
+     * Calculate plain diff without rollover.
+     * This method is mainly overridden for other counter types and follow the following semantic
+     * Return number is:
+     * * negative if the new message counter is smaller than the current maximum. Smaller values within the Window size
+     *   are check separately within the window. Other smaller values are considered DUPLICATE
+     * * positive if the new message counter is larger than the current maximum and are always NEW
+     */
+    protected calculateDiff(messageCounter: number) {
+        if (this.maximumMessageCounter === undefined) {
+            return 0;
+        }
+        return messageCounter - this.maximumMessageCounter;
+    }
+
+    /** Update or move the message counter window. */
+    private calculateMessageCounterBitmap(messageCounterBitmap: number, diff: number) {
+        if (diff < 0) {
+            // negative value means the new message counter is smaller than the current maximum
+            if (diff < -MSG_COUNTER_WINDOW_SIZE) {
+                throw new InternalError(`Message counter difference too large: ${diff}`);
+            }
+            // set the corresponding bit
+            const bit = 1 << (-diff - 1);
+            messageCounterBitmap |= bit;
+        } else if (diff > 0) {
+            // positive value means new message counter is larger than the current maximum
+            if (diff <= MSG_COUNTER_WINDOW_SIZE) {
+                // shift the bitmap and set the bit for the previous maximum
+                const bit = 1 << (diff - 1);
+                messageCounterBitmap = ((messageCounterBitmap << diff) >>> 0) | bit;
+            } else {
+                // diff is larger than the window size, so no previous message counter is known
+                messageCounterBitmap = 0;
+            }
+        }
+        return messageCounterBitmap >>> 0; // Stay 32 bit unsigned integer
+    }
+
+    /** Update the message counter and window. */
+    private updateMessageCounterAndBitmap(messageCounter: number, diff: number) {
+        if (this.maximumMessageCounter === undefined) {
+            this.initialize(messageCounter);
+            return;
+        }
+
+        this.messageCounterBitmap = this.calculateMessageCounterBitmap(this.messageCounterBitmap, diff);
+
+        if (diff > 0 || diff < -MSG_COUNTER_WINDOW_SIZE) {
+            this.maximumMessageCounter = messageCounter;
+        }
+    }
+
+    /** Check if the message counter is known in the bitmap. */
+    private isCounterKnownInBitmap(diff: number) {
+        if (diff < -MSG_COUNTER_WINDOW_SIZE || diff >= 0) {
+            throw new InternalError(`Invalid Message counter difference for check: ${diff}`);
+        }
+        const bit = 1 << (-diff - 1);
+        return (this.messageCounterBitmap & bit) !== 0;
+    }
+
+    /**
+     * Returns true if the message counter is a duplicate.
+     */
+    updateMessageCounter(messageCounter: number) {
+        if (messageCounter < 0 || messageCounter > MAX_COUNTER_VALUE_32BIT) {
+            throw new InternalError(`Invalid message counter value: ${messageCounter}`);
+        }
+        if (this.maximumMessageCounter === undefined) {
+            this.updateMessageCounterAndBitmap(messageCounter, 0);
+            return;
+        }
+        if (messageCounter === this.maximumMessageCounter) {
+            throw new DuplicateMessageError("Message counter equals the maximum message counter.");
+        }
+
+        const diff = this.calculateDiff(messageCounter);
+        // A counter in the range [(max_message_counter + 1) to (232 - 1)] SHALL be considered new, and cause the
+        // max_message_counter value to be updated.
+        // Message counters within the range of the bitmap SHALL be considered duplicate if the corresponding bit
+        // offset is set to true. All other message counters SHALL be considered duplicate.
+        if (diff < 0) {
+            if (diff < -MSG_COUNTER_WINDOW_SIZE) {
+                throw new DuplicateMessageError("Message counter is considered duplicate.");
+            }
+            if (this.isCounterKnownInBitmap(diff)) {
+                throw new DuplicateMessageError("Message counter is within the message counter window and duplicate.");
+            }
+        }
+        this.updateMessageCounterAndBitmap(messageCounter, diff);
+    }
+}
+
+/**
+ * Implements a message reception state for encrypted messages with rollover.
+ * A message counter with rollover is a free running message counter that monotonically increases, but rolls
+ * over to zero when it exceeds the maximum value of the counter (32-bits). If the difference is below 2^31 then it is
+ * considered a rollover and not a smaller value
+ */
+export class MessageReceptionStateEncryptedWithRollover extends MessageReceptionStateEncryptedWithoutRollover {
+    protected override calculateDiff(messageCounter: number) {
+        if (this.maximumMessageCounter === undefined) {
+            return 0;
+        }
+        // A message counter with rollover is a free running message counter that monotonically increases, but rolls
+        // over to zero when it exceeds the maximum value of the counter (32-bits). if the difference is below 2^31 then it is considered a rollover and not a smaller value
+        const diff = messageCounter - this.maximumMessageCounter;
+
+        if (diff > 0) {
+            // positive value means new message counter is larger than the current maximum
+            if (diff < MAX_COUNTER_INCREASE_2POW31) {
+                return diff;
+            }
+            return diff - MAX_COUNTER_VALUE_32BIT - 1;
+        } else if (diff < 0) {
+            // negative value means the new message counter is smaller than the current maximum
+            if (diff >= -MAX_COUNTER_INCREASE_2POW31) {
+                return diff;
+            }
+            return diff + MAX_COUNTER_VALUE_32BIT + 1;
+        }
+        return 0;
+    }
+}
+
+/**
+ * Implements a message reception state for unencrypted messages without rollover.
+ * Any message counter equal to max_message_counter or within the message counter window, where the corresponding bit
+ * is set to true SHALL be considered duplicate. All other message counters, whether behind the window or ahead of
+ * max_message_counter, are considered new and SHALL update max_message_counter and shift the window accordingly.
+ * Messages with a counter behind the window are likely caused by a node rebooting and are thus processed as rolling
+ * back the window to the current location.
+ */
+export class MessageReceptionStateUnencryptedWithRollover extends MessageReceptionStateEncryptedWithoutRollover {
+    protected override calculateDiff(messageCounter: number) {
+        if (this.maximumMessageCounter === undefined) {
+            return 0;
+        }
+        // A message counter with rollover is a free running message counter that monotonically increases, but rolls
+        // over to zero when it exceeds the maximum value of the counter (32-bits).
+        // Any message counter equal to max_message_counter or within the message counter window, where the corresponding
+        // bit is set to true SHALL be considered duplicate. All other message counters, whether behind the window or
+        // ahead of max_message_counter, are considered new and SHALL update max_message_counter
+        const diff = messageCounter - this.maximumMessageCounter;
+
+        if (diff > 0) {
+            // positive value means new message counter is larger than the current maximum
+            if (-diff + MAX_COUNTER_VALUE_32BIT < MSG_COUNTER_WINDOW_SIZE) {
+                return diff - MAX_COUNTER_VALUE_32BIT - 1;
+            }
+            return diff;
+        } else if (diff < 0) {
+            // negative value means the new message counter is smaller than the current maximum
+            if (diff < -MSG_COUNTER_WINDOW_SIZE) {
+                return MAX_COUNTER_VALUE_32BIT + diff;
+            }
+            return diff;
+        }
+        return 0;
+    }
+}

package/src/protocol/ProtocolHandler.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Message } from "../codec/MessageCodec.js";
+import { MessageExchange } from "./MessageExchange.js";
+
+export interface ProtocolHandler {
+    getId(): number;
+    onNewExchange(exchange: MessageExchange, message: Message): Promise<void>;
+    close(): Promise<void>;
+}

package/src/protocol/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./ChannelManager.js";
+export * from "./DeviceAdvertiser.js";
+export * from "./DeviceCommissioner.js";
+export * from "./ExchangeManager.js";
+export * from "./MessageCounter.js";
+export * from "./MessageExchange.js";
+export * from "./MessageReceptionState.js";
+export * from "./ProtocolHandler.js";

package/src/securechannel/SecureChannelMessenger.ts

@@ -0,0 +1,166 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterError, UnexpectedDataError } from "#general";
+import {
+    GeneralStatusCode,
+    ProtocolStatusCode,
+    SECURE_CHANNEL_PROTOCOL_ID,
+    SecureMessageType,
+    TlvSchema,
+} from "#types";
+import { Message } from "../codec/MessageCodec.js";
+import { ExchangeSendOptions, MessageExchange } from "../protocol/MessageExchange.js";
+import { TlvSecureChannelStatusMessage } from "./SecureChannelStatusMessageSchema.js";
+
+/** Error base Class for all errors related to the status response messages. */
+export class ChannelStatusResponseError extends MatterError {
+    public constructor(
+        message: string,
+        public readonly generalStatusCode: GeneralStatusCode,
+        public readonly protocolStatusCode: ProtocolStatusCode,
+    ) {
+        super(`(${generalStatusCode}/${protocolStatusCode}) ${message}`);
+    }
+}
+
+/** This value is used by chip SDK when performance wise heavy crypto operations are expected. */
+export const EXPECTED_CRYPTO_PROCESSING_TIME_MS = 30_000;
+
+/** This value is used by chip SDK when normal processing time is expected. */
+export const DEFAULT_NORMAL_PROCESSING_TIME_MS = 2_000;
+
+export class SecureChannelMessenger {
+    #defaultExpectedProcessingTimeMs: number;
+
+    constructor(
+        protected readonly exchange: MessageExchange,
+        defaultExpectedProcessingTimeMs = EXPECTED_CRYPTO_PROCESSING_TIME_MS,
+    ) {
+        this.#defaultExpectedProcessingTimeMs = defaultExpectedProcessingTimeMs;
+    }
+
+    /**
+     * Waits for the next message and returns it.
+     * When no expectedProcessingTimeMs is provided, the default value of EXPECTED_CRYPTO_PROCESSING_TIME_MS is used.
+     */
+    async nextMessage(
+        expectedMessageInfo: string,
+        expectedMessageType?: number,
+        expectedProcessingTimeMs = this.#defaultExpectedProcessingTimeMs,
+    ) {
+        const message = await this.exchange.nextMessage(expectedProcessingTimeMs);
+        const messageType = message.payloadHeader.messageType;
+        this.throwIfErrorStatusReport(message, expectedMessageInfo);
+        if (expectedMessageType !== undefined && messageType !== expectedMessageType)
+            throw new UnexpectedDataError(
+                `Received unexpected message type: ${messageType}, expected: ${expectedMessageType} (${expectedMessageInfo})`,
+            );
+        return message;
+    }
+
+    /**
+     * Waits for the next message and decodes it.
+     * When no expectedProcessingTimeMs is provided, the default value of EXPECTED_CRYPTO_PROCESSING_TIME_MS is used.
+     */
+    async nextMessageDecoded<T>(
+        expectedMessageType: number,
+        schema: TlvSchema<T>,
+        expectedMessageInfo: string,
+        expectedProcessingTimeMs = this.#defaultExpectedProcessingTimeMs,
+    ) {
+        return schema.decode(
+            (await this.nextMessage(expectedMessageInfo, expectedMessageType, expectedProcessingTimeMs)).payload,
+        );
+    }
+
+    /**
+     * Waits for the next message and returns it.
+     * When no expectedProcessingTimeMs is provided, the default value of EXPECTED_CRYPTO_PROCESSING_TIME_MS is used.
+     */
+    async waitForSuccess(
+        expectedMessageInfo: string,
+        expectedProcessingTimeMs = this.#defaultExpectedProcessingTimeMs,
+    ) {
+        // If the status is not Success, this would throw an Error.
+        await this.nextMessage(expectedMessageInfo, SecureMessageType.StatusReport, expectedProcessingTimeMs);
+    }
+
+    /**
+     * Sends a message of the given type with the given payload.
+     * If no ExchangeSendOptions are provided, the expectedProcessingTimeMs will be set to
+     * EXPECTED_CRYPTO_PROCESSING_TIME_MS.
+     */
+    async send<T>(message: T, type: number, schema: TlvSchema<T>, options?: ExchangeSendOptions) {
+        options = {
+            ...options,
+            expectedProcessingTimeMs: options?.expectedProcessingTimeMs ?? this.#defaultExpectedProcessingTimeMs,
+        };
+        const payload = schema.encode(message);
+        await this.exchange.send(type, payload, options);
+        return payload;
+    }
+
+    sendError(code: ProtocolStatusCode) {
+        return this.sendStatusReport(GeneralStatusCode.Failure, code);
+    }
+
+    sendSuccess() {
+        return this.sendStatusReport(GeneralStatusCode.Success, ProtocolStatusCode.Success);
+    }
+
+    sendCloseSession() {
+        return this.sendStatusReport(GeneralStatusCode.Success, ProtocolStatusCode.CloseSession, false);
+    }
+
+    getChannelName() {
+        return this.exchange.channel.channel.name;
+    }
+
+    async close() {
+        await this.exchange.close();
+    }
+
+    private async sendStatusReport(
+        generalStatus: GeneralStatusCode,
+        protocolStatus: ProtocolStatusCode,
+        requiresAck?: boolean,
+    ) {
+        await this.exchange.send(
+            SecureMessageType.StatusReport,
+            TlvSecureChannelStatusMessage.encode({
+                generalStatus,
+                protocolId: SECURE_CHANNEL_PROTOCOL_ID,
+                protocolStatus,
+            }),
+            { requiresAck },
+        );
+    }
+
+    protected throwIfErrorStatusReport(message: Message, logHint?: string) {
+        const {
+            payloadHeader: { messageType },
+            payload,
+        } = message;
+        if (messageType !== SecureMessageType.StatusReport) return;
+
+        const { generalStatus, protocolId, protocolStatus } = TlvSecureChannelStatusMessage.decode(payload);
+        if (generalStatus !== GeneralStatusCode.Success) {
+            throw new ChannelStatusResponseError(
+                `Received general error status for protocol ${protocolId}${logHint ? ` (${logHint})` : ""}`,
+                generalStatus,
+                protocolStatus,
+            );
+        }
+        if (protocolStatus !== ProtocolStatusCode.Success) {
+            throw new ChannelStatusResponseError(
+                `Received general success status, but protocol status is not Success${logHint ? ` (${logHint})` : ""}`,
+                generalStatus,
+                protocolStatus,
+            );
+        }
+    }
+}

package/src/securechannel/SecureChannelProtocol.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { FabricManager } from "#fabric/FabricManager.js";
+import { AsyncObservable, Logger, MatterFlowError } from "#general";
+import { SessionManager } from "#session/SessionManager.js";
+import {
+    GeneralStatusCode,
+    ProtocolStatusCode,
+    SECURE_CHANNEL_PROTOCOL_ID,
+    SecureMessageType,
+    StatusCode,
+    StatusResponseError,
+} from "#types";
+import { Message } from "../codec/MessageCodec.js";
+import { MessageExchange } from "../protocol/MessageExchange.js";
+import { ProtocolHandler } from "../protocol/ProtocolHandler.js";
+import { assertSecureSession } from "../session/SecureSession.js";
+import { CaseServer } from "../session/case/CaseServer.js";
+import { MaximumPasePairingErrorsReachedError, PaseServer } from "../session/pase/PaseServer.js";
+import { ChannelStatusResponseError, SecureChannelMessenger } from "./SecureChannelMessenger.js";
+import { TlvSecureChannelStatusMessage } from "./SecureChannelStatusMessageSchema.js";
+
+const logger = Logger.get("SecureChannelProtocol");
+
+export class StatusReportOnlySecureChannelProtocol implements ProtocolHandler {
+    getId(): number {
+        return SECURE_CHANNEL_PROTOCOL_ID;
+    }
+
+    async onNewExchange(exchange: MessageExchange, message: Message) {
+        const messageType = message.payloadHeader.messageType;
+
+        switch (messageType) {
+            case SecureMessageType.StatusReport:
+                await this.handleInitialStatusReport(exchange, message);
+                break;
+            default:
+                // We silently ignore incoming Standalone Ack messages that we do not expect here
+                if (messageType !== SecureMessageType.StandaloneAck) {
+                    throw new StatusResponseError(
+                        `Unexpected initial message on secure channel protocol: ${messageType.toString(16)}`,
+                        StatusCode.InvalidAction,
+                    );
+                }
+        }
+    }
+
+    async handleInitialStatusReport(exchange: MessageExchange, message: Message) {
+        const {
+            payloadHeader: { messageType },
+            payload,
+        } = message;
+        if (messageType !== SecureMessageType.StatusReport) {
+            throw new MatterFlowError(
+                `Unexpected message type on secure channel protocol, expected StatusReport: ${messageType.toString(
+                    16,
+                )}`,
+            );
+        }
+
+        const { generalStatus, protocolId, protocolStatus } = TlvSecureChannelStatusMessage.decode(payload);
+        if (generalStatus !== GeneralStatusCode.Success) {
+            throw new ChannelStatusResponseError(
+                `Received general error status (${protocolId})`,
+                generalStatus,
+                protocolStatus,
+            );
+        }
+        if (protocolStatus !== ProtocolStatusCode.CloseSession) {
+            throw new ChannelStatusResponseError(
+                `Received general success status, but protocol status is not CloseSession`,
+                generalStatus,
+                protocolStatus,
+            );
+        }
+
+        const { session } = exchange;
+        assertSecureSession(session);
+        logger.debug(`Peer requested to close session ${session.name}. Remove session now.`);
+        // TODO: and do more - see Core Specs 5.5
+        await session.destroy(false, false);
+    }
+
+    async close() {
+        // Nothing to do
+    }
+}
+
+export class SecureChannelProtocol extends StatusReportOnlySecureChannelProtocol {
+    #paseCommissioner: PaseServer | undefined;
+    readonly #caseCommissioner: CaseServer;
+    readonly #tooManyPaseErrors = AsyncObservable<[]>();
+
+    constructor(sessions: SessionManager, fabrics: FabricManager) {
+        super();
+        this.#caseCommissioner = new CaseServer(sessions, fabrics);
+    }
+
+    /**
+     * Emitted when the active PASE session hits the maximum error threshold.
+     */
+    get tooManyPaseErrors() {
+        return this.#tooManyPaseErrors;
+    }
+
+    setPaseCommissioner(paseServer: PaseServer) {
+        this.#paseCommissioner = paseServer;
+    }
+
+    removePaseCommissioner() {
+        this.#paseCommissioner = undefined;
+    }
+
+    override async onNewExchange(exchange: MessageExchange, message: Message) {
+        const messageType = message.payloadHeader.messageType;
+
+        switch (messageType) {
+            case SecureMessageType.PbkdfParamRequest:
+                if (this.#paseCommissioner === undefined) {
+                    // Cleaner to return an error (ok for chip-tool as it seems)?
+                    // Formally we should not respond at all which leads to retries and such
+                    const messenger = new SecureChannelMessenger(exchange);
+                    await messenger.sendError(ProtocolStatusCode.InvalidParam);
+                    await messenger.close(); // also closes exchange
+                    return;
+                }
+                try {
+                    await this.#paseCommissioner.onNewExchange(exchange);
+                } catch (error) {
+                    MaximumPasePairingErrorsReachedError.accept(error);
+
+                    await this.#tooManyPaseErrors.emit();
+                }
+                break;
+            case SecureMessageType.Sigma1:
+                await this.#caseCommissioner.onNewExchange(exchange);
+                break;
+            default:
+                await super.onNewExchange(exchange, message);
+        }
+    }
+
+    static isStandaloneAck(protocolId: number, messageType: number) {
+        return protocolId === SECURE_CHANNEL_PROTOCOL_ID && messageType === SecureMessageType.StandaloneAck;
+    }
+}

package/src/securechannel/SecureChannelStatusMessageSchema.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DataReader, DataWriter, Endian } from "#general";
+import { GeneralStatusCode, ProtocolStatusCode, Schema } from "#types";
+
+export type StatusMessage = {
+    generalStatus: GeneralStatusCode;
+    protocolId: number;
+    protocolStatus: ProtocolStatusCode;
+    protocolData?: Uint8Array;
+};
+
+export class SecureChannelStatusMessageSchema extends Schema<StatusMessage, Uint8Array> {
+    encodeInternal({ generalStatus, protocolId, protocolStatus, protocolData }: StatusMessage) {
+        const writer = new DataWriter(Endian.Little);
+        writer.writeUInt16(generalStatus);
+        writer.writeUInt32(protocolId);
+        writer.writeUInt16(protocolStatus);
+        if (protocolData !== undefined && protocolData.length > 0) {
+            writer.writeByteArray(protocolData);
+        }
+        return writer.toByteArray();
+    }
+
+    decodeInternal(bytes: Uint8Array) {
+        const reader = new DataReader(bytes, Endian.Little);
+        const generalStatus = reader.readUInt16();
+        const protocolId = reader.readUInt32();
+        const protocolStatus = reader.readUInt16();
+        const remainingBytes = reader.getRemainingBytesCount() > 0 ? reader.getRemainingBytes() : undefined;
+
+        return { generalStatus, protocolId, protocolStatus, remainingBytes };
+    }
+}
+
+export const TlvSecureChannelStatusMessage = new SecureChannelStatusMessageSchema();

package/src/securechannel/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Export SecureChannel Classes
+export * from "./SecureChannelMessenger.js";
+export * from "./SecureChannelProtocol.js";
+export * from "./SecureChannelStatusMessageSchema.js";