/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Bytes, Crypto, CRYPTO_AEAD_MIC_LENGTH_BYTES, CRYPTO_PRIVACY_NONCE_LENGTH_BYTES, CRYPTO_SYMMETRIC_KEY_LENGTH, CryptoInputError, MaybePromise, } from "@matter/general"; /** * HKDF info string for deriving a privacy key from an encryption key. * @see {@link MatterSpecification.v161.Core} § 4.9.1 */ const PRIVACY_KEY_INFO = Bytes.fromString("PrivacyKey"); const NONCE_SESSION_ID_LENGTH = 2; const NONCE_MIC_LENGTH = CRYPTO_PRIVACY_NONCE_LENGTH_BYTES - NONCE_SESSION_ID_LENGTH; const NONCE_MIC_OFFSET = CRYPTO_AEAD_MIC_LENGTH_BYTES - NONCE_MIC_LENGTH; /** * Matter message privacy: obfuscation of the packet header for privacy-enhanced messages. * @see {@link MatterSpecification.v161.Core} § 4.9 */ export namespace MessagePrivacy { /** Derive a privacy key from an encryption key: HKDF(key, salt=[], info="PrivacyKey", 16). */ export function deriveKey(crypto: Crypto, encryptionKey: Bytes): MaybePromise { return crypto.createHkdfKey(encryptionKey, new Uint8Array(0), PRIVACY_KEY_INFO, CRYPTO_SYMMETRIC_KEY_LENGTH); } /** Build the 13-byte privacy nonce: sessionId (2 bytes, big-endian) then the last 11 bytes of the message MIC. */ export function buildNonce(sessionId: number, mic: Bytes): Bytes { const micBytes = Bytes.of(mic); if (micBytes.length !== CRYPTO_AEAD_MIC_LENGTH_BYTES) { throw new CryptoInputError(`Privacy nonce requires a ${CRYPTO_AEAD_MIC_LENGTH_BYTES}-byte MIC`); } return Bytes.concat( Uint8Array.of((sessionId >> 8) & 0xff, sessionId & 0xff), micBytes.slice(NONCE_MIC_OFFSET, NONCE_MIC_OFFSET + NONCE_MIC_LENGTH), ); } /** * Obfuscate or deobfuscate a header region using AES-CTR (as AES-CCM with empty AAD, ciphertext-only). * CTR keystream XOR is symmetric, so the same call serves both directions. */ export function obfuscate(crypto: Crypto, privacyKey: Bytes, data: Bytes, nonce: Bytes): Bytes { const dataBytes = Bytes.of(data); return Bytes.of(crypto.encrypt(privacyKey, dataBytes, nonce)).slice(0, dataBytes.length); } }