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 */ 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 * 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 * 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. */ 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. */ 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 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