Module ml_kem 

ML-KEM — Module-Lattice-Based Key-Encapsulation Mechanism

A pure-Rust implementation of FIPS 203 (ML-KEM) providing three parameter sets: MlKem512, MlKem768, and MlKem1024.

Uses only the Rust standard library. No external dependencies.

Quick start

use quantica::ml_kem::*;

let mut rng = OsRng;

// Key generation
let (ek, dk) = MlKem::<MlKem768>::keygen(&mut rng).unwrap();

// Encapsulation (sender)
let (shared_secret_s, ciphertext) = MlKem::<MlKem768>::encaps(&ek, &mut rng).unwrap();

// Decapsulation (receiver)
let shared_secret_r = MlKem::<MlKem768>::decaps(&dk, &ciphertext, &mut rng).unwrap();

assert_eq!(shared_secret_s, shared_secret_r);

Side-channel countermeasures

This implementation includes multiple layers of protection against physical side-channel attacks:

• Constant-time: no secret-dependent branches or memory accesses
• Zeroization: all secret intermediates erased via volatile writes
• First-order masking: secret polynomials split into additive shares (DPA/template)
• Double decaps: fault detection on FO comparison (DFA)
• dk integrity: H(ek) verification at decaps time (DFA)
• NTT shuffling: randomized butterfly order (SPA)

Module overview

Three API tiers (see the crate-level “API tiers” section): the guaranteed facade, the hazmat-gated expert bricks, and crate-internal modules.

Module	Tier	Description
params	facade	Parameter sets and the Params trait
rng	facade	Cryptographic RNG trait and OS-backed implementation
kem	hazmat	Deterministic FIPS 203 internals (CAVP/KAT tooling)
encode	hazmat	Encoding, decoding, compression, decompression
sample	hazmat	Polynomial sampling (NTT domain and CBD)
kpke	internal	Unauthenticated K-PKE component (FO-transform input)
ntt	internal	NTT and polynomial arithmetic (Montgomery domain)
sha3	internal	SHA-3 / SHAKE wrappers (FIPS 202)
masked	internal	First-order arithmetic masking for polynomials
shuffle	internal	Fisher-Yates shuffle for NTT butterfly randomization

Re-exports

pub use params::MlKem512;

pub use params::MlKem768;

pub use params::MlKem1024;

pub use params::Params;

pub use rng::CryptoRng;

pub use rng::OsRng;

Modules

params

ML-KEM parameter sets and the Params trait. ML-KEM parameter sets as defined in FIPS 203 Section 8, Table 2.

rng

Cryptographic random number generation trait and OS-backed implementation.

Structs

Ciphertext

ML-KEM ciphertext wrapping the encapsulated shared secret.

DecapsulationKey

ML-KEM decapsulation key (the private half of a key pair).

EncapsulationKey

ML-KEM encapsulation key (the public half of a key pair).

MlKem

Main ML-KEM interface, generic over a Params parameter set.

Enums

MlKemError

Errors returned by ML-KEM operations.

Type Aliases

SharedSecret

32-byte ML-KEM shared secret.