Skip to main content

Module ml_kem

Module ml_kem 

Source
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` secret

As 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.
MlKem512Ciphertext
Ciphertext.
MlKem512DecapKey
Secret decapsulation key. Zeroized on drop.
MlKem512EncapKey
Public encapsulation key.
MlKem768Ciphertext
ML-KEM-768 ciphertext. 1088 bytes.
MlKem768DecapKey
ML-KEM-768 decapsulation key (private). 2400 bytes. Zeroized on drop.
MlKem768EncapKey
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.
MlKem1024Ciphertext
Ciphertext.
MlKem1024DecapKey
Secret decapsulation key. Zeroized on drop.
MlKem1024EncapKey
Public encapsulation key.
SharedSecret
32-byte shared secret. Zeroized on drop.

Traits§

KemCore
FIPS 203 ML-KEM parameter-set marker trait.