Struct MlKem 

pub struct MlKem<P: Params>(/* private fields */);

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

This is the primary API for ML-KEM key encapsulation. It wraps the lower-level functions in kem and provides a convenient, type-safe interface parameterized by security level.

Type parameters

• P - One of MlKem512, MlKem768, or MlKem1024, selecting the security category (1, 3, or 5 respectively).

Example

use quantica::ml_kem::*;

let mut rng = OsRng;
let (ek, dk) = MlKem::<MlKem768>::keygen(&mut rng).unwrap();
let (ss, ct) = MlKem::<MlKem768>::encaps(&ek, &mut rng).unwrap();
let ss2 = MlKem::<MlKem768>::decaps(&dk, &ct, &mut rng).unwrap();
assert_eq!(ss, ss2);

Implementations

impl<P: Params> MlKem<P>

pub fn keygen( rng: &mut impl CryptoRng, ) -> Result<(EncapsulationKey<P>, DecapsulationKey<P>), MlKemError>

Generate an ML-KEM key pair.

Produces an encapsulation key (public) and a decapsulation key (private) using randomness from the provided RNG. Implements Algorithm 19 of FIPS 203.

The decapsulation key includes an integrity hash H(ek) that is verified during decapsulation to detect storage corruption (DFA protection).

Arguments

• rng - A cryptographic random number generator implementing CryptoRng.

Returns

A tuple (encapsulation_key, decapsulation_key) of typed wrappers. The decapsulation key auto-zeroizes on Drop.

Errors

Returns MlKemError::RngFailure if the RNG fails to produce bytes.

Example

use quantica::ml_kem::*;
let mut rng = OsRng;
let (ek, dk) = MlKem::<MlKem768>::keygen(&mut rng).unwrap();
assert_eq!(ek.len(), MlKem768::EK_LEN);
assert_eq!(dk.len(), MlKem768::DK_LEN);

pub fn encaps( ek: &EncapsulationKey<P>, rng: &mut impl CryptoRng, ) -> Result<(SharedSecret, Ciphertext<P>), MlKemError>

Encapsulate a shared secret against an encapsulation key.

Given a public encapsulation key, generates a fresh 32-byte shared secret and the corresponding ciphertext. Implements Algorithm 20 of FIPS 203 with input validation (length and modulus checks).

Arguments

• ek - The encapsulation (public) key, exactly Params::EK_LEN bytes.
• rng - A cryptographic random number generator implementing CryptoRng.

Returns

A tuple (shared_secret, ciphertext) where the shared secret is 32 bytes.

Errors

• MlKemError::InvalidEncapsulationKey if ek has wrong length or fails the modulus check.
• MlKemError::RngFailure if the RNG fails.

Example

use quantica::ml_kem::*;
let mut rng = OsRng;
let (ek, _dk) = MlKem::<MlKem768>::keygen(&mut rng).unwrap();
let (shared_secret, ciphertext) = MlKem::<MlKem768>::encaps(&ek, &mut rng).unwrap();

pub fn decaps( dk: &DecapsulationKey<P>, ct: &Ciphertext<P>, rng: &mut impl CryptoRng, ) -> Result<SharedSecret, MlKemError>

Decapsulate a ciphertext with full DFA protection.

Recovers the 32-byte shared secret from a ciphertext using the decapsulation (private) key. Implements Algorithm 21 of FIPS 203 with two additional DFA countermeasures:

1. dk integrity check – verifies H(ek) stored in dk to detect fault injection on key material in memory.
2. Double computation – runs the internal decapsulation twice and compares results. A single-fault attack can only corrupt one execution, so divergent results indicate fault injection.

Recommended for embedded and high-security contexts where physical fault attacks are in the threat model.

Arguments

• dk - The decapsulation (private) key, exactly Params::DK_LEN bytes.
• ct - The ciphertext, exactly Params::CT_LEN bytes.
• rng - A cryptographic random number generator (reserved for future use).

Returns

The 32-byte shared secret.

Errors

• MlKemError::InvalidDecapsulationKey if dk has wrong length or fails the integrity check.
• MlKemError::InvalidCiphertext if ct has wrong length.

Example

use quantica::ml_kem::*;
let mut rng = OsRng;
let (ek, dk) = MlKem::<MlKem768>::keygen(&mut rng).unwrap();
let (ss, ct) = MlKem::<MlKem768>::encaps(&ek, &mut rng).unwrap();
let ss2 = MlKem::<MlKem768>::decaps(&dk, &ct, &mut rng).unwrap();
assert_eq!(ss, ss2);

pub fn decaps_fast( dk: &DecapsulationKey<P>, ct: &Ciphertext<P>, ) -> Result<SharedSecret, MlKemError>

Decapsulate a ciphertext without double computation (faster variant).

Same as MlKem::decaps but omits the double-computation DFA countermeasure, making it roughly twice as fast. The H(ek) integrity check on the decapsulation key is still performed.

Use this for software-only contexts where physical fault injection is not part of the threat model.

Arguments

• dk - The decapsulation (private) key, exactly Params::DK_LEN bytes.
• ct - The ciphertext, exactly Params::CT_LEN bytes.

Returns

The 32-byte shared secret.

Errors

• MlKemError::InvalidDecapsulationKey if dk has wrong length or fails the integrity check.
• MlKemError::InvalidCiphertext if ct has wrong length.

pub fn keygen_internal(d: &[u8; 32], z: &[u8; 32]) -> (Vec<u8>, Vec<u8>)

Deterministic key generation for testing and CAVP validation.

Implements Algorithm 16 of FIPS 203 directly, using caller-supplied seeds d and z instead of drawing them from an RNG.

Arguments

• d - 32-byte seed for K-PKE key generation.
• z - 32-byte implicit rejection value stored in the decapsulation key.

Returns

A tuple (encapsulation_key, decapsulation_key) as byte vectors.

pub fn encaps_internal(ek: &[u8], m: &[u8; 32]) -> ([u8; 32], Vec<u8>)

Deterministic encapsulation for testing and CAVP validation.

Implements Algorithm 17 of FIPS 203 directly, using a caller-supplied message m instead of drawing it from an RNG. No input validation is performed on ek.

Arguments

• ek - The encapsulation (public) key.
• m - 32-byte random message seed.

Returns

A tuple (shared_secret, ciphertext).

pub fn decaps_internal(dk: &[u8], ct: &[u8]) -> [u8; 32]

Deterministic decapsulation for testing and CAVP validation.

Implements Algorithm 18 of FIPS 203 directly, with no input validation or DFA countermeasures. All comparisons are still constant-time.

Arguments

• dk - The decapsulation (private) key.
• ct - The ciphertext.

Returns

The 32-byte shared secret.