Module channel 

SecureChannel envelope — the end-to-end crypto seam that wraps the opaque wire blob marshal produces, between the codec and the transport.

Layering (work/QUANTUM_MAP.md §1, §L): the channel owns its own versioned envelope and never inspects or mutates the payload, exactly as the FEC layer in super::fec does. seal frames an opaque blob under a suite id; open reverses it, returning None on any malformed input — the same None-on-malformed contract super::marshal::message_from_wire honours, so a corrupt or truncated envelope is dropped, never decoded.

[ CHAN_MAGIC | CHAN_VER | suite_id (LE u16) | body ]

The null suite (SUITE_NULL) is identity framing — no cryptography — and exists to prove the embedding seam end-to-end before any primitive lands. Real suites replace body with handshake/sequence ‖ AEAD(blob)+tag under their own suite id; because the suite id is bound in the envelope, swapping a suite is a registry change, never a wire break.

Structs

NullSuite

The identity suite: no cryptography, body == blob. Proves the seam; never the shipped default once a real suite exists.

PqHandshake

The freshly generated handshake material an initiator publishes + retains.

PqSuite

The post-quantum suite: a per-session ChaCha20-Poly1305 key (from an ML-KEM-768 handshake, see pq_handshake_initiator / pq_handshake_responder). Each seal_body draws a fresh counter nonce, so every frame is unique; the nonce is carried in the body, so the peer opens statelessly. The suite id is bound as the AEAD associated data, so a frame can’t be replayed under a different suite. (Bidirectional use derives a key per direction — see the handshake.)

Constants

SUITE_NULL

The suite id of the identity suite.

SUITE_PNP

The suite id of the PNP tier — the information-theoretic true one-time pad (see super::pnp). It is the last resort should computational cryptography fall (the P = NP scenario): its secrecy rests on Shannon, not on any hardness assumption. Like SUITE_PQ it is keyed and stateful, so it lives outside the stateless suite_for registry and is used through super::pnp::PnpSuite rather than seal / open.

SUITE_PQ

The suite id of the post-quantum suite: an ML-KEM-768 handshake establishes the shared secret, SHAKE256 derives the key, and every body is ChaCha20-Poly1305 AEAD-sealed.

Traits

ActiveSession

A keyed, stateful crypto session installed for the live send/receive path. Unlike the stateless Suite registry, a session carries per-direction key/pad material and may fail closed on seal — a one-time pad can run out. Both the keyed PqSuite and the super::pnp one-time pad plug in here, so seal_active_checked / open_active stay suite-agnostic.

Suite

A pluggable crypto suite. Each posture level — null, Classic, Hybrid, PQ, PQ-Max — is one Suite registered in suite_for, so adding a primitive is a registration, not a change to seal / open. The seam stays suite-agnostic; all cryptography lives behind this trait (work/QUANTUM_MAP.md §3 — crypto-agility).

Functions

active_session

The keyed session active for seal/open on this thread, if any.

active_suite

The suite active for seal/open on this thread, if any.

derive_aead_key

Derive a directional 32-byte AEAD key from an ML-KEM shared secret via SHAKE256, domain-separated by label (e.g. b"i2r" / b"r2i") so each direction has an independent key — no nonce reuse across the two streams that share the handshake secret.

install_session

Install session as the active keyed session on this thread, returning the prior one. The live seal_active_checked / open_active path then routes through it until it is replaced/cleared.

open

Reverse seal, returning the inner blob. None on a too-short header, a bad magic/version, an unknown suite id, or a body the suite rejects — never a panic, never a partial decode (mirrors super::marshal::message_from_wire).

open_active

Open an inbound frame under the active keyed session if installed, else the active suite; None on a tampered/foreign frame (the caller drops it). With neither engaged, pass bytes through so the wire stays byte-identical for non-secure programs.

open_with

Reverse seal_with under a keyed Suite instance, or None on a bad header, a suite-id mismatch, or a body the suite rejects (a tampered AEAD tag).

pq_handshake_finish

Initiator step 2: decapsulate the responder’s ciphertext, yielding the matching directional suites (initiator→responder, responder→initiator).

pq_handshake_initiator

Initiator step 1: generate an ML-KEM-768 keypair. Publish PqHandshake::ek to the responder.

pq_handshake_responder

Responder: encapsulate to the initiator’s ek, returning the ciphertext to send back and the two directional suites (initiator→responder, responder→initiator).

seal

Frame an opaque blob under suite_id, dispatching the body through the registered Suite. Panics only if sealed with an unregistered suite — a programmer error, since callers select from the registry.

seal_active

Seal bytes under the active suite; with no active suite, return them unchanged so the wire stays byte-identical for non-secure programs. (Stateless path only — the keyed, possibly fail-closing session path is seal_active_checked.)

seal_active_checked

Seal bytes for the live send path: through the active keyed ActiveSession if installed (which may fail closed, returning None — e.g. a one-time pad is exhausted), else through the active stateless suite, else pass-through. A None result is the fail-closed signal the caller MUST surface as a send error — never transmit the plaintext instead.

seal_with

Frame a blob under a keyed Suite instance (the PqSuite path), binding the suite id in the header exactly like seal. The instance carries the per-session key the static registry can’t.

suite_for

Resolve a registered STATELESS suite by its wire id, or None for an unknown suite (so open returns None rather than decoding under the wrong primitive). The keyed PqSuite is not here — it carries a per-session key and is used via seal_with / open_with.

with_session

Run f with session active for seal/open on this thread, restoring the prior session after (mirrors with_suite).

with_suite

Run f with suite active for seal/open on this thread, restoring the prior suite after (mirrors marshal’s scoped wire-knob setters).