1 /*
2 * Copyright 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 #include <string.h>
11 #include <openssl/byteorder.h>
12 #include <openssl/proverr.h>
13 #include <openssl/x509.h>
14 #include <openssl/core_names.h>
15 #include "internal/encoder.h"
16 #include "prov/ml_kem.h"
17 #include "ml_kem_codecs.h"
18
19 /* Tables describing supported ASN.1 input/output formats. */
20
21 /*-
22 * ML-KEM-512:
23 * Public key bytes: 800 (0x0320)
24 * Private key bytes: 1632 (0x0660)
25 */
26 static const ML_COMMON_SPKI_FMT ml_kem_512_spkifmt = {
27 { 0x30, 0x82, 0x03, 0x32, 0x30, 0x0b, 0x06, 0x09, 0x60, 0x86, 0x48,
28 0x01, 0x65, 0x03, 0x04, 0x04, 0x01, 0x03, 0x82, 0x03, 0x21, 0x00, }
29 };
30 static const ML_COMMON_PKCS8_FMT ml_kem_512_p8fmt[NUM_PKCS8_FORMATS] = {
31 { "seed-priv", 0x06aa, 0, 0x308206a6, 0x0440, 6, 0x40, 0x04820660, 0x4a, 0x0660, 0, 0 },
32 { "priv-only", 0x0664, 0, 0x04820660, 0, 0, 0, 0, 0x04, 0x0660, 0, 0 },
33 { "oqskeypair", 0x0984, 0, 0x04820980, 0, 0, 0, 0, 0x04, 0x0660, 0x0664, 0x0320 },
34 { "seed-only", 0x0042, 2, 0x8040, 0, 2, 0x40, 0, 0, 0, 0, 0 },
35 { "bare-priv", 0x0660, 4, 0, 0, 0, 0, 0, 0, 0x0660, 0, 0 },
36 { "bare-seed", 0x0040, 4, 0, 0, 0, 0x40, 0, 0, 0, 0, 0 },
37 };
38
39 /*-
40 * ML-KEM-768:
41 * Public key bytes: 1184 (0x04a0)
42 * Private key bytes: 2400 (0x0960)
43 */
44 static const ML_COMMON_SPKI_FMT ml_kem_768_spkifmt = {
45 { 0x30, 0x82, 0x04, 0xb2, 0x30, 0x0b, 0x06, 0x09, 0x60, 0x86, 0x48,
46 0x01, 0x65, 0x03, 0x04, 0x04, 0x02, 0x03, 0x82, 0x04, 0xa1, 0x00, }
47 };
48 static const ML_COMMON_PKCS8_FMT ml_kem_768_p8fmt[NUM_PKCS8_FORMATS] = {
49 { "seed-priv", 0x09aa, 0, 0x308209a6, 0x0440, 6, 0x40, 0x04820960, 0x4a, 0x0960, 0, 0, },
50 { "priv-only", 0x0964, 0, 0x04820960, 0, 0, 0, 0, 0x04, 0x0960, 0, 0, },
51 { "oqskeypair", 0x0e04, 0, 0x04820e00, 0, 0, 0, 0, 0x04, 0x0960, 0x0964, 0x04a0 },
52 { "seed-only", 0x0042, 2, 0x8040, 0, 2, 0x40, 0, 0, 0, 0, 0, },
53 { "bare-priv", 0x0960, 4, 0, 0, 0, 0, 0, 0, 0x0960, 0, 0, },
54 { "bare-seed", 0x0040, 4, 0, 0, 0, 0x40, 0, 0, 0, 0, 0, },
55 };
56
57 /*-
58 * ML-KEM-1024:
59 * Private key bytes: 3168 (0x0c60)
60 * Public key bytes: 1568 (0x0620)
61 */
62 static const ML_COMMON_SPKI_FMT ml_kem_1024_spkifmt = {
63 { 0x30, 0x82, 0x06, 0x32, 0x30, 0x0b, 0x06, 0x09, 0x60, 0x86, 0x48,
64 0x01, 0x65, 0x03, 0x04, 0x04, 0x03, 0x03, 0x82, 0x06, 0x21, 0x00, }
65 };
66 static const ML_COMMON_PKCS8_FMT ml_kem_1024_p8fmt[NUM_PKCS8_FORMATS] = {
67 { "seed-priv", 0x0caa, 0, 0x30820ca6, 0x0440, 6, 0x40, 0x04820c60, 0x4a, 0x0c60, 0, 0 },
68 { "priv-only", 0x0c64, 0, 0x04820c60, 0, 0, 0, 0, 0x04, 0x0c60, 0, 0 },
69 { "oqskeypair", 0x1284, 0, 0x04821280, 0, 0, 0, 0, 0x04, 0x0c60, 0x0c64, 0x0620 },
70 { "seed-only", 0x0042, 2, 0x8040, 0, 2, 0x40, 0, 0, 0, 0, 0 },
71 { "bare-priv", 0x0c60, 4, 0, 0, 0, 0, 0, 0, 0x0c60, 0, 0 },
72 { "bare-seed", 0x0040, 4, 0, 0, 0, 0x40, 0, 0, 0, 0, 0 },
73 };
74
75 /* Indices of slots in the `codecs` table below */
76 #define ML_KEM_512_CODEC 0
77 #define ML_KEM_768_CODEC 1
78 #define ML_KEM_1024_CODEC 2
79
80 /*
81 * Per-variant fixed parameters
82 */
83 static const ML_COMMON_CODEC codecs[3] = {
84 { &ml_kem_512_spkifmt, ml_kem_512_p8fmt },
85 { &ml_kem_768_spkifmt, ml_kem_768_p8fmt },
86 { &ml_kem_1024_spkifmt, ml_kem_1024_p8fmt }
87 };
88
89 /* Retrieve the parameters of one of the ML-KEM variants */
ml_kem_get_codec(int evp_type)90 static const ML_COMMON_CODEC *ml_kem_get_codec(int evp_type)
91 {
92 switch (evp_type) {
93 case EVP_PKEY_ML_KEM_512:
94 return &codecs[ML_KEM_512_CODEC];
95 case EVP_PKEY_ML_KEM_768:
96 return &codecs[ML_KEM_768_CODEC];
97 case EVP_PKEY_ML_KEM_1024:
98 return &codecs[ML_KEM_1024_CODEC];
99 }
100 return NULL;
101 }
102
103 ML_KEM_KEY *
ossl_ml_kem_d2i_PUBKEY(const uint8_t * pubenc,int publen,int evp_type,PROV_CTX * provctx,const char * propq)104 ossl_ml_kem_d2i_PUBKEY(const uint8_t *pubenc, int publen, int evp_type,
105 PROV_CTX *provctx, const char *propq)
106 {
107 OSSL_LIB_CTX *libctx = PROV_LIBCTX_OF(provctx);
108 const ML_KEM_VINFO *v;
109 const ML_COMMON_CODEC *codec;
110 const ML_COMMON_SPKI_FMT *vspki;
111 ML_KEM_KEY *ret;
112
113 if ((v = ossl_ml_kem_get_vinfo(evp_type)) == NULL
114 || (codec = ml_kem_get_codec(evp_type)) == NULL)
115 return NULL;
116 vspki = codec->spkifmt;
117 if (publen != ML_COMMON_SPKI_OVERHEAD + (ossl_ssize_t) v->pubkey_bytes
118 || memcmp(pubenc, vspki->asn1_prefix, ML_COMMON_SPKI_OVERHEAD) != 0)
119 return NULL;
120 publen -= ML_COMMON_SPKI_OVERHEAD;
121 pubenc += ML_COMMON_SPKI_OVERHEAD;
122
123 if ((ret = ossl_ml_kem_key_new(libctx, propq, evp_type)) == NULL)
124 return NULL;
125
126 if (!ossl_ml_kem_parse_public_key(pubenc, (size_t) publen, ret)) {
127 ERR_raise_data(ERR_LIB_PROV, PROV_R_BAD_ENCODING,
128 "errror parsing %s public key from input SPKI",
129 v->algorithm_name);
130 ossl_ml_kem_key_free(ret);
131 return NULL;
132 }
133
134 return ret;
135 }
136
137 ML_KEM_KEY *
ossl_ml_kem_d2i_PKCS8(const uint8_t * prvenc,int prvlen,int evp_type,PROV_CTX * provctx,const char * propq)138 ossl_ml_kem_d2i_PKCS8(const uint8_t *prvenc, int prvlen,
139 int evp_type, PROV_CTX *provctx,
140 const char *propq)
141 {
142 const ML_KEM_VINFO *v;
143 const ML_COMMON_CODEC *codec;
144 ML_COMMON_PKCS8_FMT_PREF *fmt_slots = NULL, *slot;
145 const ML_COMMON_PKCS8_FMT *p8fmt;
146 ML_KEM_KEY *key = NULL, *ret = NULL;
147 PKCS8_PRIV_KEY_INFO *p8inf = NULL;
148 const uint8_t *buf, *pos;
149 const X509_ALGOR *alg = NULL;
150 const char *formats;
151 int len, ptype;
152 uint32_t magic;
153 uint16_t seed_magic;
154
155 /* Which ML-KEM variant? */
156 if ((v = ossl_ml_kem_get_vinfo(evp_type)) == NULL
157 || (codec = ml_kem_get_codec(evp_type)) == NULL)
158 return 0;
159
160 /* Extract the key OID and any parameters. */
161 if ((p8inf = d2i_PKCS8_PRIV_KEY_INFO(NULL, &prvenc, prvlen)) == NULL)
162 return 0;
163 /* Shortest prefix is 4 bytes: seq tag/len + octet string tag/len */
164 if (!PKCS8_pkey_get0(NULL, &buf, &len, &alg, p8inf))
165 goto end;
166 /* Bail out early if this is some other key type. */
167 if (OBJ_obj2nid(alg->algorithm) != evp_type)
168 goto end;
169
170 /* Get the list of enabled decoders. Their order is not important here. */
171 formats = ossl_prov_ctx_get_param(
172 provctx, OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS, NULL);
173 fmt_slots = ossl_ml_common_pkcs8_fmt_order(v->algorithm_name, codec->p8fmt,
174 "input", formats);
175 if (fmt_slots == NULL)
176 goto end;
177
178 /* Parameters must be absent. */
179 X509_ALGOR_get0(NULL, &ptype, NULL, alg);
180 if (ptype != V_ASN1_UNDEF) {
181 ERR_raise_data(ERR_LIB_PROV, PROV_R_UNEXPECTED_KEY_PARAMETERS,
182 "unexpected parameters with a PKCS#8 %s private key",
183 v->algorithm_name);
184 goto end;
185 }
186 if ((ossl_ssize_t)len < (ossl_ssize_t)sizeof(magic))
187 goto end;
188
189 /* Find the matching p8 info slot, that also has the expected length. */
190 pos = OPENSSL_load_u32_be(&magic, buf);
191 for (slot = fmt_slots; (p8fmt = slot->fmt) != NULL; ++slot) {
192 if (len != (ossl_ssize_t)p8fmt->p8_bytes)
193 continue;
194 if (p8fmt->p8_shift == sizeof(magic)
195 || (magic >> (p8fmt->p8_shift * 8)) == p8fmt->p8_magic) {
196 pos -= p8fmt->p8_shift;
197 break;
198 }
199 }
200 if (p8fmt == NULL
201 || (p8fmt->seed_length > 0 && p8fmt->seed_length != ML_KEM_SEED_BYTES)
202 || (p8fmt->priv_length > 0 && p8fmt->priv_length != v->prvkey_bytes)
203 || (p8fmt->pub_length > 0 && p8fmt->pub_length != v->pubkey_bytes)) {
204 ERR_raise_data(ERR_LIB_PROV, PROV_R_ML_KEM_NO_FORMAT,
205 "no matching enabled %s private key input formats",
206 v->algorithm_name);
207 goto end;
208 }
209
210 if (p8fmt->seed_length > 0) {
211 /* Check |seed| tag/len, if not subsumed by |magic|. */
212 if (pos + sizeof(uint16_t) == buf + p8fmt->seed_offset) {
213 pos = OPENSSL_load_u16_be(&seed_magic, pos);
214 if (seed_magic != p8fmt->seed_magic)
215 goto end;
216 } else if (pos != buf + p8fmt->seed_offset) {
217 goto end;
218 }
219 pos += ML_KEM_SEED_BYTES;
220 }
221 if (p8fmt->priv_length > 0) {
222 /* Check |priv| tag/len */
223 if (pos + sizeof(uint32_t) == buf + p8fmt->priv_offset) {
224 pos = OPENSSL_load_u32_be(&magic, pos);
225 if (magic != p8fmt->priv_magic)
226 goto end;
227 } else if (pos != buf + p8fmt->priv_offset) {
228 goto end;
229 }
230 pos += v->prvkey_bytes;
231 }
232 if (p8fmt->pub_length > 0) {
233 if (pos != buf + p8fmt->pub_offset)
234 goto end;
235 pos += v->pubkey_bytes;
236 }
237 if (pos != buf + len)
238 goto end;
239
240 /*
241 * Collect the seed and/or key into a "decoded" private key object,
242 * to be turned into a real key on provider "load" or "import".
243 */
244 if ((key = ossl_prov_ml_kem_new(provctx, propq, evp_type)) == NULL)
245 goto end;
246
247 if (p8fmt->seed_length > 0) {
248 if (!ossl_ml_kem_set_seed(buf + p8fmt->seed_offset,
249 ML_KEM_SEED_BYTES, key)) {
250 ERR_raise_data(ERR_LIB_OSSL_DECODER, ERR_R_INTERNAL_ERROR,
251 "error storing %s private key seed",
252 v->algorithm_name);
253 goto end;
254 }
255 }
256 if (p8fmt->priv_length > 0) {
257 if ((key->encoded_dk = OPENSSL_malloc(p8fmt->priv_length)) == NULL) {
258 ERR_raise_data(ERR_LIB_PROV, PROV_R_INVALID_KEY,
259 "error parsing %s private key",
260 v->algorithm_name);
261 goto end;
262 }
263 memcpy(key->encoded_dk, buf + p8fmt->priv_offset, p8fmt->priv_length);
264 }
265 /* Any OQS public key content is ignored */
266 ret = key;
267
268 end:
269 OPENSSL_free(fmt_slots);
270 PKCS8_PRIV_KEY_INFO_free(p8inf);
271 if (ret == NULL)
272 ossl_ml_kem_key_free(key);
273 return ret;
274 }
275
276 /* Same as ossl_ml_kem_encode_pubkey, but allocates the output buffer. */
ossl_ml_kem_i2d_pubkey(const ML_KEM_KEY * key,unsigned char ** out)277 int ossl_ml_kem_i2d_pubkey(const ML_KEM_KEY *key, unsigned char **out)
278 {
279 size_t publen;
280
281 if (!ossl_ml_kem_have_pubkey(key)) {
282 ERR_raise_data(ERR_LIB_PROV, PROV_R_NOT_A_PUBLIC_KEY,
283 "no %s public key data available",
284 key->vinfo->algorithm_name);
285 return 0;
286 }
287 publen = key->vinfo->pubkey_bytes;
288
289 if (out != NULL
290 && (*out = OPENSSL_malloc(publen)) == NULL)
291 return 0;
292 if (!ossl_ml_kem_encode_public_key(*out, publen, key)) {
293 ERR_raise_data(ERR_LIB_OSSL_ENCODER, ERR_R_INTERNAL_ERROR,
294 "error encoding %s public key",
295 key->vinfo->algorithm_name);
296 OPENSSL_free(*out);
297 return 0;
298 }
299
300 return (int)publen;
301 }
302
303 /* Allocate and encode PKCS#8 private key payload. */
ossl_ml_kem_i2d_prvkey(const ML_KEM_KEY * key,uint8_t ** out,PROV_CTX * provctx)304 int ossl_ml_kem_i2d_prvkey(const ML_KEM_KEY *key, uint8_t **out,
305 PROV_CTX *provctx)
306 {
307 const ML_KEM_VINFO *v = key->vinfo;
308 const ML_COMMON_CODEC *codec;
309 ML_COMMON_PKCS8_FMT_PREF *fmt_slots, *slot;
310 const ML_COMMON_PKCS8_FMT *p8fmt;
311 uint8_t *buf = NULL, *pos;
312 const char *formats;
313 int len = ML_KEM_SEED_BYTES;
314 int ret = 0;
315
316 /* Not ours to handle */
317 if ((codec = ml_kem_get_codec(v->evp_type)) == NULL)
318 return 0;
319
320 if (!ossl_ml_kem_have_prvkey(key)) {
321 ERR_raise_data(ERR_LIB_PROV, PROV_R_NOT_A_PRIVATE_KEY,
322 "no %s private key data available",
323 key->vinfo->algorithm_name);
324 return 0;
325 }
326
327 formats = ossl_prov_ctx_get_param(
328 provctx, OSSL_PKEY_PARAM_ML_KEM_OUTPUT_FORMATS, NULL);
329 fmt_slots = ossl_ml_common_pkcs8_fmt_order(v->algorithm_name, codec->p8fmt,
330 "output", formats);
331 if (fmt_slots == NULL)
332 return 0;
333
334 /* If we don't have a seed, skip seedful entries */
335 for (slot = fmt_slots; (p8fmt = slot->fmt) != NULL; ++slot)
336 if (ossl_ml_kem_have_seed(key) || p8fmt->seed_length == 0)
337 break;
338 /* No matching table entries, give up */
339 if (p8fmt == NULL
340 || (p8fmt->seed_length > 0 && p8fmt->seed_length != ML_KEM_SEED_BYTES)
341 || (p8fmt->priv_length > 0 && p8fmt->priv_length != v->prvkey_bytes)
342 || (p8fmt->pub_length > 0 && p8fmt->pub_length != v->pubkey_bytes)) {
343 ERR_raise_data(ERR_LIB_PROV, PROV_R_ML_KEM_NO_FORMAT,
344 "no matching enabled %s private key output formats",
345 v->algorithm_name);
346 goto end;
347 }
348 len = p8fmt->p8_bytes;
349
350 if (out == NULL) {
351 ret = len;
352 goto end;
353 }
354
355 if ((pos = buf = OPENSSL_malloc((size_t) len)) == NULL)
356 goto end;
357
358 switch (p8fmt->p8_shift) {
359 case 0:
360 pos = OPENSSL_store_u32_be(pos, p8fmt->p8_magic);
361 break;
362 case 2:
363 pos = OPENSSL_store_u16_be(pos, (uint16_t)p8fmt->p8_magic);
364 break;
365 case 4:
366 break;
367 default:
368 ERR_raise_data(ERR_LIB_PROV, ERR_R_INTERNAL_ERROR,
369 "error encoding %s private key",
370 v->algorithm_name);
371 goto end;
372 }
373
374 if (p8fmt->seed_length != 0) {
375 /*
376 * Either the tag/len were already included in |magic| or they require
377 * us to write two bytes now.
378 */
379 if (pos + sizeof(uint16_t) == buf + p8fmt->seed_offset)
380 pos = OPENSSL_store_u16_be(pos, p8fmt->seed_magic);
381 if (pos != buf + p8fmt->seed_offset
382 || !ossl_ml_kem_encode_seed(pos, ML_KEM_SEED_BYTES, key)) {
383 ERR_raise_data(ERR_LIB_PROV, ERR_R_INTERNAL_ERROR,
384 "error encoding %s private key",
385 v->algorithm_name);
386 goto end;
387 }
388 pos += ML_KEM_SEED_BYTES;
389 }
390 if (p8fmt->priv_length != 0) {
391 if (pos + sizeof(uint32_t) == buf + p8fmt->priv_offset)
392 pos = OPENSSL_store_u32_be(pos, p8fmt->priv_magic);
393 if (pos != buf + p8fmt->priv_offset
394 || !ossl_ml_kem_encode_private_key(pos, v->prvkey_bytes, key)) {
395 ERR_raise_data(ERR_LIB_PROV, ERR_R_INTERNAL_ERROR,
396 "error encoding %s private key",
397 v->algorithm_name);
398 goto end;
399 }
400 pos += v->prvkey_bytes;
401 }
402 /* OQS form output with tacked-on public key */
403 if (p8fmt->pub_length != 0) {
404 /* The OQS pubkey is never separately DER-wrapped */
405 if (pos != buf + p8fmt->pub_offset
406 || !ossl_ml_kem_encode_public_key(pos, v->pubkey_bytes, key)) {
407 ERR_raise_data(ERR_LIB_PROV, ERR_R_INTERNAL_ERROR,
408 "error encoding %s private key",
409 v->algorithm_name);
410 goto end;
411 }
412 pos += v->pubkey_bytes;
413 }
414
415 if (pos == buf + len) {
416 *out = buf;
417 ret = len;
418 }
419
420 end:
421 OPENSSL_free(fmt_slots);
422 if (ret == 0)
423 OPENSSL_free(buf);
424 return ret;
425 }
426
ossl_ml_kem_key_to_text(BIO * out,const ML_KEM_KEY * key,int selection)427 int ossl_ml_kem_key_to_text(BIO *out, const ML_KEM_KEY *key, int selection)
428 {
429 uint8_t seed[ML_KEM_SEED_BYTES], *prvenc = NULL, *pubenc = NULL;
430 size_t publen, prvlen;
431 const char *type_label = NULL;
432 int ret = 0;
433
434 if (out == NULL || key == NULL) {
435 ERR_raise(ERR_LIB_OSSL_ENCODER, ERR_R_PASSED_NULL_PARAMETER);
436 return 0;
437 }
438 type_label = key->vinfo->algorithm_name;
439 publen = key->vinfo->pubkey_bytes;
440 prvlen = key->vinfo->prvkey_bytes;
441
442 if ((selection & OSSL_KEYMGMT_SELECT_PRIVATE_KEY) != 0
443 && (ossl_ml_kem_have_prvkey(key)
444 || ossl_ml_kem_have_seed(key))) {
445 if (BIO_printf(out, "%s Private-Key:\n", type_label) <= 0)
446 return 0;
447
448 if (ossl_ml_kem_have_seed(key)) {
449 if (!ossl_ml_kem_encode_seed(seed, sizeof(seed), key))
450 goto end;
451 if (!ossl_bio_print_labeled_buf(out, "seed:", seed, sizeof(seed)))
452 goto end;
453 }
454 if (ossl_ml_kem_have_prvkey(key)) {
455 if ((prvenc = OPENSSL_malloc(prvlen)) == NULL)
456 return 0;
457 if (!ossl_ml_kem_encode_private_key(prvenc, prvlen, key))
458 goto end;
459 if (!ossl_bio_print_labeled_buf(out, "dk:", prvenc, prvlen))
460 goto end;
461 }
462 ret = 1;
463 }
464
465 /* The public key is output regardless of the selection */
466 if (ossl_ml_kem_have_pubkey(key)) {
467 /* If we did not output private key bits, this is a public key */
468 if (ret == 0 && BIO_printf(out, "%s Public-Key:\n", type_label) <= 0)
469 goto end;
470
471 if ((pubenc = OPENSSL_malloc(key->vinfo->pubkey_bytes)) == NULL
472 || !ossl_ml_kem_encode_public_key(pubenc, publen, key)
473 || !ossl_bio_print_labeled_buf(out, "ek:", pubenc, publen))
474 goto end;
475 ret = 1;
476 }
477
478 /* If we got here, and ret == 0, there was no key material */
479 if (ret == 0)
480 ERR_raise_data(ERR_LIB_PROV, PROV_R_MISSING_KEY,
481 "no %s key material available",
482 type_label);
483
484 end:
485 OPENSSL_free(pubenc);
486 OPENSSL_free(prvenc);
487 return ret;
488 }
489