kyber_nz/
lib.rs

1//! # kyber-nz (ML-KEM / FIPS 203)
2//!
3//! A **pure Rust**, **secure**, and **robust** implementation of the **FIPS 203** (Module-Lattice-Based Key-Encapsulation Mechanism) standard,
4//! formerly known as **CRYSTALS-Kyber**.
5//!
6//! This library strives for excellence in security (resistance to side-channel attacks)
7//! and reliability (strict error handling).
8//!
9//! ## 🛡️ Security & Robustness
10//!
11//! * **Constant Time**: All sensitive operations (especially decapsulation and hash comparison)
12//!   are performed in constant time using the [`subtle`] crate to prevent Timing Attacks.
13//! * **Memory Clearing**: Structures containing secrets (`KemDecapsKey`, `KemSharedSecret`) implement
14//!   the [`zeroize::Zeroize`] and [`zeroize::ZeroizeOnDrop`] traits. They are automatically wiped from RAM
15//!   when they go out of scope.
16//! * **Determinism**: Key generation and encapsulation functions accept an external random number generator
17//!   (implementing [`rand_core::RngCore`]), allowing for deterministic tests (Known Answer Tests).
18//!
19//! ## 🚀 Quick Start (ML-KEM-768)
20//!
21//! ```rust
22//! use kyber_nz::Kyber768; // Alias for ML-KEM-768
23//! use kyber_nz::traits::KemScheme;
24//! use rand::rngs::OsRng;
25//!
26//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! // 1. Initialization
28//! let kem = Kyber768::new();
29//!
30//! // 2. Key Generation (Alice)
31//! let (ek, dk) = kem.key_gen(&mut OsRng);
32//!
33//! // 3. Encapsulation (Bob)
34//! let (shared_secret_bob, ciphertext) = kem.encaps(&ek, &mut OsRng);
35//!
36//! // 4. Decapsulation (Alice)
37//! let shared_secret_alice = kem.decaps(&dk, &ciphertext);
38//!
39//! // The secrets are identical
40//! assert_eq!(shared_secret_bob.0, shared_secret_alice.0);
41//! # Ok(())
42//! # }
43//! ```
44//!
45//! ## 📦 Architecture
46//!
47//! The library is structured in a modular way:
48//!
49//! - [`kem_scheme`]: Implementation of the Key Encapsulation Mechanism (ML-KEM).
50//! - [`pke_scheme`]: Implementation of the underlying Public Key Encryption (K-PKE).
51//! - [`polynomial`]: Polynomial arithmetic on the ring $R_q = \mathbb{Z}_q[X]/(X^{256}+1)$.
52//! - [`params`]: Definition of security parameters via the [`params::SecurityLevel`] trait.
53
54use crate::params::{Kyber1024Params, Kyber512Params, Kyber768Params};
55use crate::{constants::KyberParams, kem_scheme::MlKem, polynomial::Polynomial};
56
57pub mod constants;
58pub mod conversion;
59pub mod errors;
60pub mod hash;
61pub mod kem_scheme;
62pub mod params;
63pub mod pke_scheme;
64pub mod polynomial;
65pub mod traits;
66
67/// Type alias for a polynomial in the ring R_q with Kyber parameters.
68pub type KyberPoly = Polynomial<KyberParams>;
69
70/// Alias for **ML-KEM-512**.
71pub type Kyber512 = MlKem<2, Kyber512Params, KyberParams>;
72
73/// Alias for **ML-KEM-768**.
74pub type Kyber768 = MlKem<3, Kyber768Params, KyberParams>;
75
76/// Alias for **ML-KEM-1024**.
77pub type Kyber1024 = MlKem<4, Kyber1024Params, KyberParams>;
kyber_nz/lib.rs

kyber_nz/
lib.rs
