sealed_channel/lib.rs
1#![no_std]
2#![forbid(unsafe_code)]
3#![doc = include_str!("../README.md")]
4//!
5//! # Construction
6//!
7//! `sealed-channel` is a transport-agnostic, forward-secret authenticated
8//! record channel. It performs **pure compute only**: it knows nothing about
9//! sockets, WebSockets, JSON, browsers, tokens, or any transport, and it
10//! performs **no RNG and no I/O**. The caller supplies all randomness, the
11//! ephemeral keys, and the Diffie-Hellman shared secret.
12//!
13//! Keys are derived with HKDF-SHA256 from the pre-shared secret (PSK), the
14//! externally-supplied ephemeral DH shared secret, and a transcript hash that
15//! binds the exact bytes of both handshake messages. Records are sealed with
16//! ChaCha20-Poly1305, with the cleartext `magic || seq` header used as the
17//! AEAD additional authenticated data and a per-direction nonce prefix
18//! concatenated with the big-endian sequence number used as the nonce.
19//!
20//! Forward secrecy comes from the **ephemeral** DH shared secret supplied by
21//! the caller: once the ephemeral private keys are discarded, past traffic
22//! cannot be decrypted even if the PSK is later compromised.
23//!
24//! # CRITICAL SECURITY INVARIANT
25//!
26//! Authentication strength equals the entropy of the PSK. An active
27//! man-in-the-middle (e.g. a relay) can perform its own DH with each side and
28//! therefore knows both DH shared secrets; the ONLY thing keeping it out is
29//! the PSK, which it does not know. The PSK MUST be high-entropy (at least 128
30//! bits, 256 recommended). NEVER pass a low-entropy secret such as a PIN or
31//! password as the PSK — authenticating a weak secret against an active MITM
32//! requires a PAKE (e.g. SPAKE2+ / OPAQUE), which this crate is NOT.
33
34extern crate alloc;
35
36pub mod error;
37pub mod record;
38pub mod schedule;
39pub mod transcript;
40
41pub use error::Error;
42pub use record::{RecordOpener, RecordSealer};
43pub use schedule::SessionKeys;
44pub use transcript::transcript_hash;