/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Mark } from "#common/Mark.js"; import { SessionManager } from "#session/SessionManager.js"; import { SessionParameters } from "#session/SessionParameters.js"; import { Abort, Bytes, causedBy, Channel, Crypto, InternalError, Logger, Diagnostic, MatterError, NetworkError, PbkdfParameters, Spake2p, UnexpectedDataError, } from "@matter/general"; import { isValidPasscode, NodeId, SecureChannelStatusCode } from "@matter/types"; import { TransientPeerCommunicationError } from "../../peer/PeerCommunicationError.js"; import { RetransmissionLimitReachedError } from "../../protocol/errors.js"; import { MessageExchange } from "../../protocol/MessageExchange.js"; import { DEFAULT_PASSCODE_ID, PaseClientMessenger, SPAKE_CONTEXT } from "./PaseMessenger.js"; const logger = Logger.get("PaseClient"); const MAX_PASSCODE_GENERATION_ATTEMPTS = 100; /** * The responder's key confirmation (Pake2 cB) does not verify: the passcode is wrong for the device at this address, or * a stale address reached another device in commissioning mode. * * @see {@link MatterSpecification.v161.Core} ยง 4.14.1.2.7 */ export class PasscodeMismatchError extends UnexpectedDataError {} export class PaseClient { #sessions: SessionManager; constructor(sessions: SessionManager) { this.#sessions = sessions; } static async generatePakePasscodeVerifier(crypto: Crypto, setupPinCode: number, pbkdfParameters: PbkdfParameters) { const { w0, L } = await Spake2p.computeW0L(crypto, pbkdfParameters, setupPinCode); return Bytes.concat(Bytes.fromBigInt(w0, 32), L); } static generateRandomPasscode(crypto: Crypto) { // Generate 27-bit random candidates and reject invalid values to avoid modulo bias. for (let i = 0; i < MAX_PASSCODE_GENERATION_ATTEMPTS; i++) { const passcode = crypto.randomUint32 & 0x07ff_ffff; if (isValidPasscode(passcode)) { return passcode; } } throw new InternalError( `Unable to generate valid passcode in ${MAX_PASSCODE_GENERATION_ATTEMPTS} tries; entropy source is broken`, ); } static generateRandomDiscriminator(crypto: Crypto) { return crypto.randomUint16 % 4096; } async pair( initiatorSessionParams: SessionParameters, exchange: MessageExchange, channel: Channel, setupPin: number, options?: PaseClient.PairOptions, ) { const messenger = new PaseClientMessenger(exchange); const abort = new Abort({ abort: options?.abort }); try { return await this.#doPair( initiatorSessionParams, messenger, exchange, channel, setupPin, abort, options?.suppressPeerLoss, options?.onPbkdfParamResponse, ); } catch (error) { // Unlike CASE, for PASE we send InvalidParam even on abort. This signals the device to reset its // pairing state immediately, preventing a 60-second lockdown when cancelling parallel commissioning. // Skip when a sent message is still unacked: the peer never acknowledged our prior message, so the // device has no pairing state to reset and the send would only fail with a flow error. if ( !exchange.hasUnackedMessage && !causedBy(error, NetworkError, TransientPeerCommunicationError, RetransmissionLimitReachedError) ) { try { // Intentionally not passing the abort signal: we WANT to send InvalidParam even when // aborting to signal the device to reset its pairing state immediately. Passing an // already-aborted signal would cause the send to fail instantly without notifying the // device, leaving it in a 60-second lockdown. The enclosing try/catch absorbs failures. await messenger.sendError(SecureChannelStatusCode.InvalidParam); } catch (e) { MatterError.accept(e); logger.debug("Failed to send InvalidParam on PASE error:", Diagnostic.errorMessage(e)); } } throw error; } finally { abort.close(); try { await messenger.close(); } catch (e) { logger.error("Unhandled error closing PASE messenger:", e); } } } async #doPair( initiatorSessionParams: SessionParameters, messenger: PaseClientMessenger, exchange: MessageExchange, channel: Channel, setupPin: number, abort: Abort, suppressPeerLoss?: boolean, onPbkdfParamResponse?: () => void, ) { const { crypto } = this.#sessions; const initiatorRandom = crypto.randomBytes(32); const initiatorSessionId = await abort.attempt(this.#sessions.getNextAvailableSessionId()); // Send pbkdfRequest and read pbkdfResponse const requestPayload = await abort.attempt( messenger.sendPbkdfParamRequest( { initiatorRandom, initiatorSessionId, passcodeId: DEFAULT_PASSCODE_ID, hasPbkdfParameters: false, initiatorSessionParams, }, { abort: abort.signal }, ), ); const { responsePayload, response: { pbkdfParameters, responderSessionId, responderSessionParams }, } = await messenger.readPbkdfParamResponse({ abort: abort.signal }); onPbkdfParamResponse?.(); if (pbkdfParameters === undefined) { throw new UnexpectedDataError("Missing requested PbkdfParameters in the response. Commissioning failed."); } // Update the session timing parameters with the just received ones to optimize the session establishment if (responderSessionParams !== undefined) { exchange.session.timingParameters = responderSessionParams; } // This includes the Fallbacks for the session parameters overridden by what was sent by the device in PbkdfResponse const peerSessionParameters = { ...exchange.session.parameters, ...(responderSessionParams ?? {}), }; // Compute pake1 and read pake2 const { w0, w1 } = await abort.attempt(Spake2p.computeW0W1(crypto, pbkdfParameters, setupPin)); const spake2p = Spake2p.create( crypto, await abort.attempt(crypto.computeHash([SPAKE_CONTEXT, requestPayload, responsePayload])), w0, ); const X = spake2p.computeX(); await abort.attempt(messenger.sendPasePake1({ x: X }, { abort: abort.signal })); // Process pake2 and send pake3 const { y: Y, verifier } = await messenger.readPasePake2({ abort: abort.signal }); const { Ke, hAY, hBX } = await abort.attempt(spake2p.computeSecretAndVerifiersFromY(w1, X, Y)); if (!Bytes.areEqual(verifier, hBX)) { throw new PasscodeMismatchError( "PASE key confirmation from the device does not match: the passcode is wrong for this device", ); } // Intentional: no abort.attempt / abort.race below. Once Pake3 is sent the device has committed its PASE // state; aborting here would leave it in limbo for 60s. Any caller that no longer wants this session is // responsible for closing it after we return. await messenger.sendPasePake3({ verifier: hAY }); await messenger.waitForSuccess({ description: "PasePake3-Success" }); const secureSession = await this.#sessions.createSecureSession({ channel, id: initiatorSessionId, fabric: undefined, peerNodeId: NodeId.UNSPECIFIED_NODE_ID, peerSessionId: responderSessionId, sharedSecret: Ke, salt: new Uint8Array(0), isInitiator: true, isResumption: false, peerSessionParameters, reportedSessionParameters: responderSessionParams, suppressPeerLoss, }); logger.info("Paired successfully", Mark.OUTBOUND, messenger.channelName, exchange.diagnostics); return secureSession; } } export namespace PaseClient { export interface PairOptions { abort?: AbortSignal; /** @see {@link NodeSession.suppressPeerLoss} */ suppressPeerLoss?: boolean; /** Called once the responder has answered the PBKDFParamRequest. */ onPbkdfParamResponse?: () => void; } }