Crate kyberlib 

kyberlib — FIPS 203 ML-KEM in Rust

Audit-friendly, no_std-compatible implementation of FIPS 203 ML-KEM (the standardised CRYSTALS-Kyber post-quantum key encapsulation mechanism, finalised August 2024). 60/60 ACVP conformance against the NIST test corpus.

At a glance

• Three parameter sets: MlKem512, MlKem768 (default), MlKem1024 — covering NIST security categories 1, 3, 5.
• Two APIs: the v0.0.7 typed-state API (KemCore trait + typed wrappers) and the legacy free-function API (keypair / encapsulate / decapsulate).
• Constant-time: KyberSlash audit clean (ADR 0003); secrets carry zeroize::Zeroize; dudect regression gate in scripts/dudect.sh.
• no_std: optional std feature. Default features pull in std for ergonomic error types.
• No unsafe in the safe core. The optional avx2 / nasm backends scope unsafe to the SIMD module only.

Quick start (typed API — recommended)

use kyberlib::{KemCore, MlKem768};

let mut rng = rand::thread_rng();

// Bob generates a (decap, encap) keypair.
let (bob_dk, bob_ek) = MlKem768::generate(&mut rng)?;

// Alice encapsulates a shared secret against Bob's encap key.
let (ciphertext, ss_alice) = bob_ek.encapsulate(&mut rng)?;

// Bob decapsulates with his decap key (implicit rejection per
// FIPS 203 §6.3 — never panics, never branches on validity).
let ss_bob = bob_dk.decapsulate(&ciphertext);

assert_eq!(ss_alice, ss_bob);

Quick start (legacy free-function API)

use kyberlib::{keypair, encapsulate, decapsulate};

let mut rng = rand::thread_rng();
let bob = keypair(&mut rng)?;
let (ct, ss_a) = encapsulate(&bob.public, &mut rng)?;
let ss_b = decapsulate(&ct, &bob.secret)?;
assert_eq!(ss_a, ss_b);

Cargo features

Feature	Default	Description
std	✅	Enables the std library — required for std::error::Error on KyberLibError. Disable for no_std targets.
kyber768	✅	NIST security category 3 (≈ AES-192). Default.
kyber512		NIST security category 1 (≈ AES-128). Mutually exclusive with kyber768/kyber1024.
kyber1024		NIST security category 5 (≈ AES-256). Required by CNSA 2.0 for NSS by 2027-01-01. Mutually exclusive with kyber768/kyber512.
90s		“Kyber-90s” variant — SHA-2 / AES-CTR instead of SHAKE. Removed in FIPS 203 but retained for pre-spec compatibility.
90s-fixslice		90s with a bitsliced AES implementation (aes + ctr crates).
avx2		AVX2-accelerated backend (x86_64 only). Compile-errors on other arches.
nasm		AVX2 via NASM assembler (instead of GAS). Requires NASM installed. Implies avx2.
hazmat		Re-exports the IND-CPA primitives (no Fujisaki–Okamoto transform). Advanced use only; the resulting construction is NOT IND-CCA secure.

Architecture

See api for the legacy free-function surface, ml_kem for the v0.0.7 typed-state API, kex for the Uake/Ake key-exchange wrappers, and error for the KyberLibError enum.

Errors

All fallible public functions return KyberLibError. Variants:

• KyberLibError::InvalidInput — input slice length mismatch. Typical cause: two peers using different security levels.
• KyberLibError::InvalidKey — imported keypair fails the encap/decap self-test (the public and secret halves don’t belong together).
• KyberLibError::InvalidLength — buffer length below the required copy length.
• KyberLibError::Decapsulation — ciphertext failed to authenticate. Not normally returned: the FIPS 203 implicit- rejection construction returns a pseudorandom shared secret on invalid input instead.
• KyberLibError::RandomBytesGeneration — external RNG failed (e.g. hardware RNG fault).

Macros (legacy compatibility surface)

See macros for the kyberlib_* macro family that wraps the free-function API for terser call sites. Prefer the typed API (KemCore) in new code.

Re-exports

pub use reference::indcpa;(Non-x86-64 or non-avx2) and hazmat

pub use error::KyberLibError;

pub use ml_kem::KemCore;

pub use ml_kem::MlKem1024;

pub use ml_kem::MlKem1024Ciphertext;

pub use ml_kem::MlKem1024DecapKey;

pub use ml_kem::MlKem1024EncapKey;

pub use ml_kem::MlKem512;

pub use ml_kem::MlKem512Ciphertext;

pub use ml_kem::MlKem512DecapKey;

pub use ml_kem::MlKem512EncapKey;

pub use ml_kem::MlKem768;

pub use ml_kem::MlKem768Ciphertext;

pub use ml_kem::MlKem768DecapKey;

pub use ml_kem::MlKem768EncapKey;

pub use ml_kem::SharedSecret;

pub use params::KYBER_90S;

pub use params::KYBER_CIPHERTEXT_BYTES;

pub use params::KYBER_PUBLIC_KEY_BYTES;

pub use params::KYBER_SECRET_KEY_BYTES;

pub use params::KYBER_SECURITY_PARAMETER;

pub use params::KYBER_SHARED_SECRET_BYTES;

pub use params::KYBER_SYM_BYTES;

pub use params::ML_KEM_90S;

pub use params::ML_KEM_CIPHERTEXT_BYTES;

pub use params::ML_KEM_PUBLIC_KEY_BYTES;

pub use params::ML_KEM_SECRET_KEY_BYTES;

pub use params::ML_KEM_SECURITY_PARAMETER;

pub use params::ML_KEM_SHARED_SECRET_BYTES;

pub use params::ML_KEM_SYM_BYTES;

pub use paramsets::MlKemParams;

pub use api::*;

pub use kex::*;

Modules

api

API for the KyberLib library. Legacy free-function KEM API.

error

Error types for the KyberLib library. Error types.

kem

Key encapsulation module for the KyberLib library.

kex

Key exchange structs for the KyberLib library. Authenticated key-exchange wrappers around the KEM core.

macros

Macro utilities for the KyberLib library.

ml_kem

FIPS 203 ML-KEM type-state API (v0.0.7 — see issue #130). FIPS 203 ML-KEM type-state API.

oid

IETF LAMPS object identifiers for ML-KEM parameter sets (v0.0.7 — see issue #150). Object identifiers for ML-KEM parameter sets per the IETF LAMPS drafts (draft-ietf-lamps-kyber-certificates, draft-ietf-lamps-cms-kyber, RFC 9936).

params

Parameters for the KyberLib library. Constants and parameters for the FIPS 203 ML-KEM scheme.

paramsets

Parameter-pack trait unifying ML-KEM-512 / 768 / 1024 — foundation for the const-generic refactor tracked as #130b. Parameter-pack trait for the three FIPS 203 ML-KEM parameter sets.

referenceNon-x86-64 or non-avx2

Reference implementation for the KyberLib library.

rng

Random number generators for the KyberLib library. RNG helpers.

symmetric

Symmetric key encapsulation module for the KyberLib library. Symmetric primitives — SHAKE-128/256 (default) or AES-256-CTR + SHA-2 (under the deprecated 90s feature).

Macros

kyberlib_ake_client_confirm

Decapsulates and authenticates the shared secret from the output of kyberlib_ake_server_receive().

kyberlib_ake_client_init

Initiates a Mutually Authenticated Key Exchange.

kyberlib_ake_server_receive

Handles and authenticates the output of a kyberlib_ake_client_init() request.

kyberlib_assert

Asserts that a given expression is true. Panics if the assertion fails.

kyberlib_decrypt_message

Generates a shared secret for a given cipher text and private key.

kyberlib_encrypt_message

Generates cipher text and a shared secret for a given public key.

kyberlib_generate_key_pair

Generates a public and private key pair for CCA-secure Kyber key encapsulation mechanism.

kyberlib_max

Returns the maximum of the given values.

kyberlib_min

Returns the minimum of the given values.

kyberlib_uake_client_confirm

Decapsulates and authenticates the shared secret from the output of kyberlib_uake_server_receive().

kyberlib_uake_client_init

Initiates a Unilaterally Authenticated Key Exchange.

kyberlib_uake_server_receive

Handles the output of a kyberlib_uake_client_init() request.

Traits

CryptoRng

A marker trait used to indicate that an RngCore or BlockRngCore implementation is supposed to be cryptographically secure.

RngCore

The core of a random number generator.