1 #include "quic_record_shared.h" 2 #include "internal/quic_record_util.h" 3 #include "internal/common.h" 4 #include "../ssl_local.h" 5 6 /* Constants used for key derivation in QUIC v1. */ 7 static const unsigned char quic_v1_iv_label[] = { 8 0x71, 0x75, 0x69, 0x63, 0x20, 0x69, 0x76 /* "quic iv" */ 9 }; 10 static const unsigned char quic_v1_key_label[] = { 11 0x71, 0x75, 0x69, 0x63, 0x20, 0x6b, 0x65, 0x79 /* "quic key" */ 12 }; 13 static const unsigned char quic_v1_hp_label[] = { 14 0x71, 0x75, 0x69, 0x63, 0x20, 0x68, 0x70 /* "quic hp" */ 15 }; 16 static const unsigned char quic_v1_ku_label[] = { 17 0x71, 0x75, 0x69, 0x63, 0x20, 0x6b, 0x75 /* "quic ku" */ 18 }; 19 20 OSSL_QRL_ENC_LEVEL *ossl_qrl_enc_level_set_get(OSSL_QRL_ENC_LEVEL_SET *els, 21 uint32_t enc_level, 22 int require_prov) 23 { 24 OSSL_QRL_ENC_LEVEL *el; 25 26 if (!ossl_assert(enc_level < QUIC_ENC_LEVEL_NUM)) 27 return NULL; 28 29 el = &els->el[enc_level]; 30 31 if (require_prov) 32 switch (el->state) { 33 case QRL_EL_STATE_PROV_NORMAL: 34 case QRL_EL_STATE_PROV_UPDATING: 35 case QRL_EL_STATE_PROV_COOLDOWN: 36 break; 37 default: 38 return NULL; 39 } 40 41 return el; 42 } 43 44 int ossl_qrl_enc_level_set_have_el(OSSL_QRL_ENC_LEVEL_SET *els, 45 uint32_t enc_level) 46 { 47 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 48 49 switch (el->state) { 50 case QRL_EL_STATE_UNPROV: 51 return 0; 52 case QRL_EL_STATE_PROV_NORMAL: 53 case QRL_EL_STATE_PROV_UPDATING: 54 case QRL_EL_STATE_PROV_COOLDOWN: 55 return 1; 56 default: 57 case QRL_EL_STATE_DISCARDED: 58 return -1; 59 } 60 } 61 62 int ossl_qrl_enc_level_set_has_keyslot(OSSL_QRL_ENC_LEVEL_SET *els, 63 uint32_t enc_level, 64 unsigned char tgt_state, 65 size_t keyslot) 66 { 67 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 68 69 if (!ossl_assert(el != NULL && keyslot < 2)) 70 return 0; 71 72 switch (tgt_state) { 73 case QRL_EL_STATE_PROV_NORMAL: 74 case QRL_EL_STATE_PROV_UPDATING: 75 return enc_level == QUIC_ENC_LEVEL_1RTT || keyslot == 0; 76 case QRL_EL_STATE_PROV_COOLDOWN: 77 assert(enc_level == QUIC_ENC_LEVEL_1RTT); 78 return keyslot == (el->key_epoch & 1); 79 default: 80 return 0; 81 } 82 } 83 84 static void el_teardown_keyslot(OSSL_QRL_ENC_LEVEL_SET *els, 85 uint32_t enc_level, 86 size_t keyslot) 87 { 88 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 89 90 if (el->cctx[keyslot] != NULL) { 91 EVP_CIPHER_CTX_free(el->cctx[keyslot]); 92 el->cctx[keyslot] = NULL; 93 } 94 95 OPENSSL_cleanse(el->iv[keyslot], sizeof(el->iv[keyslot])); 96 } 97 98 static int el_build_keyslot(OSSL_QRL_ENC_LEVEL *el, 99 const unsigned char *secret, size_t secret_len, 100 EVP_CIPHER_CTX **out_cctx, unsigned char *out_iv, size_t *out_iv_len) 101 { 102 unsigned char key[EVP_MAX_KEY_LENGTH]; 103 size_t key_len = 0, iv_len = 0; 104 const char *cipher_name = NULL; 105 EVP_CIPHER *cipher = NULL; 106 EVP_CIPHER_CTX *cctx = NULL; 107 108 *out_cctx = NULL; 109 *out_iv_len = 0; 110 111 cipher_name = ossl_qrl_get_suite_cipher_name(el->suite_id); 112 iv_len = ossl_qrl_get_suite_cipher_iv_len(el->suite_id); 113 key_len = ossl_qrl_get_suite_cipher_key_len(el->suite_id); 114 if (cipher_name == NULL) { 115 ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR); 116 return 0; 117 } 118 119 if (secret_len != ossl_qrl_get_suite_secret_len(el->suite_id) 120 || secret_len > EVP_MAX_KEY_LENGTH) { 121 ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR); 122 return 0; 123 } 124 125 /* Derive "quic iv" into caller's buffer. */ 126 if (!tls13_hkdf_expand_ex(el->libctx, el->propq, el->md, secret, 127 quic_v1_iv_label, sizeof(quic_v1_iv_label), NULL, 0, 128 out_iv, iv_len, 1)) 129 goto err; 130 131 /* Derive "quic key" into local. */ 132 if (!tls13_hkdf_expand_ex(el->libctx, el->propq, el->md, secret, 133 quic_v1_key_label, sizeof(quic_v1_key_label), NULL, 0, 134 key, key_len, 1)) 135 goto err; 136 137 /* Create and initialise cipher context. */ 138 if ((cipher = EVP_CIPHER_fetch(el->libctx, cipher_name, el->propq)) == NULL) { 139 ERR_raise(ERR_LIB_SSL, ERR_R_EVP_LIB); 140 goto err; 141 } 142 143 if ((cctx = EVP_CIPHER_CTX_new()) == NULL) { 144 ERR_raise(ERR_LIB_SSL, ERR_R_EVP_LIB); 145 goto err; 146 } 147 148 if (!ossl_assert(iv_len == (size_t)EVP_CIPHER_get_iv_length(cipher)) 149 || !ossl_assert(key_len == (size_t)EVP_CIPHER_get_key_length(cipher))) { 150 ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR); 151 goto err; 152 } 153 154 /* IV will be changed on RX/TX so we don't need to use a real value here. */ 155 if (!EVP_CipherInit_ex(cctx, cipher, NULL, key, out_iv, 0)) { 156 ERR_raise(ERR_LIB_SSL, ERR_R_EVP_LIB); 157 goto err; 158 } 159 160 *out_cctx = cctx; 161 *out_iv_len = iv_len; 162 163 /* Zeroize intermediate keys. */ 164 OPENSSL_cleanse(key, sizeof(key)); 165 EVP_CIPHER_free(cipher); 166 return 1; 167 168 err: 169 EVP_CIPHER_CTX_free(cctx); 170 EVP_CIPHER_free(cipher); 171 OPENSSL_cleanse(key, sizeof(key)); 172 OPENSSL_cleanse(out_iv, iv_len); 173 return 0; 174 } 175 176 static void el_install_keyslot(OSSL_QRL_ENC_LEVEL *el, size_t keyslot, 177 EVP_CIPHER_CTX *new_cctx, const unsigned char *new_iv, size_t new_iv_len) 178 { 179 assert(el->cctx[keyslot] == NULL); 180 assert(new_iv_len <= sizeof(el->iv[keyslot])); 181 182 el->cctx[keyslot] = new_cctx; 183 memcpy(el->iv[keyslot], new_iv, new_iv_len); 184 } 185 186 static int el_setup_keyslot(OSSL_QRL_ENC_LEVEL_SET *els, uint32_t enc_level, 187 unsigned char tgt_state, size_t keyslot, const unsigned char *secret, 188 size_t secret_len) 189 { 190 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 191 EVP_CIPHER_CTX *new_cctx = NULL; 192 unsigned char new_iv[EVP_MAX_IV_LENGTH]; 193 size_t new_iv_len = EVP_MAX_IV_LENGTH; 194 195 if (!ossl_assert(el != NULL 196 && ossl_qrl_enc_level_set_has_keyslot(els, enc_level, 197 tgt_state, keyslot))) { 198 ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT); 199 return 0; 200 } 201 202 if (!el_build_keyslot(el, secret, secret_len, &new_cctx, new_iv, 203 &new_iv_len)) 204 return 0; 205 206 el_install_keyslot(el, keyslot, new_cctx, new_iv, new_iv_len); 207 208 OPENSSL_cleanse(new_iv, sizeof(new_iv)); 209 return 1; 210 } 211 212 int ossl_qrl_enc_level_set_provide_secret(OSSL_QRL_ENC_LEVEL_SET *els, 213 OSSL_LIB_CTX *libctx, 214 const char *propq, 215 uint32_t enc_level, 216 uint32_t suite_id, 217 EVP_MD *md, 218 const unsigned char *secret, 219 size_t secret_len, 220 unsigned char init_key_phase_bit, 221 int is_tx) 222 { 223 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 224 unsigned char ku_key[EVP_MAX_KEY_LENGTH], hpr_key[EVP_MAX_KEY_LENGTH]; 225 int have_ks0 = 0, have_ks1 = 0, own_md = 0; 226 const char *md_name = ossl_qrl_get_suite_md_name(suite_id); 227 size_t hpr_key_len, init_keyslot; 228 229 if (el == NULL 230 || md_name == NULL 231 || init_key_phase_bit > 1 || is_tx < 0 || is_tx > 1 232 || (init_key_phase_bit > 0 && enc_level != QUIC_ENC_LEVEL_1RTT)) { 233 ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT); 234 return 0; 235 } 236 237 if (enc_level == QUIC_ENC_LEVEL_INITIAL 238 && el->state == QRL_EL_STATE_PROV_NORMAL) { 239 /* 240 * Sometimes the INITIAL EL needs to be reprovisioned, namely if a 241 * connection retry occurs. Exceptionally, if the caller wants to 242 * reprovision the INITIAL EL, tear it down as usual and then override 243 * the state so it can be provisioned again. 244 */ 245 ossl_qrl_enc_level_set_discard(els, enc_level); 246 el->state = QRL_EL_STATE_UNPROV; 247 } 248 249 if (el->state != QRL_EL_STATE_UNPROV) { 250 ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR); 251 return 0; 252 } 253 254 init_keyslot = is_tx ? 0 : init_key_phase_bit; 255 hpr_key_len = ossl_qrl_get_suite_hdr_prot_key_len(suite_id); 256 if (hpr_key_len == 0) { 257 ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR); 258 return 0; 259 } 260 261 if (md == NULL) { 262 md = EVP_MD_fetch(libctx, md_name, propq); 263 if (md == NULL) { 264 ERR_raise(ERR_LIB_SSL, ERR_R_EVP_LIB); 265 return 0; 266 } 267 268 own_md = 1; 269 } 270 271 el->libctx = libctx; 272 el->propq = propq; 273 el->md = md; 274 el->suite_id = suite_id; 275 el->tag_len = ossl_qrl_get_suite_cipher_tag_len(suite_id); 276 el->op_count = 0; 277 el->key_epoch = (uint64_t)init_key_phase_bit; 278 el->is_tx = (unsigned char)is_tx; 279 280 /* Derive "quic hp" key. */ 281 if (!tls13_hkdf_expand_ex(libctx, propq, 282 md, 283 secret, 284 quic_v1_hp_label, 285 sizeof(quic_v1_hp_label), 286 NULL, 0, 287 hpr_key, hpr_key_len, 1)) 288 goto err; 289 290 /* Setup KS0 (or KS1 if init_key_phase_bit), our initial keyslot. */ 291 if (!el_setup_keyslot(els, enc_level, QRL_EL_STATE_PROV_NORMAL, 292 init_keyslot, secret, secret_len)) 293 goto err; 294 295 have_ks0 = 1; 296 297 if (enc_level == QUIC_ENC_LEVEL_1RTT) { 298 /* Derive "quic ku" key (the epoch 1 secret). */ 299 if (!tls13_hkdf_expand_ex(libctx, propq, 300 md, 301 secret, 302 quic_v1_ku_label, 303 sizeof(quic_v1_ku_label), 304 NULL, 0, 305 is_tx ? el->ku : ku_key, secret_len, 1)) 306 goto err; 307 308 if (!is_tx) { 309 /* Setup KS1 (or KS0 if init_key_phase_bit), our next keyslot. */ 310 if (!el_setup_keyslot(els, enc_level, QRL_EL_STATE_PROV_NORMAL, 311 !init_keyslot, ku_key, secret_len)) 312 goto err; 313 314 have_ks1 = 1; 315 316 /* Derive NEXT "quic ku" key (the epoch 2 secret). */ 317 if (!tls13_hkdf_expand_ex(libctx, propq, 318 md, 319 ku_key, 320 quic_v1_ku_label, 321 sizeof(quic_v1_ku_label), 322 NULL, 0, 323 el->ku, secret_len, 1)) 324 goto err; 325 } 326 } 327 328 /* Setup header protection context. */ 329 if (!ossl_quic_hdr_protector_init(&el->hpr, 330 libctx, propq, 331 ossl_qrl_get_suite_hdr_prot_cipher_id(suite_id), 332 hpr_key, hpr_key_len)) 333 goto err; 334 335 /* 336 * We are now provisioned: KS0 has our current key (for key epoch 0), KS1 337 * has our next key (for key epoch 1, in the case of the 1-RTT EL only), and 338 * el->ku has the secret which will be used to generate keys for key epoch 339 * 2. 340 */ 341 OPENSSL_cleanse(hpr_key, sizeof(hpr_key)); 342 OPENSSL_cleanse(ku_key, sizeof(ku_key)); 343 el->state = QRL_EL_STATE_PROV_NORMAL; 344 return 1; 345 346 err: 347 el->suite_id = 0; 348 el->md = NULL; 349 OPENSSL_cleanse(hpr_key, sizeof(hpr_key)); 350 OPENSSL_cleanse(ku_key, sizeof(ku_key)); 351 OPENSSL_cleanse(el->ku, sizeof(el->ku)); 352 if (have_ks0) 353 el_teardown_keyslot(els, enc_level, init_keyslot); 354 if (have_ks1) 355 el_teardown_keyslot(els, enc_level, !init_keyslot); 356 if (own_md) 357 EVP_MD_free(md); 358 return 0; 359 } 360 361 int ossl_qrl_enc_level_set_key_update(OSSL_QRL_ENC_LEVEL_SET *els, 362 uint32_t enc_level) 363 { 364 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 365 EVP_CIPHER_CTX *new_cctx = NULL; 366 unsigned char new_iv[EVP_MAX_IV_LENGTH]; 367 size_t new_iv_len = EVP_MAX_IV_LENGTH; 368 size_t secret_len; 369 unsigned char new_ku[EVP_MAX_KEY_LENGTH]; 370 371 if (el == NULL || !ossl_assert(enc_level == QUIC_ENC_LEVEL_1RTT)) { 372 ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT); 373 return 0; 374 } 375 376 if (el->state != QRL_EL_STATE_PROV_NORMAL) { 377 ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR); 378 return 0; 379 } 380 381 if (!el->is_tx) { 382 /* 383 * We already have the key for the next epoch, so just move to using it. 384 */ 385 ++el->key_epoch; 386 el->state = QRL_EL_STATE_PROV_UPDATING; 387 return 1; 388 } 389 390 /* 391 * TX case. For the TX side we use only keyslot 0; it replaces the old key 392 * immediately. 393 */ 394 secret_len = ossl_qrl_get_suite_secret_len(el->suite_id); 395 396 /* Derive NEXT "quic ku" key (the epoch n+1 secret). */ 397 if (!tls13_hkdf_expand_ex(el->libctx, el->propq, 398 el->md, el->ku, 399 quic_v1_ku_label, 400 sizeof(quic_v1_ku_label), 401 NULL, 0, 402 new_ku, secret_len, 1)) 403 return 0; 404 405 /* Build new keyslot first so if it fails, teardown is not done. */ 406 if (!el_build_keyslot(el, el->ku, secret_len, &new_cctx, new_iv, 407 &new_iv_len)) 408 return 0; 409 410 el_teardown_keyslot(els, enc_level, 0); 411 el_install_keyslot(el, 0, new_cctx, new_iv, new_iv_len); 412 OPENSSL_cleanse(new_iv, sizeof(new_iv)); 413 414 ++el->key_epoch; 415 el->op_count = 0; 416 memcpy(el->ku, new_ku, secret_len); 417 /* Remain in PROV_NORMAL state */ 418 return 1; 419 } 420 421 /* Transitions from PROV_UPDATING to PROV_COOLDOWN. */ 422 int ossl_qrl_enc_level_set_key_update_done(OSSL_QRL_ENC_LEVEL_SET *els, 423 uint32_t enc_level) 424 { 425 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 426 427 if (el == NULL || !ossl_assert(enc_level == QUIC_ENC_LEVEL_1RTT)) { 428 ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT); 429 return 0; 430 } 431 432 /* No new key yet, but erase key material to aid PFS. */ 433 el_teardown_keyslot(els, enc_level, ~el->key_epoch & 1); 434 el->state = QRL_EL_STATE_PROV_COOLDOWN; 435 return 1; 436 } 437 438 /* 439 * Transitions from PROV_COOLDOWN to PROV_NORMAL. (If in PROV_UPDATING, 440 * auto-transitions to PROV_COOLDOWN first.) 441 */ 442 int ossl_qrl_enc_level_set_key_cooldown_done(OSSL_QRL_ENC_LEVEL_SET *els, 443 uint32_t enc_level) 444 { 445 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 446 size_t secret_len; 447 unsigned char new_ku[EVP_MAX_KEY_LENGTH]; 448 449 if (el == NULL || !ossl_assert(enc_level == QUIC_ENC_LEVEL_1RTT)) { 450 ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT); 451 return 0; 452 } 453 454 if (el->state == QRL_EL_STATE_PROV_UPDATING 455 && !ossl_qrl_enc_level_set_key_update_done(els, enc_level)) { 456 ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR); 457 return 0; 458 } 459 460 if (el->state != QRL_EL_STATE_PROV_COOLDOWN) { 461 ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR); 462 return 0; 463 } 464 465 secret_len = ossl_qrl_get_suite_secret_len(el->suite_id); 466 467 if (!el_setup_keyslot(els, enc_level, QRL_EL_STATE_PROV_NORMAL, 468 ~el->key_epoch & 1, el->ku, secret_len)) 469 return 0; 470 471 /* Derive NEXT "quic ku" key (the epoch n+1 secret). */ 472 if (!tls13_hkdf_expand_ex(el->libctx, el->propq, 473 el->md, 474 el->ku, 475 quic_v1_ku_label, 476 sizeof(quic_v1_ku_label), 477 NULL, 0, 478 new_ku, secret_len, 1)) { 479 el_teardown_keyslot(els, enc_level, ~el->key_epoch & 1); 480 return 0; 481 } 482 483 memcpy(el->ku, new_ku, secret_len); 484 el->state = QRL_EL_STATE_PROV_NORMAL; 485 return 1; 486 } 487 488 /* 489 * Discards keying material for a given encryption level. Transitions from any 490 * state to DISCARDED. 491 */ 492 void ossl_qrl_enc_level_set_discard(OSSL_QRL_ENC_LEVEL_SET *els, 493 uint32_t enc_level) 494 { 495 OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0); 496 497 if (el == NULL || el->state == QRL_EL_STATE_DISCARDED) 498 return; 499 500 if (ossl_qrl_enc_level_set_have_el(els, enc_level) == 1) { 501 ossl_quic_hdr_protector_cleanup(&el->hpr); 502 503 el_teardown_keyslot(els, enc_level, 0); 504 el_teardown_keyslot(els, enc_level, 1); 505 } 506 507 EVP_MD_free(el->md); 508 el->md = NULL; 509 el->state = QRL_EL_STATE_DISCARDED; 510 } 511
Indexes created Thu Jun 25 00:25:11 UTC 2026