MatterEx.Session (matter_ex v0.4.0)

Represents an established secure session after PASE or CASE completes.

Derives directional encryption keys from the raw session key (Ke) using HKDF-SHA256 per Matter spec section 4.13.2.6.1:

keys = HKDF(salt="", ikm=Ke, info="SessionKeys", length=48)
I2R_Key = keys[0:16]              # Initiator → Responder
R2I_Key = keys[16:32]             # Responder → Initiator
AttestationChallenge = keys[32:48] # Used in CASE

Summary

Types

t()

Functions

derive_session_keys(ke, salt \\ <<>>)

Derive I2R_Key, R2I_Key, and AttestationChallenge from session Ke.

new(opts)

Create a new session with derived directional keys and a fresh message counter.

Types

t()

@type t() :: %MatterEx.Session{
  attestation_challenge: binary(),
  auth_mode: :pase | :case,
  counter: MatterEx.Protocol.Counter.t(),
  decrypt_key: binary(),
  encrypt_key: binary(),
  fabric_index: non_neg_integer() | nil,
  local_node_id: non_neg_integer(),
  local_session_id: non_neg_integer(),
  peer_node_id: non_neg_integer(),
  peer_session_id: non_neg_integer(),
  peer_subjects: [non_neg_integer()]
}

Functions

derive_session_keys(ke, salt \\ <<>>)

@spec derive_session_keys(binary(), binary()) :: {binary(), binary(), binary()}

Derive I2R_Key, R2I_Key, and AttestationChallenge from session Ke.

For PASE sessions, salt is empty. For CASE sessions, salt is IPK(16) || SHA256(sigma1 || sigma2 || sigma3)(32) = 48 bytes.

new(opts)

@spec new(keyword()) :: t()

Create a new session with derived directional keys and a fresh message counter.

Required opts: :local_session_id, :peer_session_id, :encryption_key

Optional opts:

:role — :initiator or :responder (default :responder). Determines which derived key is used for encrypt vs decrypt.
:local_node_id — source node ID for nonce construction (default 0)
:peer_node_id — peer node ID for nonce construction (default 0)