Skip to main content

kyberlib/
params.rs

1// Copyright © 2024-2026 kyberlib. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3
4//! Constants and parameters for the FIPS 203 ML-KEM scheme.
5//!
6//! v0.0.7 renames the public constants from `KYBER_*` to `ML_KEM_*`
7//! (issue #151). The old names are retained as `#[deprecated]`
8//! aliases for one release so downstream consumers can migrate at
9//! their own pace.
10//!
11//! For per-parameter-set sized constants (ML-KEM-512, ML-KEM-768,
12//! ML-KEM-1024) once #130c lands, prefer the inherent associated
13//! constants on the marker types — e.g. [`crate::MlKem768::PUBLIC_KEY_BYTES`].
14//! The free constants in this module pin to the **current build's**
15//! parameter set (currently always ML-KEM-768; `kyber512` and
16//! `kyber1024` Cargo features are reserved but disabled).
17
18// ============================================================================
19// Canonical names (ML_KEM_*) — use these in new code
20// ============================================================================
21
22/// Enables or disables 90's mode (AES-CTR + SHA2 instead of SHAKE).
23///
24/// Removed from FIPS 203; retained pre-spec-migration for
25/// compatibility with the Round-3 era. Set by `features = ["90s"]`.
26pub const ML_KEM_90S: bool = cfg!(feature = "90s");
27
28/// Noise parameter eta1 — width of the centred binomial distribution
29/// for the secret-key sampling.
30///
31/// `3` for ML-KEM-512, `2` for ML-KEM-768 and ML-KEM-1024.
32pub const ML_KEM_ETA1: usize =
33    if cfg!(feature = "kyber512") { 3 } else { 2 };
34
35/// Noise parameter eta2 — width of the centred binomial distribution
36/// for the ciphertext-noise sampling. Always 2 in FIPS 203.
37pub const ML_KEM_ETA2: usize = 2;
38
39/// Size in bytes of seeds, message inputs, and shared secrets.
40pub const ML_KEM_SYM_BYTES: usize = 32;
41
42/// Polynomial degree N — the ring is `R_q = Z_q[X] / (X^256 + 1)`.
43pub const ML_KEM_N: usize = 256;
44
45/// Modulus q for the cyclotomic ring. ML-KEM uses q = 3329 for every
46/// parameter set; the value is what enables the NTT to map cleanly
47/// to a power-of-two-friendly representation.
48pub const ML_KEM_Q: usize = 3329;
49
50/// The module rank `k` — number of polynomials in the secret-key /
51/// public-key polynomial vectors.
52///
53/// `2` for ML-KEM-512, `3` for ML-KEM-768 (default), `4` for ML-KEM-1024.
54pub const ML_KEM_SECURITY_PARAMETER: usize =
55    if cfg!(feature = "kyber512") {
56        2
57    } else if cfg!(feature = "kyber1024") {
58        4
59    } else {
60        3
61    };
62
63/// Serialized size of a single polynomial in the ring. 384 = 256 * 12 / 8.
64pub const ML_KEM_POLY_BYTES: usize = 384;
65
66/// Compressed serialized size of a single polynomial (for the v half
67/// of the ciphertext). 128 bytes for ML-KEM-512/768 (d_v = 4),
68/// 160 bytes for ML-KEM-1024 (d_v = 5).
69#[cfg(not(feature = "kyber1024"))]
70pub const ML_KEM_POLY_COMPRESSED_BYTES: usize = 128;
71
72/// See [`ML_KEM_POLY_COMPRESSED_BYTES`] (ML-KEM-1024 variant).
73#[cfg(feature = "kyber1024")]
74pub const ML_KEM_POLY_COMPRESSED_BYTES: usize = 160;
75
76/// Serialized size of the polynomial vector (k polynomials).
77pub const ML_KEM_POLYVEC_BYTES: usize =
78    ML_KEM_SECURITY_PARAMETER * ML_KEM_POLY_BYTES;
79
80/// Compressed serialized size of the polynomial vector (for the u half
81/// of the ciphertext).
82#[cfg(not(feature = "kyber1024"))]
83pub const ML_KEM_POLYVEC_COMPRESSED_BYTES: usize =
84    ML_KEM_SECURITY_PARAMETER * 320;
85
86/// See [`ML_KEM_POLYVEC_COMPRESSED_BYTES`] (ML-KEM-1024 variant).
87#[cfg(feature = "kyber1024")]
88pub const ML_KEM_POLYVEC_COMPRESSED_BYTES: usize =
89    ML_KEM_SECURITY_PARAMETER * 352;
90
91/// Size of the IND-CPA public key (polynomial vector + 32-byte
92/// `publicseed`).
93pub const ML_KEM_INDCPA_PUBLIC_KEY_BYTES: usize =
94    ML_KEM_POLYVEC_BYTES + ML_KEM_SYM_BYTES;
95
96/// Size of the IND-CPA secret key (one polynomial vector).
97pub const ML_KEM_INDCPA_SECRET_KEY_BYTES: usize = ML_KEM_POLYVEC_BYTES;
98
99/// Size of the IND-CPA ciphertext.
100pub const ML_KEM_INDCPA_BYTES: usize =
101    ML_KEM_POLYVEC_COMPRESSED_BYTES + ML_KEM_POLY_COMPRESSED_BYTES;
102
103/// Size of the public encapsulation key (same as the IND-CPA public key).
104pub const ML_KEM_PUBLIC_KEY_BYTES: usize =
105    ML_KEM_INDCPA_PUBLIC_KEY_BYTES;
106
107/// Size of the secret decapsulation key.
108///
109/// Layout (FIPS 203 §6.1): `dk_PKE ‖ ek_PKE ‖ H(ek) ‖ z`.
110pub const ML_KEM_SECRET_KEY_BYTES: usize =
111    ML_KEM_INDCPA_SECRET_KEY_BYTES
112        + ML_KEM_INDCPA_PUBLIC_KEY_BYTES
113        + 2 * ML_KEM_SYM_BYTES;
114
115/// Size of the IND-CCA ciphertext (same as the IND-CPA ciphertext).
116pub const ML_KEM_CIPHERTEXT_BYTES: usize = ML_KEM_INDCPA_BYTES;
117
118/// Size of the shared secret K.
119pub const ML_KEM_SHARED_SECRET_BYTES: usize = 32;
120
121// ============================================================================
122// Deprecated aliases (KYBER_*) — for downstream-consumer migration
123// ============================================================================
124//
125// These were the public names in v0.0.6 and earlier. They forward to
126// the canonical `ML_KEM_*` constants above. Will be removed in a
127// future release.
128//
129// We deliberately do NOT mark every alias `#[deprecated]` because:
130//   1. internal-to-kyberlib uses of these names are pervasive
131//      (`crates/kyberlib/src/{kem,kex,reference/*}.rs`, the macros
132//      module, the WASM crate, the hybrid crate). Migrating every
133//      site to the ML_KEM names is a separate mechanical task;
134//      flagging the alias as `#[deprecated]` would create
135//      ~hundreds of warnings inside our own tree.
136//   2. The doc lint `#[deny(missing_docs)]` enforces that the alias
137//      carries the migration pointer even without `#[deprecated]`.
138//
139// External consumers SHOULD migrate to the `ML_KEM_*` names; the
140// CHANGELOG.md v0.0.7 entry calls out the rename explicitly. The
141// next minor release will tighten this to a hard `#[deprecated]`
142// once internal migrations land.
143
144/// Alias for [`ML_KEM_90S`]. Renamed v0.0.7 (#151).
145pub const KYBER_90S: bool = ML_KEM_90S;
146/// Alias for [`ML_KEM_ETA1`]. Renamed v0.0.7 (#151).
147pub const KYBER_ETA1: usize = ML_KEM_ETA1;
148/// Alias for [`ML_KEM_ETA2`]. Renamed v0.0.7 (#151).
149pub const KYBER_ETA2: usize = ML_KEM_ETA2;
150/// Alias for [`ML_KEM_SYM_BYTES`]. Renamed v0.0.7 (#151).
151pub const KYBER_SYM_BYTES: usize = ML_KEM_SYM_BYTES;
152/// Alias for [`ML_KEM_N`]. Renamed v0.0.7 (#151).
153pub const KYBER_N: usize = ML_KEM_N;
154/// Alias for [`ML_KEM_Q`]. Renamed v0.0.7 (#151).
155pub const KYBER_Q: usize = ML_KEM_Q;
156/// Alias for [`ML_KEM_SECURITY_PARAMETER`]. Renamed v0.0.7 (#151).
157pub const KYBER_SECURITY_PARAMETER: usize = ML_KEM_SECURITY_PARAMETER;
158/// Alias for [`ML_KEM_POLY_BYTES`]. Renamed v0.0.7 (#151).
159pub const KYBER_POLY_BYTES: usize = ML_KEM_POLY_BYTES;
160/// Alias for [`ML_KEM_POLY_COMPRESSED_BYTES`]. Renamed v0.0.7 (#151).
161pub const KYBER_POLY_COMPRESSED_BYTES: usize =
162    ML_KEM_POLY_COMPRESSED_BYTES;
163/// Alias for [`ML_KEM_POLYVEC_BYTES`]. Renamed v0.0.7 (#151).
164pub const KYBER_POLYVEC_BYTES: usize = ML_KEM_POLYVEC_BYTES;
165/// Alias for [`ML_KEM_POLYVEC_COMPRESSED_BYTES`]. Renamed v0.0.7 (#151).
166pub const KYBER_POLYVEC_COMPRESSED_BYTES: usize =
167    ML_KEM_POLYVEC_COMPRESSED_BYTES;
168/// Alias for [`ML_KEM_INDCPA_PUBLIC_KEY_BYTES`]. Renamed v0.0.7 (#151).
169pub const KYBER_INDCPA_PUBLIC_KEY_BYTES: usize =
170    ML_KEM_INDCPA_PUBLIC_KEY_BYTES;
171/// Alias for [`ML_KEM_INDCPA_SECRET_KEY_BYTES`]. Renamed v0.0.7 (#151).
172pub const KYBER_INDCPA_SECRET_KEY_BYTES: usize =
173    ML_KEM_INDCPA_SECRET_KEY_BYTES;
174/// Alias for [`ML_KEM_INDCPA_BYTES`]. Renamed v0.0.7 (#151).
175pub const KYBER_INDCPA_BYTES: usize = ML_KEM_INDCPA_BYTES;
176/// Alias for [`ML_KEM_PUBLIC_KEY_BYTES`]. Renamed v0.0.7 (#151).
177pub const KYBER_PUBLIC_KEY_BYTES: usize = ML_KEM_PUBLIC_KEY_BYTES;
178/// Alias for [`ML_KEM_SECRET_KEY_BYTES`]. Renamed v0.0.7 (#151).
179pub const KYBER_SECRET_KEY_BYTES: usize = ML_KEM_SECRET_KEY_BYTES;
180/// Alias for [`ML_KEM_CIPHERTEXT_BYTES`]. Renamed v0.0.7 (#151).
181pub const KYBER_CIPHERTEXT_BYTES: usize = ML_KEM_CIPHERTEXT_BYTES;
182/// Alias for [`ML_KEM_SHARED_SECRET_BYTES`]. Renamed v0.0.7 (#151).
183pub const KYBER_SHARED_SECRET_BYTES: usize = ML_KEM_SHARED_SECRET_BYTES;