Crate ml_kem 

RustCrypto: ML-KEM

Pure Rust implementation of the Module-Lattice-Based Key-Encapsulation Mechanism Standard (formerly known as Kyber) as described in FIPS 203 (final).

Documentation

About

ML-KEM is an algorithm which uses public-key cryptography to securely transfer a symmetric key between two parties who want to establish encrypted communications with each other. It uses algorithms which resist potential attacks by hypothetical future quantum computers which, when such computers are sufficiently mature, pose a problem for the algorithms we typically use for secure key establishment using public-key cryptography such as (EC)DH and RSA key encipherment.

Originally developed as CRYSTALS-Kyber (a.k.a. “Kyber”), ML-KEM is a refinement of the original Kyber algorithm after it was selected for standardization by NIST’s Post-Quantum Cryptography (PQC) competition. The Kyber algorithm received considerable feedback as part of the standardization process and as such, ML-KEM includes many changes from the original Kyber. It can be though of as the official successor of Kyber.

In summary, ML-KEM stands at the forefront of post-quantum cryptography, offering enhanced security and efficiency in key encapsulation mechanisms to safeguard sensitive communications in an era where quantum computers potentially pose a looming threat.

⚠️ Security Warning

The implementation contained in this crate has never been independently audited!

USE AT YOUR OWN RISK!

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Usage

This crate implements the Module-Latice-based Key Encapsulation Method (ML-KEM) algorithm being standardized by NIST in FIPS 203. ML-KEM is a KEM in the sense that it creates an (decapsulation key, encapsulation key) pair, such that anyone can use the encapsulation key to establish a shared key with the holder of the decapsulation key. ML-KEM is the first KEM algorithm standardized by NIST that is designed to be resistant to attacks using quantum computers.

let mut rng = rand::rng();

// Generate a (decapsulation key, encapsulation key) pair
let (dk, ek) = MlKem768::generate(&mut rng);

// Encapsulate a shared key to the holder of the decapsulation key, receive the shared
// secret `k_send` and the encapsulated form `ct`.
let (ct, k_send) = ek.encapsulate(&mut rng).unwrap();

// Decapsulate the shared key and verify that it was faithfully received.
let k_recv = dk.decapsulate(&ct).unwrap();
assert_eq!(k_send, k_recv);

Re-exports

pub use hybrid_array as array;

Modules

kem

Section 6. The ML-KEM Key-Encapsulation Mechanism

pkcs8pkcs8

PKCS#8 encoding support.

Structs

MlKem512Params

MlKem512 is the parameter set for security category 1, corresponding to key search on a block cipher with a 128-bit key.

MlKem768Params

MlKem768 is the parameter set for security category 3, corresponding to key search on a block cipher with a 192-bit key.

MlKem1024Params

MlKem1024 is the parameter set for security category 5, corresponding to key search on a block cipher with a 256-bit key.

Traits

ArraySize

An array length with other useful properties

EncapsulateDeterministicdeterministic

A value that can be encapsulated to. Note that this interface is not safe: In order for the KEM to be secure, the m input must be randomly generated.

EncodedSizeUser

An object that knows what size it is

KemCore

A generic interface to a Key Encapsulation Method

ParameterSet

A ParameterSet captures the parameters that describe a particular instance of ML-KEM. There are three variants, corresponding to three different security levels.

Type Aliases

B32deterministic

A 32-byte array, defined here for brevity because it is used several times

Ciphertext

A ciphertext produced by the KEM K

Encoded

A byte array encoding a value the indicated size

MlKem512

ML-KEM with the parameter set for security category 1, corresponding to key search on a block cipher with a 128-bit key.

MlKem768

ML-KEM with the parameter set for security category 3, corresponding to key search on a block cipher with a 192-bit key.

MlKem1024

ML-KEM with the parameter set for security category 5, corresponding to key search on a block cipher with a 256-bit key.

Seed

ML-KEM seeds are decapsulation (private) keys, which are consistently 64-bytes across all security levels, and are the preferred serialization for representing such keys.

SharedKey

A shared key produced by the KEM K