Module crypto_kem_mlkem768 

ML-KEM-768 key encapsulation

Implements libsodium’s crypto_kem_mlkem768_* functions: ML-KEM-768 from FIPS 203, a lattice-based key encapsulation mechanism (KEM) believed to resist attacks by quantum computers.

A KEM lets a sender create a fresh shared secret for the holder of a public key. crypto_kem_mlkem768_enc returns the shared secret and a ciphertext; the recipient recovers the same secret with crypto_kem_mlkem768_dec and its secret key. Feed the shared secret to a key-derivation function before using it as an encryption key. A KEM does not authenticate the sender.

Prefer crate::classic::crypto_kem, which uses X-Wing: ML-KEM-768 combined with X25519, so it stays secure if either one is broken. Use ML-KEM-768 directly when a protocol requires it.

Encapsulation rejects a public key that is not a valid FIPS 203 encapsulation key. Decapsulation always succeeds: a ciphertext that was not created for the key yields an unrelated pseudorandom secret (“implicit rejection”), so the caller learns nothing from the result.

use dryoc::classic::crypto_kem_mlkem768::*;

let (public_key, secret_key) = crypto_kem_mlkem768_keypair();

let mut ciphertext = [0u8; dryoc::constants::CRYPTO_KEM_MLKEM768_CIPHERTEXTBYTES];
let mut sender_secret = SharedSecret::default();
crypto_kem_mlkem768_enc(&mut ciphertext, &mut sender_secret, &public_key)
    .expect("encapsulation failed");

let mut recipient_secret = SharedSecret::default();
crypto_kem_mlkem768_dec(&mut recipient_secret, &ciphertext, &secret_key);
assert_eq!(sender_secret, recipient_secret);

Functions

crypto_kem_mlkem768_dec

Recovers the shared secret encapsulated in ciphertext with secret_key, writing it to shared_secret. A ciphertext not created for this key yields an unrelated pseudorandom secret instead of an error.

crypto_kem_mlkem768_enc

Creates a random shared secret for public_key, writing it to shared_secret and its encapsulation to ciphertext.

crypto_kem_mlkem768_enc_deterministic

Deterministic variant of crypto_kem_mlkem768_enc with the encapsulation randomness taken from seed. For known-answer tests; a repeated seed repeats the shared secret.

crypto_kem_mlkem768_keypair

Returns a randomly generated key pair.

crypto_kem_mlkem768_keypair_inplace

In-place variant of crypto_kem_mlkem768_keypair.

crypto_kem_mlkem768_seed_keypair

Deterministically derives a key pair from seed.

crypto_kem_mlkem768_seed_keypair_inplace

In-place variant of crypto_kem_mlkem768_seed_keypair.

Type Aliases

Ciphertext

ML-KEM-768 ciphertext.

EncSeed

Encapsulation seed: FIPS 203’s message m.

PublicKey

ML-KEM-768 public (encapsulation) key.

SecretKey

ML-KEM-768 secret (decapsulation) key, in FIPS 203’s expanded form.

Seed

Key-generation seed: FIPS 203’s d || z.

SharedSecret

Shared secret produced by encapsulation and decapsulation.