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 the FIPS 203 Initial Public Draft.

Documentation

About

ML-KEM is a cutting-edge post-quantum secure key encapsulation mechanism (KEM). KEMs play a vital role in modern cryptographic systems by securely exchanging keys between parties, ensuring confidential communication over insecure channels.

Originally developed as Kyber, ML-KEM inherits the foundation of its predecessor while introducing refinements and optimizations to enhance its security and efficiency. ML-KEM and Kyber are intimately related, with ML-KEM representing a refined and evolved version of the original Kyber algorithm. While Kyber pioneered lattice-based cryptography and provided a reliable framework for secure key exchange, ML-KEM builds upon this foundation, incorporating advancements in cryptographic research and addressing potential vulnerabilities.

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!

Minimum Supported Rust Version

This crate requires Rust 1.74 at a minimum.

We may change the MSRV in the future, but it will be accompanied by a minor version bump.

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::thread_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);

Modules

• kem
  Section 6. The ML-KEM Key-Encapsulation Mechanism

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
• Decapsulate
  A value that can be used to decapsulate an encapsulated key. Often, this will just be a secret key. But, as with Encapsulate, it can be a bundle of secret keys, or it can include a sender’s private key for authenticated encapsulation.
• Encapsulate
  A value that can be encapsulated to. Often, this will just be a public key. However, it can also be a bundle of public keys, or it can include a sender’s private key for authenticated encapsulation.
• 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.
• SharedKey
  A shared key produced by the KEM K