Struct SessionAead 

pub struct SessionAead(/* private fields */);

A session-scoped AES-128-CCM-128 cipher with the key schedule computed once at construction.

The free functions encrypt, decrypt, and ctr_apply each build a fresh Aes128Ccm cipher — including running AES-128 key expansion — on every call. That is the right trade-off for a one-shot use (a single CASE handshake blob, say), but it repeats the same key-schedule computation on every packet for any path that encrypts/decrypts more than once per key — most notably encrypting every outgoing Matter message and decrypting every inbound one on a live session. SessionAead runs AES-128 key expansion once, at construction, and reuses the expanded schedule (via the ccm/aes crates’ own internal caching) for every subsequent call.

This is purely a performance optimisation: for identical key/nonce/aad/input, every method here produces output byte-identical to the corresponding free function. It composes the same aes + ccm crates the free functions use — no cryptographic primitive is reimplemented here.

Holds the expanded AES-128 key schedule for its lifetime; there is no Debug derive because printing that schedule would leak key material (see the manual Debug impl below).

Secret hygiene: the expanded key schedule is NOT zeroized on drop — the ccm/aes types we compose do not implement ZeroizeOnDrop, and we do not reimplement them. That is acceptable here because a SessionAead is always constructed from key material that is itself already resident unzeroized for the whole session (the session keys it is derived from), so dropping the handle removes no guarantee the caller had. SessionAead is therefore NOT a secret-erasure boundary: a caller that needs key material scrubbed must scrub the source key bytes (see crate::pase::PaseSessionKeys, which is ZeroizeOnDrop) and drop every derived handle, and must not treat this type as providing erasure.

Implementations

impl SessionAead

pub fn new(key: &[u8; 16]) -> Self

Construct a cipher handle with the AES-128 key schedule computed once, from a fixed-length key.

Infallible: unlike Aes128Ccm::new_from_slice (which the free functions used to call directly, and which validates a runtime slice length), a &[u8; AEAD_KEY_LEN] is always a valid key length by construction, so key initialisation cannot fail.

pub fn encrypt( &self, nonce: &[u8; 13], aad: &[u8], plaintext: &[u8], ) -> Result<Vec<u8>>

AES-128-CCM-128 encrypt using the cached key schedule. See encrypt for the exact byte layout (ciphertext || tag) and matter.js compatibility notes.

Errors

Returns Error::EncryptionFailed on encryption failure (not expected in practice for the spec-bounded message sizes).

pub fn decrypt( &self, nonce: &[u8; 13], aad: &[u8], ciphertext: &[u8], ) -> Result<Vec<u8>>

AES-128-CCM-128 decrypt using the cached key schedule. See decrypt for the exact byte layout and error semantics.

Errors

Returns Error::EncryptedBlobDecryptionFailed on any authentication or decryption failure.

pub fn encrypt_in_place( &self, nonce: &[u8; 13], aad: &[u8], buf: &mut Vec<u8>, ) -> Result<()>

In-place seal: encrypts buf in place and appends the 16-byte tag (so buf.len() grows by AEAD_TAG_LEN), using the cached key schedule. Avoids the extra allocation-and-copy encrypt pays for callers that already own a mutable buffer to encrypt into (e.g. a pre-assembled outgoing packet).

Produces the same bytes encrypt(...) would for the same key/nonce/aad/plaintext.

Errors

Returns Error::EncryptionFailed on encryption failure. On error, buf’s contents are unspecified — the underlying ccm/aead crates make no guarantee it is restored to its input state, so callers must not read buf after an error.

pub fn decrypt_in_place( &self, nonce: &[u8; 13], aad: &[u8], buf: &mut Vec<u8>, ) -> Result<()>

In-place open: verifies and strips the 16-byte tag, truncating buf to the plaintext on success, using the cached key schedule. Avoids the extra allocation-and-copy decrypt pays for callers that already own the ciphertext in a mutable buffer (e.g. a received packet being decrypted in place).

Errors

Returns Error::EncryptedBlobDecryptionFailed on any authentication or decryption failure. On error, buf’s contents are unspecified — the underlying ccm/aead crates make no guarantee it is restored to its input state, so callers must not read buf after an error.

pub fn ctr_apply(&self, nonce: &[u8; 13], data: &[u8]) -> Result<Vec<u8>>

CTR keystream application (see ctr_apply) using the cached key schedule.

Errors

Returns Error::EncryptionFailed if the underlying cipher fails (not expected in practice for spec-bounded sizes).

Trait Implementations

impl Debug for SessionAead

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Prints a fixed opaque placeholder — never the expanded key schedule. Ccm<Aes128, U16, U13> does not implement Debug itself, and even if it did, printing key material would be a hygiene bug (see crate::pase::PaseSessionKeys’s redacted Debug for the same discipline applied to raw key bytes).