Skip to main content

kyberlib/
kem.rs

1// Copyright © 2024 kyberlib. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3
4use crate::input_check::coefficients_reduced;
5use crate::{
6    error::KyberLibError, indcpa::*, params::*, rng::randombytes,
7    symmetric::*, verify::*,
8};
9use rand_core::{CryptoRng, RngCore};
10
11/// Generates a public and private key pair for CCA-secure Kyber key encapsulation mechanism.
12///
13/// # Arguments
14///
15/// * `pk` - Output public key (an already allocated array of CRYPTO_PUBLICKEYBYTES bytes).
16/// * `sk` - Output private key (an already allocated array of CRYPTO_SECRETKEYBYTES bytes).
17/// * `_rng` - Random number generator implementing RngCore + CryptoRng.
18/// * `_seed` - Optional seed for key generation.
19///
20/// # Errors
21///
22/// Returns a `KyberLibError` on failure.
23pub fn generate_key_pair<R>(
24    pk: &mut [u8],
25    sk: &mut [u8],
26    _rng: &mut R,
27    _seed: Option<(&[u8], &[u8])>,
28) -> Result<(), KyberLibError>
29where
30    R: RngCore + CryptoRng,
31{
32    const PK_START: usize =
33        KYBER_SECRET_KEY_BYTES - (2 * KYBER_SYM_BYTES);
34    const SK_START: usize = KYBER_SECRET_KEY_BYTES - KYBER_SYM_BYTES;
35    const END: usize =
36        KYBER_INDCPA_PUBLIC_KEY_BYTES + KYBER_INDCPA_SECRET_KEY_BYTES;
37
38    indcpa_keypair(pk, sk, _seed, _rng)?;
39
40    sk[KYBER_INDCPA_SECRET_KEY_BYTES..END]
41        .copy_from_slice(&pk[..KYBER_INDCPA_PUBLIC_KEY_BYTES]);
42    hash_h(&mut sk[PK_START..], pk, KYBER_PUBLIC_KEY_BYTES);
43
44    if let Some(s) = _seed {
45        sk[SK_START..].copy_from_slice(s.1);
46    } else {
47        randombytes(&mut sk[SK_START..], KYBER_SYM_BYTES, _rng)?;
48    }
49
50    Ok(())
51}
52
53/// Generates cipher text and a shared secret for a given public key.
54///
55/// # Arguments
56///
57/// * `ct` - Output cipher text (an already allocated array of CRYPTO_CIPHERTEXTBYTES bytes).
58/// * `ss` - Output shared secret (an already allocated array of CRYPTO_BYTES bytes).
59/// * `pk` - Input public key (an already allocated array of CRYPTO_PUBLICKEYBYTES bytes).
60/// * `_rng` - Random number generator implementing RngCore + CryptoRng.
61/// * `_seed` - Optional seed for random number generation.
62///
63/// # Errors
64///
65/// Returns a `KyberLibError` on failure.
66pub fn encrypt_message<R>(
67    ct: &mut [u8],
68    ss: &mut [u8],
69    pk: &[u8],
70    _rng: &mut R,
71    _seed: Option<&[u8]>,
72) -> Result<(), KyberLibError>
73where
74    R: RngCore + CryptoRng,
75{
76    if !coefficients_reduced(&pk[..KYBER_POLYVEC_BYTES]) {
77        return Err(KyberLibError::InvalidKey);
78    }
79    let mut kr = [0u8; 2 * KYBER_SYM_BYTES];
80    let mut buf = [0u8; 2 * KYBER_SYM_BYTES];
81    let mut randbuf = [0u8; 2 * KYBER_SYM_BYTES];
82
83    // Deterministic randbuf for Known Answer Tests (KATs)
84    if let Some(s) = _seed {
85        randbuf[..KYBER_SYM_BYTES].copy_from_slice(s);
86    } else {
87        randombytes(&mut randbuf, KYBER_SYM_BYTES, _rng)?;
88    }
89
90    // FIPS 203 §6.2 — `m` flows directly into `G(m || H(ek))`.
91    // Kyber Round 3 first hashed `m' = H(m)` and then used `m'` in
92    // place of `m`. NIST removed that step in the final standard.
93    buf[..KYBER_SYM_BYTES].copy_from_slice(&randbuf[..KYBER_SYM_BYTES]);
94
95    // Multitarget countermeasure for coins + contributory KEM
96    hash_h(&mut buf[KYBER_SYM_BYTES..], pk, KYBER_PUBLIC_KEY_BYTES);
97    hash_g(&mut kr, &buf, 2 * KYBER_SYM_BYTES);
98
99    // Coins are in kr[KYBER_SYM_BYTES..]
100    indcpa_enc(ct, &buf, pk, &kr[KYBER_SYM_BYTES..]);
101
102    // FIPS 203 §6.2 — the shared secret `K` is the first half of `G`'s
103    // output directly. Kyber Round 3 ran a final KDF over `K_bar || H(c)`;
104    // that step was removed in the final standard.
105    ss[..KYBER_SHARED_SECRET_BYTES]
106        .copy_from_slice(&kr[..KYBER_SHARED_SECRET_BYTES]);
107
108    Ok(())
109}
110
111/// Generates a shared secret for a given cipher text and private key.
112///
113/// # Arguments
114///
115/// * `ss` - Output shared secret (an already allocated array of CRYPTO_BYTES bytes).
116/// * `ct` - Input cipher text (an already allocated array of CRYPTO_CIPHERTEXTBYTES bytes).
117/// * `sk` - Input private key (an already allocated array of CRYPTO_SECRETKEYBYTES bytes).
118///
119/// On failure, `ss` will contain a pseudo-random value.
120pub fn decrypt_message(ss: &mut [u8], ct: &[u8], sk: &[u8]) {
121    let mut buf = [0u8; 2 * KYBER_SYM_BYTES];
122    let mut kr = [0u8; 2 * KYBER_SYM_BYTES];
123    let mut cmp = [0u8; KYBER_CIPHERTEXT_BYTES];
124    let mut pk = [0u8; KYBER_INDCPA_PUBLIC_KEY_BYTES];
125
126    pk.copy_from_slice(
127        &sk[KYBER_INDCPA_SECRET_KEY_BYTES..]
128            [..KYBER_INDCPA_PUBLIC_KEY_BYTES],
129    );
130
131    indcpa_dec(&mut buf, ct, sk);
132
133    // Multitarget countermeasure for coins + contributory KEM
134    const START: usize = KYBER_SECRET_KEY_BYTES - 2 * KYBER_SYM_BYTES;
135    const END: usize = KYBER_SECRET_KEY_BYTES - KYBER_SYM_BYTES;
136    buf[KYBER_SYM_BYTES..].copy_from_slice(&sk[START..END]);
137    hash_g(&mut kr, &buf, 2 * KYBER_SYM_BYTES);
138
139    // Coins are in kr[KYBER_SYM_BYTES..]
140    indcpa_enc(&mut cmp, &buf, &pk, &kr[KYBER_SYM_BYTES..]);
141    let fail = verify(ct, &cmp, KYBER_CIPHERTEXT_BYTES);
142
143    // FIPS 203 §6.3 — implicit rejection.
144    //   Success path: K = K' = kr[..32] (from `G(m' || h)`).
145    //   Failure path: K = J(z || c) = SHAKE256(z || c, 32).
146    // Kyber Round 3 used `KDF(K_bar || H(c))` on success and
147    // `KDF(z || H(c))` on failure. The final standard replaced the
148    // post-KDF entirely and switched the rejection input from
149    // `z || H(c)` to `z || c`.
150    let mut k_reject_input =
151        [0u8; KYBER_SYM_BYTES + KYBER_CIPHERTEXT_BYTES];
152    k_reject_input[..KYBER_SYM_BYTES].copy_from_slice(&sk[END..]);
153    // `ct` may be a slice into a longer buffer (kex.rs concatenates
154    // additional payload after the KEM ciphertext); only the first
155    // `KYBER_CIPHERTEXT_BYTES` are the ciphertext proper.
156    k_reject_input[KYBER_SYM_BYTES..]
157        .copy_from_slice(&ct[..KYBER_CIPHERTEXT_BYTES]);
158    let mut k_reject = [0u8; KYBER_SHARED_SECRET_BYTES];
159    kdf(
160        &mut k_reject,
161        &k_reject_input,
162        KYBER_SYM_BYTES + KYBER_CIPHERTEXT_BYTES,
163    );
164
165    ss[..KYBER_SHARED_SECRET_BYTES]
166        .copy_from_slice(&kr[..KYBER_SHARED_SECRET_BYTES]);
167    cmov(ss, &k_reject, KYBER_SHARED_SECRET_BYTES, fail);
168}
169
170// =============================================================================
171// Generic ports over MlKemParams (#130b — KEM layer with FO transform)
172// =============================================================================
173
174use crate::indcpa::{
175    indcpa_dec_generic, indcpa_enc_generic, indcpa_keypair_generic,
176};
177use crate::poly::poly_compressed_len;
178use crate::polyvec::polyvec_compressed_len;
179
180/// Public encapsulation-key byte length: `polyvec_bytes_len + 32`.
181#[allow(dead_code)]
182pub(crate) const fn ek_bytes<P: crate::paramsets::MlKemParams>() -> usize
183{
184    P::K * KYBER_POLY_BYTES + KYBER_SYM_BYTES
185}
186
187/// Ciphertext byte length: `polyvec_compressed_len + poly_compressed_len`.
188#[allow(dead_code)]
189pub(crate) const fn ct_bytes<P: crate::paramsets::MlKemParams>() -> usize
190{
191    polyvec_compressed_len::<P>() + poly_compressed_len::<P>()
192}
193
194/// Secret decapsulation-key byte length:
195///   indcpa_sk (polyvec_bytes) ‖ ek (polyvec_bytes + 32) ‖ H(ek) (32) ‖ z (32)
196/// = 2*polyvec_bytes + 96
197#[allow(dead_code)]
198pub(crate) const fn dk_bytes<P: crate::paramsets::MlKemParams>() -> usize
199{
200    2 * P::K * KYBER_POLY_BYTES + 96
201}
202
203/// Generic port of [`generate_key_pair`].
204#[allow(dead_code)]
205pub(crate) fn kem_keypair_generic<P, R>(
206    pk: &mut [u8],
207    sk: &mut [u8],
208    rng: &mut R,
209    seed: Option<(&[u8], &[u8])>,
210) -> Result<(), KyberLibError>
211where
212    P: crate::paramsets::MlKemParams,
213    R: RngCore + CryptoRng,
214{
215    let indcpa_pk_bytes = ek_bytes::<P>();
216    let indcpa_sk_bytes = P::K * KYBER_POLY_BYTES;
217    let pk_start = dk_bytes::<P>() - 2 * KYBER_SYM_BYTES;
218    let sk_start = dk_bytes::<P>() - KYBER_SYM_BYTES;
219    let pk_end = indcpa_sk_bytes + indcpa_pk_bytes;
220
221    indcpa_keypair_generic::<P, R>(pk, sk, seed, rng)?;
222
223    sk[indcpa_sk_bytes..pk_end].copy_from_slice(&pk[..indcpa_pk_bytes]);
224    hash_h(&mut sk[pk_start..sk_start], pk, indcpa_pk_bytes);
225
226    if let Some(s) = seed {
227        sk[sk_start..].copy_from_slice(s.1);
228    } else {
229        randombytes(&mut sk[sk_start..], KYBER_SYM_BYTES, rng)?;
230    }
231
232    Ok(())
233}
234
235/// Generic port of [`encrypt_message`].
236#[allow(dead_code)]
237pub(crate) fn kem_enc_generic<P, R>(
238    ct: &mut [u8],
239    ss: &mut [u8],
240    pk: &[u8],
241    rng: &mut R,
242    seed: Option<&[u8]>,
243) -> Result<(), KyberLibError>
244where
245    P: crate::paramsets::MlKemParams,
246    R: RngCore + CryptoRng,
247{
248    if !coefficients_reduced(
249        &pk[..crate::polyvec::polyvec_bytes_len::<P>()],
250    ) {
251        return Err(KyberLibError::InvalidKey);
252    }
253    let mut kr = [0u8; 2 * KYBER_SYM_BYTES];
254    let mut buf = [0u8; 2 * KYBER_SYM_BYTES];
255    let mut randbuf = [0u8; 2 * KYBER_SYM_BYTES];
256
257    if let Some(s) = seed {
258        randbuf[..KYBER_SYM_BYTES].copy_from_slice(s);
259    } else {
260        randombytes(&mut randbuf, KYBER_SYM_BYTES, rng)?;
261    }
262
263    buf[..KYBER_SYM_BYTES].copy_from_slice(&randbuf[..KYBER_SYM_BYTES]);
264    hash_h(&mut buf[KYBER_SYM_BYTES..], pk, ek_bytes::<P>());
265    hash_g(&mut kr, &buf, 2 * KYBER_SYM_BYTES);
266
267    indcpa_enc_generic::<P>(ct, &buf, pk, &kr[KYBER_SYM_BYTES..]);
268
269    ss[..KYBER_SHARED_SECRET_BYTES]
270        .copy_from_slice(&kr[..KYBER_SHARED_SECRET_BYTES]);
271    Ok(())
272}
273
274/// Generic port of [`decrypt_message`]. Implements FIPS 203 §6.3
275/// implicit rejection — never panics, never branches on validity.
276#[allow(dead_code)]
277pub(crate) fn kem_dec_generic<P: crate::paramsets::MlKemParams>(
278    ss: &mut [u8],
279    ct: &[u8],
280    sk: &[u8],
281) {
282    debug_assert!(P::K <= 4);
283
284    let mut buf = [0u8; 2 * KYBER_SYM_BYTES];
285    let mut kr = [0u8; 2 * KYBER_SYM_BYTES];
286    // MAX_K-sized comparison buffer (~1.5 KB worst-case for ML-KEM-1024).
287    let mut cmp = [0u8; 32 * (4 * 11 + 5)]; // = 1568 (kyber1024 max)
288
289    let indcpa_pk_bytes = ek_bytes::<P>();
290    let indcpa_sk_bytes = P::K * KYBER_POLY_BYTES;
291    let dk_len = dk_bytes::<P>();
292    let ct_len = ct_bytes::<P>();
293
294    let mut pk = [0u8; 1568]; // MAX ek bytes (kyber1024)
295    pk[..indcpa_pk_bytes].copy_from_slice(
296        &sk[indcpa_sk_bytes..indcpa_sk_bytes + indcpa_pk_bytes],
297    );
298
299    indcpa_dec_generic::<P>(&mut buf, ct, sk);
300
301    let h_start = dk_len - 2 * KYBER_SYM_BYTES;
302    let h_end = dk_len - KYBER_SYM_BYTES;
303    buf[KYBER_SYM_BYTES..].copy_from_slice(&sk[h_start..h_end]);
304    hash_g(&mut kr, &buf, 2 * KYBER_SYM_BYTES);
305
306    indcpa_enc_generic::<P>(
307        &mut cmp[..ct_len],
308        &buf,
309        &pk[..indcpa_pk_bytes],
310        &kr[KYBER_SYM_BYTES..],
311    );
312    let fail = verify(&ct[..ct_len], &cmp[..ct_len], ct_len);
313
314    // Implicit rejection: K_reject = SHAKE256(z ‖ c, 32).
315    let mut k_reject_input = [0u8; KYBER_SYM_BYTES + 1568]; // max ct
316    k_reject_input[..KYBER_SYM_BYTES].copy_from_slice(&sk[h_end..]);
317    k_reject_input[KYBER_SYM_BYTES..KYBER_SYM_BYTES + ct_len]
318        .copy_from_slice(&ct[..ct_len]);
319    let mut k_reject = [0u8; KYBER_SHARED_SECRET_BYTES];
320    kdf(
321        &mut k_reject,
322        &k_reject_input[..KYBER_SYM_BYTES + ct_len],
323        KYBER_SYM_BYTES + ct_len,
324    );
325
326    ss[..KYBER_SHARED_SECRET_BYTES]
327        .copy_from_slice(&kr[..KYBER_SHARED_SECRET_BYTES]);
328    cmov(ss, &k_reject, KYBER_SHARED_SECRET_BYTES, fail);
329}
330
331#[cfg(test)]
332#[path = "kem_tests.rs"]
333mod tests;