Expand description
FIPS 203 ML-KEM type-state API (v0.0.7 — see issue #130). FIPS 203 ML-KEM type-state API.
New surface introduced in v0.0.7 (#130). Parameter set is a type,
not a Cargo feature: each consumer picks MlKem512, MlKem768,
or MlKem1024 at the call site. Secrets and public material
travel as distinct types with the right Drop / Zeroize semantics:
KemCore — trait, sealed
├── MlKem512 ✅ implemented
├── MlKem768 ✅ implemented (default)
└── MlKem1024 ✅ implemented
EncapsulationKey<P> — `Copy`-safe public bytes
DecapsulationKey<P> — `!Copy`, `ZeroizeOnDrop`, redacted `Debug`
Ciphertext<P> — opaque, fixed-size byte wrapper
SharedSecret — 32-byte `ZeroizeOnDrop` secretAs of Phase 3e of #130b (commit 7… — search git log --grep "Phase 3e"), all three parameter sets implement KemCore
unconditionally. The default build supports MlKem512,
MlKem768, and MlKem1024 concurrently — pick the right one
at the call site:
use kyberlib::{KemCore, MlKem512, MlKem768, MlKem1024};
let mut rng = rand::thread_rng();
let (dk_512, ek_512) = MlKem512::generate(&mut rng)?;
let (dk_768, ek_768) = MlKem768::generate(&mut rng)?;
let (dk_1024, ek_1024) = MlKem1024::generate(&mut rng)?;§Migration from the v0.0.6 surface
The free functions keypair,
encapsulate, decapsulate
and the Keypair struct from the old surface are
retained as #[deprecated] shims for MlKem768 only. They’ll be
removed in a future release.
§ACVP conformance
MlKem768 is byte-validated against 60/60 NIST ACVP test vectors
(see tests/test_acvp.rs). MlKem512 and MlKem1024
conformance is verified structurally — the generic algorithm
pipeline is byte-identical to the cfg-gated reference under each
parameter set’s feature (#130b commits a77b94b through 3819f7a).
The ACVP harness is wired to all three under #130c.
Structs§
- MlKem512
- ML-KEM-512 parameter set marker. NIST security category 1 (≈ AES-128).
- MlKem768
- ML-KEM-768 parameter set marker. NIST security category 3 (≈ AES-192). Default for CNSA 2.0 hybrid TLS deployments.
- MlKem512
Ciphertext - Ciphertext.
- MlKem512
Decap Key - Secret decapsulation key. Zeroized on drop.
- MlKem512
Encap Key - Public encapsulation key.
- MlKem768
Ciphertext - ML-KEM-768 ciphertext. 1088 bytes.
- MlKem768
Decap Key - ML-KEM-768 decapsulation key (private). 2400 bytes. Zeroized on drop.
- MlKem768
Encap Key - ML-KEM-768 encapsulation key (public). 1184 bytes.
- MlKem1024
- ML-KEM-1024 parameter set marker. NIST security category 5 (≈ AES-256). Required by CNSA 2.0 for NSS by 1 Jan 2027.
- MlKem1024
Ciphertext - Ciphertext.
- MlKem1024
Decap Key - Secret decapsulation key. Zeroized on drop.
- MlKem1024
Encap Key - Public encapsulation key.
- Shared
Secret - 32-byte shared secret. Zeroized on drop.
Traits§
- KemCore
- FIPS 203 ML-KEM parameter-set marker trait.