Source: sigil/node/sigil-czac/src/session.rs. SHA-256: 09f9716637b09055431b19d296c252c0d554087d9e7ff92d4c32cbcc4666b9dd.

This reference follows declared source modules, retains conditional attributes, and includes public declarations and implementation methods. Private-module re-exports and trait resolution require the compiler; this is a source reference, not a claim that every listed item is a root import. Function bodies and constant values are omitted.

session::DEFAULT_REKEY_AFTER

Default number of messages before rekeying is required.

2^20 ≈ 1M messages. ChaCha20-Poly1305 with a 96-bit nonce allows up to 2^32 unique nonces per key before the birthday bound becomes significant; we rekey at 2^20 to provide a conservative safety margin and ensure forward secrecy through frequent key rotation.

pub const DEFAULT_REKEY_AFTER: u64;

Source line: 39.

session::SessionKeys

Session keys derived after a successful channel handshake.

The initiator and responder derive different key pairs from the same shared secret to prevent key reuse in both directions.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SessionKeys {
/// Local encryption key (ChaCha20-Poly1305, 32 bytes).

pub local_key: [u8; 32],
/// Remote encryption key for decrypting incoming messages.

pub remote_key: [u8; 32],
/// Nonce counter for outgoing messages.

pub local_nonce_counter: u64,
/// Nonce counter for incoming messages (next expected value).

pub remote_nonce_counter: u64,
/// Number of messages before rekeying (default: 2^20).

pub rekey_after: u64,
/// Unix timestamp when these keys were derived.

pub created_at: u64
}

Source line: 46.

session::SessionKeys::derive

Derive session keys from a shared secret.

Both sides call this with the same shared_secret but opposite initiator values, ensuring they agree on which key is local vs. remote. Key derivation uses BLAKE3 KDF with distinct context strings so the two keys are cryptographically independent.

Arguments

• shared_secret - 32-byte shared secret from the handshake.
• initiator - true if this side initiated the channel.

Returns

A [SessionKeys] ready to encrypt/decrypt with nonce counters at zero.

pub fn derive(shared_secret: &[u8; 32], initiator: bool) -> Self;

Source line: 77.

session::SessionKeys::needs_rekey

Check whether the session keys need rekeying.

pub fn needs_rekey(&self) -> bool;

Source line: 103.

session::SessionKeys::next_nonce

Construct the next nonce from the local counter and increment it.

pub fn next_nonce(&mut self) -> [u8; 12];

Source line: 109.

session::SessionKeys::encrypt

Encrypt plaintext with the local ChaCha20-Poly1305 key.

Output format: [nonce (12 bytes)] [ciphertext + tag (plaintext.len() + 16 bytes)]

The aad bytes (e.g. the serialized message header) are authenticated but not included in the output; the caller must transmit them alongside the ciphertext and supply identical bytes to decrypt.

Errors

Returns [CzacError::RekeyRequired] if the nonce counter has reached rekey_after. Returns [CzacError::SessionCryptoError] on cipher failure.

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

Source line: 127.

session::SessionKeys::decrypt

Decrypt ciphertext with the remote ChaCha20-Poly1305 key.

Expects input format: [nonce (12 bytes)] [ciphertext + tag]

The aad must be identical to the bytes passed to encrypt on the sending side. Any mismatch, ciphertext tampering, or tag failure causes an immediate hard error — no plaintext is returned on failure.

Nonce ordering is enforced: a message with a nonce counter less than the current remote_nonce_counter is rejected as a replay.

Errors

Returns [CzacError::SessionCryptoError] if:

• The input is too short (< 12 + 16 bytes)
• Nonce replay is detected
• AAD mismatch or ciphertext tampering (authentication tag fails)

pub fn decrypt(&mut self, data: &[u8], aad: &[u8]) -> Result<Vec<u8>, CzacError>;

Source line: 174.