matter-crypto

Matter protocol session-establishment primitives — PASE (Password Authenticated Session Establishment) via SPAKE2+ and CASE (Certificate Authenticated Session Establishment) via SIGMA-I. Part of the matter-rust workspace.

Scope

PASE — spec §3.10

Sans-IO state machines (PaseProver, PaseVerifier) — drive bytes through method-per-message-type APIs; caller owns the transport.
SPAKE2+ math over P-256 with Matter's M and N constants.
PBKDF2 setup-PIN derivation; HKDF session-key derivation.
Constant-time confirmation tag comparison via subtle.
Byte-for-byte verified against matter.js for three handshake scenarios (negotiation, known-params, max-iterations).

CASE — spec §4.13

Sans-IO CaseInitiator / CaseResponder state machines.
SIGMA-I math: ephemeral P-256 ECDH, mutual ECDSA signatures, AES-CCM-128 encrypted blobs.
NOC chain validation via matter-cert::CertificateChain::validate.
Pluggable signing via the CaseSigner trait — wire your own HSM/TPM/secure-element by implementing one method.
Session resumption: Sigma1 + Sigma2_Resume fast path. The caller drives record lookup via the Sigma1Outcome enum (sans-IO purity).
Byte-for-byte verified against matter.js for the new-session scenario. Resumption byte-parity is deferred — see TODO-1.0.md.

Status

0.2.0. PASE and CASE feature-complete.

Minimal example

use matter_crypto::{PasePbkdfParams, PaseProver, PaseVerifier};

let pin = 20202021_u32;
let params = PasePbkdfParams {
    iterations: 1_000,
    salt: vec![0x42u8; 16],
};

let mut prover = PaseProver::new_with_negotiation(pin)?;
let mut verifier = PaseVerifier::new_from_pin(pin, params)?;

// Drive the 5-message handshake — pseudo-code; caller pipes bytes
// between the two sides over the actual network in production.
let m = prover.start()?;
verifier.handle_pbkdf_request(&m)?;
let m = verifier.next_message()?;
prover.handle_pbkdf_response(&m)?;
let m = prover.next_message()?;
verifier.handle_pake1(&m)?;
let m = verifier.next_message()?;
prover.handle_pake2(&m)?;
let m = prover.next_message()?;
verifier.handle_pake3(&m)?;

let prover_keys = prover.finish()?;
let verifier_keys = verifier.finish()?;
assert_eq!(prover_keys.ke, verifier_keys.ke);

Minimal example — CASE

use matter_crypto::{
    CaseCredentials, CaseInitiator, CaseResponder, RingSigner, Sigma1Outcome,
};
use matter_cert::TrustedRoots;

// --- Build credentials (caller supplies these) ---
// `noc` and `icac` are MatterCertificate values from matter-cert.
// `signer` holds the NOC private key.
let (signer, _pkcs8) = RingSigner::generate()?;
let rcac_pub: [u8; 65] = *signer.public_key().as_bytes(); // example; real app uses RCAC pub key
let initiator_creds = CaseCredentials {
    noc: my_noc,
    icac: None,
    signer: Box::new(signer),
    fabric_id: 0x1234_5678_9ABC_DEF0,
    node_id: 0xAAAA_BBBB_CCCC_DDDD,
    ipk: my_ipk,
    rcac_public_key: rcac_pub,
};

// --- Drive the 3-message Sigma1/2/3 handshake ---
// (caller pipes bytes across the network in a real deployment)
let mut initiator = CaseInitiator::new(
    initiator_creds, trusted_roots, responder_node_id, fabric_id, initiator_session_id,
)?;
let mut responder = CaseResponder::new(responder_creds, trusted_roots, responder_session_id)?;

let sigma1 = initiator.start()?;
let outcome = responder.handle_sigma1(&sigma1)?;
assert!(matches!(outcome, Sigma1Outcome::NewSession));

let sigma2 = responder.next_message()?;
initiator.handle_sigma2(&sigma2)?;

let sigma3 = initiator.next_message()?;
responder.handle_sigma3(&sigma3)?;

let init_out = initiator.finish()?;
let resp_out = responder.finish()?;
// Both sides derive the same session keys.
assert_eq!(init_out.keys.i2r_key, resp_out.keys.i2r_key);

Cryptographic primitives

This crate never implements crypto primitives. Underlying math:

ring — SHA-256, HMAC, HKDF, PBKDF2, ECDSA-verify.
p256 — P-256 scalar/point arithmetic for SPAKE2+ (ring deliberately doesn't expose these).
subtle — constant-time comparison for PASE confirmation tags.
aes + ccm — AES-CCM-128 for CASE encrypted blobs (ring 0.17 does not expose AES-CCM).

Cross-verification

PASE messages produced by our PaseProver and PaseVerifier are byte-identical to matter.js's output for the same inputs. CI runs this verification on every PR against three captured handshake scenarios.

CASE new-session messages (Sigma1/2/3) are byte-identical to matter.js's output for the same inputs. Resumption byte-parity is deferred — known divergences are documented in TODO-1.0.md.

License

Apache 2.0. See LICENSE.

matter-crypto 0.3.0