/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Icac } from "#certificate/kinds/Icac.js"; import { Noc } from "#certificate/kinds/Noc.js"; import { Fabric } from "#fabric/Fabric.js"; import { TransientPeerCommunicationError } from "#peer/PeerCommunicationError.js"; import { RetransmissionLimitReachedError } from "#protocol/errors.js"; import { ExchangeSendOptions, MessageExchange } from "#protocol/MessageExchange.js"; import { NodeSession } from "#session/NodeSession.js"; import { SessionManager } from "#session/SessionManager.js"; import { SessionParameters } from "#session/SessionParameters.js"; import { Abort, Bytes, causedBy, Duration, EcdsaSignature, Logger, Diagnostic, MatterError, NetworkError, PublicKey, UnexpectedDataError, } from "@matter/general"; import { CaseAuthenticatedTag, NodeId, SecureChannelStatusCode } from "@matter/types"; import { KDFSR1_KEY_INFO, KDFSR2_INFO, KDFSR2_KEY_INFO, KDFSR3_INFO, RESUME1_MIC_NONCE, RESUME2_MIC_NONCE, TBE_DATA2_NONCE, TBE_DATA3_NONCE, TlvEncryptedDataSigma2, TlvEncryptedDataSigma3, TlvSignedData, } from "./CaseMessages.js"; import { CaseClientMessenger } from "./CaseMessenger.js"; const logger = Logger.get("CaseClient"); export class CaseClient { #sessions: SessionManager; constructor(sessions: SessionManager) { this.#sessions = sessions; } async pair(exchange: MessageExchange, fabric: Fabric, peerNodeId: NodeId, options?: CaseClient.PairOptions) { const { expectedProcessingTime, caseAuthenticatedTags, abort, validateSessionParameters, maxInitialRetransmissions: maxRetransmissions, maxInitialRetransmissionTime: maxRetransmissionTime, initialRetransmissionTime, initialRetransmissionTimeLimit: retransmissionTimeLimit, initialBackoffOffset: backoffOffset, } = options ?? {}; const messenger = new CaseClientMessenger(exchange, expectedProcessingTime); using localAbort = new Abort({ abort }); try { return await this.#doPair( messenger, exchange, fabric, peerNodeId, localAbort, caseAuthenticatedTags, { maxRetransmissions, maxRetransmissionTime, initialRetransmissionTime, retransmissionTimeLimit, backoffOffset, }, validateSessionParameters, ); } catch (error) { // Skip when a sent message is still unacked: the peer never acknowledged our prior message, so the send // would only fail with a flow error. if ( !localAbort.aborted && !exchange.hasUnackedMessage && !causedBy(error, NetworkError, TransientPeerCommunicationError, RetransmissionLimitReachedError) ) { try { await messenger.sendError(SecureChannelStatusCode.InvalidParam); } catch (e) { // The CASE failure this reports is what the caller needs; a failure to report it // must not take its place MatterError.accept(e); logger.debug("Failed to send InvalidParam on CASE error:", Diagnostic.errorMessage(e)); } } throw error; } finally { await messenger.close(); } } async #doPair( messenger: CaseClientMessenger, exchange: MessageExchange, fabric: Fabric, peerNodeId: NodeId, abort: Abort, caseAuthenticatedTags?: readonly CaseAuthenticatedTag[], initialSendOptions?: ExchangeSendOptions, validateSessionParameters?: CaseClient.ValidateSessionParameters, ) { const { crypto } = fabric; // Generate pairing info const initiatorRandom = crypto.randomBytes(32); const initiatorSessionId = await abort.attempt(this.#sessions.getNextAvailableSessionId()); // Initiator Session Id const { operationalIdentityProtectionKey, operationalCert: localNoc, intermediateCACert: localIcac } = fabric; const localKey = await abort.attempt(crypto.createKeyPair()); // Send sigma1 let sigma1Bytes; let resumed = false; let resumptionRecord = this.#sessions.findResumptionRecordByAddress(fabric.addressOf(peerNodeId)); if (resumptionRecord !== undefined) { const { sharedSecret, resumptionId } = resumptionRecord; const resumeKey = await abort.attempt( crypto.createHkdfKey(sharedSecret, Bytes.concat(initiatorRandom, resumptionId), KDFSR1_KEY_INFO), ); const initiatorResumeMic = crypto.encrypt(resumeKey, new Uint8Array(0), RESUME1_MIC_NONCE); sigma1Bytes = await abort.attempt( messenger.sendSigma1( { initiatorSessionId, destinationId: await abort.attempt(fabric.currentDestinationIdFor(peerNodeId, initiatorRandom)), initiatorEcdhPublicKey: localKey.publicBits, initiatorRandom, resumptionId, initiatorResumeMic, initiatorSessionParams: this.#sessions.sessionParameters, }, initialSendOptions, ), ); } else { sigma1Bytes = await abort.attempt( messenger.sendSigma1( { initiatorSessionId, destinationId: await abort.attempt(fabric.currentDestinationIdFor(peerNodeId, initiatorRandom)), initiatorEcdhPublicKey: localKey.publicBits, initiatorRandom, initiatorSessionParams: this.#sessions.sessionParameters, }, { abort, ...initialSendOptions, }, ), ); } let secureSession: NodeSession; const { sigma2Bytes, sigma2, sigma2Resume } = await messenger.readSigma2(abort); if (sigma2Resume !== undefined) { // Process sigma2 resume if (resumptionRecord === undefined) { throw new UnexpectedDataError("Received an unexpected sigma2Resume."); } const { sharedSecret, fabric, sessionParameters: resumptionSessionParams, caseAuthenticatedTags, } = resumptionRecord; const { responderSessionId: peerSessionId, resumptionId, resumeMic, responderSessionParams } = sigma2Resume; // Sigma2Resume's freshly-sent parameters are more current than the resumption record, so they take // precedence. Normalize via the factory so validation sees the same decoded/spec-gated parameters the // session adopts. const sessionParameters = SessionParameters({ ...exchange.session.parameters, ...(resumptionSessionParams ?? {}), ...(responderSessionParams ?? {}), }); validateSessionParameters?.(sessionParameters); const resumeSalt = Bytes.concat(initiatorRandom, resumptionId); const resumeKey = await abort.attempt(crypto.createHkdfKey(sharedSecret, resumeSalt, KDFSR2_KEY_INFO)); crypto.decrypt(resumeKey, resumeMic, RESUME2_MIC_NONCE); const secureSessionSalt = Bytes.concat(initiatorRandom, resumptionRecord.resumptionId); secureSession = await abort.attempt( this.#sessions.createSecureSession({ channel: exchange.channel.transportChannel, id: initiatorSessionId, fabric, peerNodeId, peerSessionId, sharedSecret, salt: secureSessionSalt, isInitiator: true, isResumption: true, peerSessionParameters: sessionParameters, reportedSessionParameters: responderSessionParams, caseAuthenticatedTags, delayManagerRegistration: true, }), ); NodeSession.logNew(logger, "Resumed", secureSession, messenger, fabric, peerNodeId); resumptionRecord.resumptionId = resumptionId; /* update resumptionId */ resumptionRecord.sessionParameters = secureSession.parameters; /* update mrpParams */ resumed = true; const successPromise = messenger.sendSuccess(); this.#sessions.sessions.add(secureSession); // Triggers interactions to the node try { await successPromise; } catch (error) { MatterError.accept(error); logger.info( messenger.exchange.via, "Error sending Sigma2Resume-Success, assume session still valid:", error, ); } } else { // Process sigma2 const { responderEcdhPublicKey: peerKey, encrypted: peerEncrypted, responderRandom, responderSessionId: peerSessionId, responderSessionParams, } = sigma2; // Update the session timing parameters with the just received ones to optimize the session establishment if (responderSessionParams !== undefined) { exchange.session.timingParameters = responderSessionParams; } // We use the Fallbacks for the session parameters overridden by what was sent by the device in Sigma2. // Normalize via the factory so validation sees the same decoded/spec-gated parameters the session adopts. const peerSessionParameters = SessionParameters({ ...exchange.session.parameters, ...(responderSessionParams ?? {}), }); validateSessionParameters?.(peerSessionParameters); const sharedSecret = await abort.attempt(crypto.generateDhSecret(localKey, PublicKey(peerKey))); const sigma2Salt = Bytes.concat( operationalIdentityProtectionKey, responderRandom, peerKey, await abort.attempt(crypto.computeHash(sigma1Bytes)), ); const sigma2Key = await abort.attempt(crypto.createHkdfKey(sharedSecret, sigma2Salt, KDFSR2_INFO)); const peerEncryptedData = crypto.decrypt(sigma2Key, peerEncrypted, TBE_DATA2_NONCE); const { responderNoc: peerNoc, responderIcac: peerIcac, signature: peerSignature, resumptionId: peerResumptionId, } = TlvEncryptedDataSigma2.decode(peerEncryptedData); const peerSignatureData = TlvSignedData.encode({ responderNoc: peerNoc, responderIcac: peerIcac, responderPublicKey: peerKey, initiatorPublicKey: localKey.publicBits, }); const { ellipticCurvePublicKey: peerPublicKey, subject: { fabricId: peerFabricIdNOCert, nodeId: peerNodeIdNOCert }, } = Noc.fromTlv(peerNoc).cert; await abort.attempt( crypto.verifyEcdsa(PublicKey(peerPublicKey), peerSignatureData, new EcdsaSignature(peerSignature)), ); if (peerNodeIdNOCert !== peerNodeId) { throw new UnexpectedDataError( `The node ID in the peer certificate ${peerNodeIdNOCert} doesn't match the expected peer node ID ${peerNodeId}`, ); } if (peerFabricIdNOCert !== fabric.fabricId) { throw new UnexpectedDataError( `The fabric ID in the peer certificate ${peerFabricIdNOCert} doesn't match the expected fabric ID ${fabric.fabricId}`, ); } if (peerIcac !== undefined) { const { subject: { fabricId: peerFabricIdIcaCert }, } = Icac.fromTlv(peerIcac).cert; if (peerFabricIdIcaCert !== undefined && peerFabricIdIcaCert !== fabric.fabricId) { throw new UnexpectedDataError( `The fabric ID in the peer intermediate CA certificate ${peerFabricIdIcaCert} doesn't match the expected fabric ID ${fabric.fabricId}`, ); } } await abort.attempt(fabric.verifyCredentials(peerNoc, peerIcac)); // Generate and send sigma3 const sigma3Salt = Bytes.concat( operationalIdentityProtectionKey, await abort.attempt(crypto.computeHash([sigma1Bytes, sigma2Bytes])), ); const sigma3Key = await abort.attempt(crypto.createHkdfKey(sharedSecret, sigma3Salt, KDFSR3_INFO)); const signatureData = TlvSignedData.encode({ responderNoc: localNoc, responderIcac: localIcac, responderPublicKey: localKey.publicBits, initiatorPublicKey: peerKey, }); const signature = await abort.attempt(fabric.sign(signatureData)); const encryptedData = TlvEncryptedDataSigma3.encode({ responderNoc: localNoc, responderIcac: localIcac, signature: signature.bytes, }); const encrypted = crypto.encrypt(sigma3Key, encryptedData, TBE_DATA3_NONCE); const sigma3Bytes = await messenger.sendSigma3({ encrypted }, { abort }); await abort.attempt(messenger.waitForSuccess({ description: "Sigma3-Success" })); // Create a secure session. Configured CATs take precedence over resumption record ones const sessionCaseAuthenticatedTags = caseAuthenticatedTags ?? resumptionRecord?.caseAuthenticatedTags; const secureSessionSalt = Bytes.concat( operationalIdentityProtectionKey, await abort.attempt(crypto.computeHash([sigma1Bytes, sigma2Bytes, sigma3Bytes])), ); secureSession = await abort.attempt( this.#sessions.createSecureSession({ channel: exchange.channel.transportChannel, id: initiatorSessionId, fabric, peerNodeId, peerSessionId, sharedSecret, salt: secureSessionSalt, isInitiator: true, isResumption: false, peerSessionParameters, reportedSessionParameters: responderSessionParams, caseAuthenticatedTags: sessionCaseAuthenticatedTags, delayManagerRegistration: true, }), ); NodeSession.logNew(logger, "New", secureSession, messenger, fabric, peerNodeId); resumptionRecord = { fabric, peerNodeId, sharedSecret, resumptionId: peerResumptionId, sessionParameters: secureSession.parameters, caseAuthenticatedTags: sessionCaseAuthenticatedTags, }; this.#sessions.sessions.add(secureSession); } // Not abortable; errors must not propagate — session is already adopted at this point. try { await messenger.close(); } catch (e) { logger.error(messenger.via, "Unhandled error closing CASE messenger:", e); } try { await this.#sessions.saveResumptionRecord(resumptionRecord); } catch (e) { logger.warn(messenger.via, "Failed to save resumption record; session is usable but cannot be resumed:", e); } return { session: secureSession, resumed }; } } export namespace CaseClient { /** * Validates the peer's negotiated session parameters before the session is adopted. Invoked for both fresh and * resumed handshakes. Throwing aborts establishment; {@link CaseClient.pair} reports the failure to the peer as * InvalidParam. */ export type ValidateSessionParameters = (peerSessionParameters: SessionParameters) => void; export interface PairOptions { expectedProcessingTime?: Duration; caseAuthenticatedTags?: readonly CaseAuthenticatedTag[]; abort?: AbortSignal; maxInitialRetransmissions?: number; maxInitialRetransmissionTime?: Duration; initialRetransmissionTime?: Duration; /** {@link ExchangeSendOptions.retransmissionTimeLimit} for Sigma1. */ initialRetransmissionTimeLimit?: Duration; /** {@link ExchangeSendOptions.backoffOffset} for Sigma1. */ initialBackoffOffset?: number; validateSessionParameters?: ValidateSessionParameters; } }