1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
//! CGv2 authenticated envelope protocol (`src/protocol/`).
//!
//! # Responsibility scope
//! This module defines the on-wire format used by crypt_guard v2.0 for all
//! hybrid KEM + symmetric encryption operations. It owns:
//!
//! - [`header`] — the 14-byte fixed header (`magic`, `version`, algorithm IDs, flags)
//! - [`version`] — the protocol magic constant `b"CGv2"` and `VERSION_V2 = 2`
//! - [`aad`] — deterministic AAD construction from header + KEM ciphertext + nonce
//! - [`envelope`] — the full [`Envelope`] struct and its length-prefixed serialization
//!
//! # Key types exported
//! - [`Envelope`] — the authenticated wire container
//! - [`header::Header`] — parsed header fields
//! - [`header::KemAlgId`](crate::protocol::header::KemAlgId), [`header::AeadAlgId`](crate::protocol::header::AeadAlgId), [`header::KdfAlgId`](crate::protocol::header::KdfAlgId) — algorithm IDs
//! - [`aad::build_aad`] — AAD builder
//! - [`version::MAGIC`], [`version::VERSION_V2`] — constants
//!
//! # Nonce policy
//! The nonce is stored *inside* the [`Envelope`] on the encrypt path and recovered
//! from it on the decrypt path. **The nonce must never be printed to stdout or
//! logged at `info` level.** Use `tracing::trace!` if you must log it during debugging,
//! and ensure that trace logging is disabled in production builds.
//!
//! # Concurrency
//! Protocol types have no shared mutable state and are `Send + Sync` where their
//! fields permit it. [`signed_envelope::SignedEnvelope`] intentionally does not
//! require `Clone`; clone guarantees apply only to types that explicitly provide them.
//!
//! # Errors
//! Parse errors map to [`crate::error::CryptError::InvalidEnvelope`] or
//! [`crate::error::CryptError::UnsupportedEnvelopeVersion`].
//!
//! # Examples
//! ```rust,no_run
//! use crypt_guard::protocol::{
//! header::{Header, KemAlgId, AeadAlgId, KdfAlgId},
//! envelope::Envelope,
//! };
//! let hdr = Header::new(KemAlgId::MlKem768, AeadAlgId::XChaCha20Poly1305, KdfAlgId::HkdfSha256);
//! let env = Envelope::new(hdr, vec![0u8; 32], vec![0u8; 24], vec![0u8; 64]);
//! let serialized = env.to_bytes();
//! let parsed = Envelope::from_bytes(&serialized).unwrap();
//! assert_eq!(env, parsed);
//! ```
pub use ;
pub use Envelope;
pub use ;
pub use ;