xref: /freebsd/crypto/openssl/include/crypto/ml_kem.h (revision e7be843b4a162e68651d3911f0357ed464915629)
1 /*
2  * Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.
3  *
4  * Licensed under the Apache License 2.0 (the "License").  You may not use
5  * this file except in compliance with the License.  You can obtain a copy
6  * in the file LICENSE in the source distribution or at
7  * https://www.openssl.org/source/license.html
8  */
9 
10 #ifndef OPENSSL_HEADER_ML_KEM_H
11 # define OPENSSL_HEADER_ML_KEM_H
12 # pragma once
13 
14 # include <openssl/e_os2.h>
15 # include <openssl/bio.h>
16 # include <openssl/core_dispatch.h>
17 # include <crypto/evp.h>
18 
19 # define ML_KEM_DEGREE 256
20 /*
21  * With (q-1) an odd multiple of 256, and 17 ("zeta") as a primitive 256th root
22  * of unity, the polynomial (X^256+1) splits in Z_q[X] into 128 irreducible
23  * quadratic factors of the form (X^2 - zeta^(2i + 1)).  This is used to
24  * implement efficient multiplication in the ring R_q via the "NTT" transform.
25  */
26 # define ML_KEM_PRIME          (ML_KEM_DEGREE * 13 + 1)
27 
28 /*
29  * Various ML-KEM primitives need random input, 32-bytes at a time.  Key
30  * generation consumes two random values (d, z) with "d" plus the rank (domain
31  * separation) further expanded to two derived seeds "rho" and "sigma", with
32  * "rho" used to generate the public matrix "A", and sigma to generate the
33  * private vector "s" and error vector "e".
34  *
35  * Encapsulation also consumes one random value m, that is 32-bytes long.  The
36  * resulting shared secret "K" (also 32 bytes) and an internal random value "r"
37  * are derived from "m" concatenated with a digest of the received public key.
38  * Use of the public key hash means that the derived shared secret is
39  * "contributary", it uses randomness from both parties.
40  *
41  * The seed "rho" is appended to the public key and allows the recipient of the
42  * public key to re-compute the matrix "A" when performing encapsulation.
43  *
44  * Note that the matrix "m" we store in the public key is the transpose of the
45  * "A" matrix from FIPS 203!
46  */
47 # define ML_KEM_RANDOM_BYTES    32 /* rho, sigma, ... */
48 # define ML_KEM_SEED_BYTES      (ML_KEM_RANDOM_BYTES * 2) /* Keygen (d, z) */
49 
50 # define ML_KEM_PKHASH_BYTES        32 /* Salts the shared-secret */
51 # define ML_KEM_SHARED_SECRET_BYTES 32
52 
53 # if ML_KEM_PKHASH_BYTES != ML_KEM_RANDOM_BYTES
54 #  error "unexpected ML-KEM public key hash size"
55 # endif
56 
57 /*-
58  * The ML-KEM specification can be found in
59  * https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf
60  *
61  * Section 8, Table 2, lists the parameters for the three variants:
62  *
63  *         Variant     n     q  k  eta1  eta2  du   dv  secbits
64  *      ----------   ---  ----  -  ----  ----  --   --  -------
65  *      ML-KEM-512   256  3329  2     3     2  10    4      128
66  *      ML-KEM-768   256  3329  3     2     2  10    4      192
67  *      ML-KEM-1024  256  3329  4     2     2  11    5      256
68  *
69  * where:
70  *
71  * - "n" (ML_KEM_DEGREE above) is the fixed degree of the quotient polynomial
72  *    in the ring: "R_q" = Z[X]/(X^n + 1).
73  * - "q" (ML_KEM_PRIME above) is the fixed prime (256 * 13 + 1 = 3329) used in
74  *   all ML-KEM variants.
75  * - "k" is the row rank of the square matrix "A", with entries in R_q, that
76  *   defines the "noisy" linear equations: t = A * s + e.  Also the rank of
77  *   of the associated vectors.
78  * - "eta1" determines the amplitude of "s" and "e" vectors in key generation
79  *   and the "y" vector in ML-KEM encapsulation (K-PKE encryption).
80  * - "eta2" determines the amplitude of "e1" and "e2" noise terms in ML-KEM
81  *   encapsulation (K-PKE encryption).
82  * - "du" determines how many bits of each coefficient are retained in the
83  *   compressed form of the "u" vector in the encapsulation ciphertext.
84  * - "dv" determines how many bits of each coefficient are retained in the
85  *   compressed form of the "v" value in encapsulation ciphertext
86  * - "secbits" is required security strength of the RNG for the random inputs.
87  */
88 
89 /*
90  * Variant-specific constants and structures
91  * -----------------------------------------
92  */
93 # define EVP_PKEY_ML_KEM_512    NID_ML_KEM_512
94 # define ML_KEM_512_BITS        512
95 # define ML_KEM_512_RANK        2
96 # define ML_KEM_512_ETA1        3
97 # define ML_KEM_512_ETA2        2
98 # define ML_KEM_512_DU          10
99 # define ML_KEM_512_DV          4
100 # define ML_KEM_512_SECBITS     128
101 
102 # define EVP_PKEY_ML_KEM_768    NID_ML_KEM_768
103 # define ML_KEM_768_BITS        768
104 # define ML_KEM_768_RANK        3
105 # define ML_KEM_768_ETA1        2
106 # define ML_KEM_768_ETA2        2
107 # define ML_KEM_768_DU          10
108 # define ML_KEM_768_DV          4
109 # define ML_KEM_768_SECBITS     192
110 
111 # define EVP_PKEY_ML_KEM_1024   NID_ML_KEM_1024
112 # define ML_KEM_1024_BITS       1024
113 # define ML_KEM_1024_RANK       4
114 # define ML_KEM_1024_ETA1       2
115 # define ML_KEM_1024_ETA2       2
116 # define ML_KEM_1024_DU         11
117 # define ML_KEM_1024_DV         5
118 # define ML_KEM_1024_SECBITS    256
119 
120 # define ML_KEM_KEY_RANDOM_PCT  (1 << 0)
121 # define ML_KEM_KEY_FIXED_PCT   (1 << 1)
122 # define ML_KEM_KEY_PREFER_SEED (1 << 2)
123 # define ML_KEM_KEY_RETAIN_SEED (1 << 3)
124 /* Mask to check whether PCT on import is enabled */
125 # define ML_KEM_KEY_PCT_TYPE \
126     (ML_KEM_KEY_RANDOM_PCT | ML_KEM_KEY_FIXED_PCT)
127 /* Default provider flags */
128 # define ML_KEM_KEY_PROV_FLAGS_DEFAULT \
129     (ML_KEM_KEY_RANDOM_PCT | ML_KEM_KEY_PREFER_SEED | ML_KEM_KEY_RETAIN_SEED)
130 
131 /*
132  * External variant-specific API
133  * -----------------------------
134  */
135 
136 typedef struct {
137     const char *algorithm_name;
138     size_t prvkey_bytes;
139     size_t prvalloc;
140     size_t pubkey_bytes;
141     size_t puballoc;
142     size_t ctext_bytes;
143     size_t vector_bytes;
144     size_t u_vector_bytes;
145     int evp_type;
146     int bits;
147     int rank;
148     int du;
149     int dv;
150     int secbits;
151 } ML_KEM_VINFO;
152 
153 /* Retrive global variant-specific parameters */
154 const ML_KEM_VINFO *ossl_ml_kem_get_vinfo(int evp_type);
155 
156 /* Known as ML_KEM_KEY via crypto/types.h */
157 typedef struct ossl_ml_kem_key_st {
158     /* Variant metadata, for one of ML-KEM-{512,768,1024} */
159     const ML_KEM_VINFO *vinfo;
160 
161     /*
162      * Library context, initially used to fetch the SHA3 MDs, and later for
163      * random number generation.
164      */
165     OSSL_LIB_CTX *libctx;
166 
167     /* Pre-fetched SHA3 */
168     EVP_MD *shake128_md;
169     EVP_MD *shake256_md;
170     EVP_MD *sha3_256_md;
171     EVP_MD *sha3_512_md;
172 
173     /*
174      * Pointers into variable size storage, initially all NULL. Appropriate
175      * storage is allocated once a public or private key is specified, at
176      * which point the key becomes immutable.
177      */
178     uint8_t *rho;                           /* Public matrix seed */
179     uint8_t *pkhash;                        /* Public key hash */
180     struct ossl_ml_kem_scalar_st *t;        /* Public key vector */
181     struct ossl_ml_kem_scalar_st *m;        /* Pre-computed pubkey matrix */
182     struct ossl_ml_kem_scalar_st *s;        /* Private key secret vector */
183     uint8_t *z;                             /* Private key FO failure secret */
184     uint8_t *d;                             /* Private key seed */
185     int prov_flags;                         /* prefer/retain seed and PCT flags */
186 
187     /*
188      * Fixed-size built-in buffer, which holds the |rho| and the public key
189      * |pkhash| in that order, once we have expanded key material.
190      * With seed-only keys, that are not yet expanded, this instead holds the
191      * |z| and |d| components in that order.
192      */
193     uint8_t seedbuf[64];                    /* |rho| + |pkhash| / |z| + |d| */
194     uint8_t *encoded_dk;                    /* Unparsed P8 private key */
195 } ML_KEM_KEY;
196 
197 /* The public key is always present, when the private is */
198 # define ossl_ml_kem_key_vinfo(key)     ((key)->vinfo)
199 # define ossl_ml_kem_have_pubkey(key)   ((key)->t != NULL)
200 # define ossl_ml_kem_have_prvkey(key)   ((key)->s != NULL)
201 # define ossl_ml_kem_have_seed(key)     ((key)->d != NULL)
202 # define ossl_ml_kem_have_dkenc(key)    ((key)->encoded_dk != NULL)
203 # define ossl_ml_kem_decoded_key(key)   ((key)->encoded_dk != NULL \
204                                          || ((key)->s == NULL && (key)->d != NULL))
205 
206 /*
207  * ----- ML-KEM key lifecycle
208  */
209 
210 /*
211  * Allocate a "bare" key for given ML-KEM variant. Initially without any public
212  * or private key material.
213  */
214 ML_KEM_KEY *ossl_ml_kem_key_new(OSSL_LIB_CTX *libctx, const char *properties,
215                                 int evp_type);
216 /* Reset a key clearing all public and private key material */
217 void ossl_ml_kem_key_reset(ML_KEM_KEY *key);
218 /* Deallocate the key */
219 void ossl_ml_kem_key_free(ML_KEM_KEY *key);
220 /*
221  * Duplicate a key, optionally including some key material, per the
222  * |selection|, see <openssl/core_dispatch.h>.
223  */
224 ML_KEM_KEY *ossl_ml_kem_key_dup(const ML_KEM_KEY *key, int selection);
225 
226 /*
227  * ----- Import or generate key material.
228  */
229 
230 /*
231  * Functions that augment "bare ML-KEM keys" with key material deserialised
232  * from an input buffer. It is an error for any key material to already be
233  * present.
234  *
235  * Return 1 on success, 0 otherwise.
236  */
237 __owur
238 int ossl_ml_kem_parse_public_key(const uint8_t *in, size_t len,
239                                  ML_KEM_KEY *key);
240 __owur
241 int ossl_ml_kem_parse_private_key(const uint8_t *in, size_t len,
242                                   ML_KEM_KEY *key);
243 ML_KEM_KEY *ossl_ml_kem_set_seed(const uint8_t *seed, size_t seedlen,
244                                  ML_KEM_KEY *key);
245 __owur
246 int ossl_ml_kem_genkey(uint8_t *pubenc, size_t publen, ML_KEM_KEY *key);
247 
248 /*
249  * Perform an ML-KEM operation with a given ML-KEM key.  The key can generally
250  * be either a private or public key, with the exception of encoding a private
251  * key or performing KEM decapsulation.
252  */
253 __owur
254 int ossl_ml_kem_encode_public_key(uint8_t *out, size_t len,
255                                   const ML_KEM_KEY *key);
256 __owur
257 int ossl_ml_kem_encode_private_key(uint8_t *out, size_t len,
258                                    const ML_KEM_KEY *key);
259 __owur
260 int ossl_ml_kem_encode_seed(uint8_t *out, size_t len,
261                             const ML_KEM_KEY *key);
262 
263 __owur
264 int ossl_ml_kem_encap_seed(uint8_t *ctext, size_t clen,
265                            uint8_t *shared_secret, size_t slen,
266                            const uint8_t *entropy, size_t elen,
267                            const ML_KEM_KEY *key);
268 __owur
269 int ossl_ml_kem_encap_rand(uint8_t *ctext, size_t clen,
270                            uint8_t *shared_secret, size_t slen,
271                            const ML_KEM_KEY *key);
272 __owur
273 int ossl_ml_kem_decap(uint8_t *shared_secret, size_t slen,
274                       const uint8_t *ctext, size_t clen,
275                       const ML_KEM_KEY *key);
276 
277 /* Compare the public key hashes of two keys */
278 __owur
279 int ossl_ml_kem_pubkey_cmp(const ML_KEM_KEY *key1, const ML_KEM_KEY *key2);
280 
281 #endif  /* OPENSSL_HEADER_ML_KEM_H */
282