Module mlkem768

Available on crate feature dep_orion only.

ML-KEM-768 as specified in FIPS-203.

ML-KEM key usage recommendations

In general, it is highly recommended to use the KeyPair type to deal with decapsulating operations, or decapsulation keys in general.

A KeyPair requires, or automatically generates, a Seed. It cannot be made solely from encoded/serialized decapsulation key in bytes, unless a Seed is also provided.

A seed is only 64 bytes, is fully FIPS compliant, and hardens against attacks described here.

Serialized decapsulation keys

It is possible to instantiate a DecapsulationKey directly, if strictly required, using DecapsulationKey::unchecked_from_slice().

Parameters:

• ek: The public encapsulation key, for which a shared secret and ciphertext is generated.
• dk: The secret decapsulation key, for which a ciphertext is used to derive a shared secret.
• c: The public ciphertext, sent to the decapsulating party.
• m: Explicit randomness used for encapsulation.

Errors:

An error will be returned if:

• getrandom::fill() fails during encapsulation.
• m is not 32 bytes.

Panics:

A panic will occur if:

• getrandom::fill() fails during KeyPair::generate().

Security:

• It is critical that both the seed and explicit randomness m, used for key generation and encapsulation are generated using a strong CSPRNG.
• Users should always prefer encapsulation without specifying explicit randomness, if possible. encap_deterministic() exists mainly for no_std usage.
• Prefer using KeyPair to create and use ML-KEM keys, which is MAL-BIND-K-CT secure.

Example:

use orion::hazardous::kem::mlkem768::*;

let keypair = KeyPair::generate()?;

let (sender_shared_secret, sender_ciphertext) = MlKem768::encap(keypair.public())?;
let recipient_shared_secret = MlKem768::decap(keypair.private(), &sender_ciphertext)?;

assert_eq!(sender_shared_secret, recipient_shared_secret);

Structs

Ciphertext

A type to represent the KEM Ciphertext that ML-KEM-768 returns.

DecapsulationKey

A type to represent the DecapsulationKey that ML-KEM-768 produces.

EncapsulationKey

A type to represent the EncapsulationKey that ML-KEM-768 returns.

KeyPair

A keypair of ML-KEM-768 keys, that are derived from a given seed.

MlKem768

ML-KEM-768.

Seed

A type to represent the d||z seed used by ML-KEM to produce a decapsulation key and its corresponding encapsulation key.

SharedSecret

A type to represent the SharedSecret that ML-KEM-768 produces.