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.

Features

The following features are provided by this crate:

• zeroize — Enables memory zeroing for all cryptographic secrets
• pkcs8 — Enables PKCS#8 encoding/decoding traits for encapsulation and decapsulation key types
• alloc — Enables allocating PKCS#8 encoding functions
• pem — Enables PEM encoding/decoding support for PKCS#8 keys
• hazmat — Enables EncapsulationKey::encapsulate_deterministic. Useful for testing purposes. Do NOT enable unless you know what you are doing.

The default features are [] (nothing).

⚠️ Security Warning

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

USE AT YOUR OWN RISK!

Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations, excluding explicitly unstable features.

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-Lattice-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 a (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.

// NOTE: requires the `getrandom` feature is enabled

use ml_kem::{
    MlKem768,
    kem::{Decapsulate, Encapsulate, Kem}
};

// Generate a decapsulation/encapsulation keypair
let (dk, ek) = MlKem768::generate_keypair();

// 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();

// Decapsulate the shared key
let k_recv = dk.decapsulate(&ct);

// We've now established a shared key
assert_eq!(k_send, k_recv);

Re-exports

pub use ml_kem_512::MlKem512;

pub use ml_kem_768::MlKem768;

pub use ml_kem_1024::MlKem1024;

pub use array;

pub use kem;

Modules

ml_kem_512

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

ml_kem_768

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

ml_kem_1024

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

pkcs8pkcs8

PKCS#8 encoding support.

Structs

DecapsulationKey

A DecapsulationKey provides the ability to generate a new key pair, and decapsulate an encapsulated shared key.

EncapsulationKey

An EncapsulationKey provides the ability to encapsulate a shared key so that it can only be decapsulated by the holder of the corresponding decapsulation key.

InvalidKey

Error type for TryKeyInit for cases where the provided bytes do not correspond to a valid key.

Traits

ArraySize

Trait which associates a usize size and ArrayType with a typenum-provided Unsigned integer.

Decapsulate

Decapsulator for encapsulated keys, with an associated Encapsulator bounded by the Encapsulate trait.

Encapsulate

Encapsulator for shared secrets.

ExpandedKeyEncodingDeprecated

DEPRECATED: support for encoding and decoding DecapsulationKeys in the legacy expanded form, as opposed to the more widely adopted Seed form.

FromSeed

Initialize a KEM from a Seed.

Generate

Secure random generation.

Kem

Key encapsulation mechanism.

KeyExport

Serialize a key to a byte array.

KeyInit

Types which can be initialized from a key.

KeySizeUser

Types which use key for initialization.

ParameterSet

A ParameterSet captures the parameters that describe a particular instance of ML-KEM.

TryKeyInit

Types which can be fallibly initialized from a key.

Type Aliases

B32

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

Ciphertext

Ciphertext message (a.k.a. “encapsulated key”) produced by Encapsulate::encapsulate which is an encrypted SharedKey that can be decrypted using Decapsulate::decapsulate.

DecapsulationKey512

An ML-KEM-512 DecapsulationKey which provides the ability to generate a new key pair, and decapsulate an encapsulated shared key.

DecapsulationKey768

An ML-KEM-768 DecapsulationKey which provides the ability to generate a new key pair, and decapsulate an encapsulated shared key.

DecapsulationKey1024

An ML-KEM-1024 DecapsulationKey which provides the ability to generate a new key pair, and decapsulate an encapsulated shared key.

EncapsulationKey512

An ML-KEM-512 EncapsulationKey provides the ability to encapsulate a shared key so that it can only be decapsulated by the holder of the corresponding decapsulation key.

EncapsulationKey768

An ML-KEM-768 EncapsulationKey provides the ability to encapsulate a shared key so that it can only be decapsulated by the holder of the corresponding decapsulation key.

EncapsulationKey1024

An ML-KEM-1024 EncapsulationKey provides the ability to encapsulate a shared key so that it can only be decapsulated by the holder of the corresponding decapsulation key.

ExpandedDecapsulationKey

Serialized decapsulation key after having been expanded from a Seed.

Key

Key used by KeySizeUser implementors.

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

Shared key established by using ML-KEM, returned from both encapsulation and decapsulation.