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

Module	Description
params	Parameter sets and the Params trait
kem	Top-level ML-KEM algorithms (Algorithms 16-21)
kpke	K-PKE component scheme (Algorithms 13-15)
ntt	Number-Theoretic Transform and polynomial arithmetic
encode	Encoding, decoding, compression, decompression
sample	Polynomial sampling (NTT domain and CBD)
sha3	SHA-3 / SHAKE primitives (FIPS 202)
rng	Cryptographic RNG trait and OS-backed implementation
masked	First-order arithmetic masking for polynomials
shuffle	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

encode

Byte encoding/decoding and compression/decompression (Algorithms 3-6).

kem

ML-KEM key encapsulation: keygen, encaps, decaps (Algorithms 16-21).

kpke

K-PKE component scheme: key generation, encryption, decryption (Algorithms 13-15).

masked

First-order arithmetic masking for DPA/template attack protection. First-order arithmetic masking for ML-KEM polynomials (countermeasure: DPA / DEMA / CPA on the K-PKE secret s).

ntt

Number-Theoretic Transform and modular polynomial arithmetic.

params

ML-KEM parameter sets and the Params trait.

rng

Cryptographic random number generation trait and OS-backed implementation.

sample

Polynomial sampling algorithms: sample::sample_ntt and sample::sample_poly_cbd.

sha3

SHA-3 and SHAKE hash function primitives (FIPS 202). SHA-3 / SHAKE high-level wrappers used by ML-KEM (FIPS 203).

shuffle

Fisher-Yates shuffle for NTT butterfly index randomization (SPA protection). Fisher-Yates shuffle for NTT butterfly index randomization (countermeasure: SPA / SEMA on secret-polynomial NTT).

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.