Skip to main content

Crate kyberlib

Crate kyberlib 

Source
Expand description

§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). 180/180 ACVP conformance against the NIST test corpus (60 vectors each for ML-KEM-512, -768 and -1024).

kyberlib logo

§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.
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

FeatureDefaultDescription
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.
kyber512NIST security category 1 (≈ AES-128). Mutually exclusive with kyber768/kyber1024.
kyber1024NIST 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-fixslice90s with a bitsliced AES implementation (aes + ctr crates).
avx2AVX2-accelerated backend (x86_64 only). Compile-errors on other arches.
nasmAVX2 via NASM assembler (instead of GAS). Requires NASM installed. Implies avx2.
hazmatRe-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, hazmat::kex (feature hazmat) for the Uake/Ake key exchanges, and error for the KyberLibError enum.

§Errors

All fallible public functions return KyberLibError. Variants:

§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 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::*;

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.
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.
reference
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_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.

Constants§

BACKEND
Name of the backend serving the typed ML-KEM API in this build.

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.