ssl/quic/quic_record_shared.c

   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 (!ossl_qrl_enc_level_set_has_keyslot(els, enc_level, el->state, keyslot))
  91         return;
  92
  93     if (el->cctx[keyslot] != NULL) {
  94         EVP_CIPHER_CTX_free(el->cctx[keyslot]);
  95         el->cctx[keyslot] = NULL;
  96     }
  97
  98     OPENSSL_cleanse(el->iv[keyslot], sizeof(el->iv[keyslot]));
  99 }
 100
 101 static int el_setup_keyslot(OSSL_QRL_ENC_LEVEL_SET *els,
 102                             uint32_t enc_level,
 103                             unsigned char tgt_state,
 104                             size_t keyslot,
 105                             const unsigned char *secret,
 106                             size_t secret_len)
 107 {
 108     OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0);
 109     unsigned char key[EVP_MAX_KEY_LENGTH];
 110     size_t key_len = 0, iv_len = 0;
 111     const char *cipher_name = NULL;
 112     EVP_CIPHER *cipher = NULL;
 113     EVP_CIPHER_CTX *cctx = NULL;
 114
 115     if (!ossl_assert(el != NULL
 116                      && ossl_qrl_enc_level_set_has_keyslot(els, enc_level,
 117                                                            tgt_state, keyslot))) {
 118         ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT);
 119         return 0;
 120     }
 121
 122     cipher_name = ossl_qrl_get_suite_cipher_name(el->suite_id);
 123     iv_len      = ossl_qrl_get_suite_cipher_iv_len(el->suite_id);
 124     key_len     = ossl_qrl_get_suite_cipher_key_len(el->suite_id);
 125     if (cipher_name == NULL) {
 126         ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR);
 127         return 0;
 128     }
 129
 130     if (secret_len != ossl_qrl_get_suite_secret_len(el->suite_id)
 131         || secret_len > EVP_MAX_KEY_LENGTH) {
 132         ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR);
 133         return 0;
 134     }
 135
 136     assert(el->cctx[keyslot] == NULL);
 137
 138     /* Derive "quic iv" key. */
 139     if (!tls13_hkdf_expand_ex(el->libctx, el->propq,
 140                               el->md,
 141                               secret,
 142                               quic_v1_iv_label,
 143                               sizeof(quic_v1_iv_label),
 144                               NULL, 0,
 145                               el->iv[keyslot], iv_len, 1))
 146         goto err;
 147
 148     /* Derive "quic key" key. */
 149     if (!tls13_hkdf_expand_ex(el->libctx, el->propq,
 150                               el->md,
 151                               secret,
 152                               quic_v1_key_label,
 153                               sizeof(quic_v1_key_label),
 154                               NULL, 0,
 155                               key, key_len, 1))
 156         goto err;
 157
 158     /* Create and initialise cipher context. */
 159     if ((cipher = EVP_CIPHER_fetch(el->libctx, cipher_name, el->propq)) == NULL) {
 160         ERR_raise(ERR_LIB_SSL, ERR_R_EVP_LIB);
 161         goto err;
 162     }
 163
 164     if ((cctx = EVP_CIPHER_CTX_new()) == NULL) {
 165         ERR_raise(ERR_LIB_SSL, ERR_R_EVP_LIB);
 166         goto err;
 167     }
 168
 169     if (!ossl_assert(iv_len == (size_t)EVP_CIPHER_get_iv_length(cipher))
 170         || !ossl_assert(key_len == (size_t)EVP_CIPHER_get_key_length(cipher))) {
 171         ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR);
 172         goto err;
 173     }
 174
 175     /* IV will be changed on RX/TX so we don't need to use a real value here. */
 176     if (!EVP_CipherInit_ex(cctx, cipher, NULL, key, el->iv[keyslot], 0)) {
 177         ERR_raise(ERR_LIB_SSL, ERR_R_EVP_LIB);
 178         goto err;
 179     }
 180
 181     el->cctx[keyslot] = cctx;
 182
 183     /* Zeroize intermediate keys. */
 184     OPENSSL_cleanse(key, sizeof(key));
 185     EVP_CIPHER_free(cipher);
 186     return 1;
 187
 188 err:
 189     EVP_CIPHER_CTX_free(cctx);
 190     EVP_CIPHER_free(cipher);
 191     OPENSSL_cleanse(el->iv[keyslot], sizeof(el->iv[keyslot]));
 192     OPENSSL_cleanse(key, sizeof(key));
 193     return 0;
 194 }
 195
 196 int ossl_qrl_enc_level_set_provide_secret(OSSL_QRL_ENC_LEVEL_SET *els,
 197                                           OSSL_LIB_CTX *libctx,
 198                                           const char *propq,
 199                                           uint32_t enc_level,
 200                                           uint32_t suite_id,
 201                                           EVP_MD *md,
 202                                           const unsigned char *secret,
 203                                           size_t secret_len,
 204                                           unsigned char init_key_phase_bit,
 205                                           int is_tx)
 206 {
 207     OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0);
 208     unsigned char ku_key[EVP_MAX_KEY_LENGTH], hpr_key[EVP_MAX_KEY_LENGTH];
 209     int have_ks0 = 0, have_ks1 = 0, own_md = 0;
 210     const char *md_name = ossl_qrl_get_suite_md_name(suite_id);
 211     size_t hpr_key_len, init_keyslot;
 212
 213     if (el == NULL
 214         || md_name == NULL
 215         || init_key_phase_bit > 1 || is_tx < 0 || is_tx > 1
 216         || (init_key_phase_bit > 0 && enc_level != QUIC_ENC_LEVEL_1RTT)) {
 217         ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT);
 218         return 0;
 219     }
 220
 221     if (enc_level == QUIC_ENC_LEVEL_INITIAL
 222         && el->state == QRL_EL_STATE_PROV_NORMAL) {
 223         /*
 224          * Sometimes the INITIAL EL needs to be reprovisioned, namely if a
 225          * connection retry occurs. Exceptionally, if the caller wants to
 226          * reprovision the INITIAL EL, tear it down as usual and then override
 227          * the state so it can be provisioned again.
 228          */
 229         ossl_qrl_enc_level_set_discard(els, enc_level);
 230         el->state = QRL_EL_STATE_UNPROV;
 231     }
 232
 233     if (el->state != QRL_EL_STATE_UNPROV) {
 234         ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR);
 235         return 0;
 236     }
 237
 238     init_keyslot = is_tx ? 0 : init_key_phase_bit;
 239     hpr_key_len = ossl_qrl_get_suite_hdr_prot_key_len(suite_id);
 240     if (hpr_key_len == 0) {
 241         ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR);
 242         return 0;
 243     }
 244
 245     if (md == NULL) {
 246         md = EVP_MD_fetch(libctx, md_name, propq);
 247         if (md == NULL) {
 248             ERR_raise(ERR_LIB_SSL, ERR_R_EVP_LIB);
 249             return 0;
 250         }
 251
 252         own_md = 1;
 253     }
 254
 255     el->libctx      = libctx;
 256     el->propq       = propq;
 257     el->md          = md;
 258     el->suite_id    = suite_id;
 259     el->tag_len     = ossl_qrl_get_suite_cipher_tag_len(suite_id);
 260     el->op_count    = 0;
 261     el->key_epoch   = (uint64_t)init_key_phase_bit;
 262     el->is_tx       = (unsigned char)is_tx;
 263
 264     /* Derive "quic hp" key. */
 265     if (!tls13_hkdf_expand_ex(libctx, propq,
 266                               md,
 267                               secret,
 268                               quic_v1_hp_label,
 269                               sizeof(quic_v1_hp_label),
 270                               NULL, 0,
 271                               hpr_key, hpr_key_len, 1))
 272         goto err;
 273
 274     /* Setup KS0 (or KS1 if init_key_phase_bit), our initial keyslot. */
 275     if (!el_setup_keyslot(els, enc_level, QRL_EL_STATE_PROV_NORMAL,
 276                           init_keyslot, secret, secret_len))
 277         goto err;
 278
 279     have_ks0 = 1;
 280
 281     if (enc_level == QUIC_ENC_LEVEL_1RTT) {
 282         /* Derive "quic ku" key (the epoch 1 secret). */
 283         if (!tls13_hkdf_expand_ex(libctx, propq,
 284                                   md,
 285                                   secret,
 286                                   quic_v1_ku_label,
 287                                   sizeof(quic_v1_ku_label),
 288                                   NULL, 0,
 289                                   is_tx ? el->ku : ku_key, secret_len, 1))
 290             goto err;
 291
 292         if (!is_tx) {
 293             /* Setup KS1 (or KS0 if init_key_phase_bit), our next keyslot. */
 294             if (!el_setup_keyslot(els, enc_level, QRL_EL_STATE_PROV_NORMAL,
 295                                   !init_keyslot, ku_key, secret_len))
 296                 goto err;
 297
 298             have_ks1 = 1;
 299
 300             /* Derive NEXT "quic ku" key (the epoch 2 secret). */
 301             if (!tls13_hkdf_expand_ex(libctx, propq,
 302                                       md,
 303                                       ku_key,
 304                                       quic_v1_ku_label,
 305                                       sizeof(quic_v1_ku_label),
 306                                       NULL, 0,
 307                                       el->ku, secret_len, 1))
 308                 goto err;
 309         }
 310     }
 311
 312     /* Setup header protection context. */
 313     if (!ossl_quic_hdr_protector_init(&el->hpr,
 314                                       libctx, propq,
 315                                       ossl_qrl_get_suite_hdr_prot_cipher_id(suite_id),
 316                                       hpr_key, hpr_key_len))
 317         goto err;
 318
 319     /*
 320      * We are now provisioned: KS0 has our current key (for key epoch 0), KS1
 321      * has our next key (for key epoch 1, in the case of the 1-RTT EL only), and
 322      * el->ku has the secret which will be used to generate keys for key epoch
 323      * 2.
 324      */
 325     OPENSSL_cleanse(hpr_key, sizeof(hpr_key));
 326     OPENSSL_cleanse(ku_key, sizeof(ku_key));
 327     el->state = QRL_EL_STATE_PROV_NORMAL;
 328     return 1;
 329
 330 err:
 331     el->suite_id = 0;
 332     el->md = NULL;
 333     OPENSSL_cleanse(hpr_key, sizeof(hpr_key));
 334     OPENSSL_cleanse(ku_key, sizeof(ku_key));
 335     OPENSSL_cleanse(el->ku, sizeof(el->ku));
 336     if (have_ks0)
 337         el_teardown_keyslot(els, enc_level, 0);
 338     if (have_ks1)
 339         el_teardown_keyslot(els, enc_level, 1);
 340     if (own_md)
 341         EVP_MD_free(md);
 342     return 0;
 343 }
 344
 345 int ossl_qrl_enc_level_set_key_update(OSSL_QRL_ENC_LEVEL_SET *els,
 346                                       uint32_t enc_level)
 347 {
 348     OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0);
 349     size_t secret_len;
 350     unsigned char new_ku[EVP_MAX_KEY_LENGTH];
 351
 352     if (el == NULL || !ossl_assert(enc_level == QUIC_ENC_LEVEL_1RTT)) {
 353         ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT);
 354         return 0;
 355     }
 356
 357     if (el->state != QRL_EL_STATE_PROV_NORMAL) {
 358         ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR);
 359         return 0;
 360     }
 361
 362     if (!el->is_tx) {
 363         /*
 364          * We already have the key for the next epoch, so just move to using it.
 365          */
 366         ++el->key_epoch;
 367         el->state = QRL_EL_STATE_PROV_UPDATING;
 368         return 1;
 369     }
 370
 371     /*
 372      * TX case. For the TX side we use only keyslot 0; it replaces the old key
 373      * immediately.
 374      */
 375     secret_len = ossl_qrl_get_suite_secret_len(el->suite_id);
 376
 377     /* Derive NEXT "quic ku" key (the epoch n+1 secret). */
 378     if (!tls13_hkdf_expand_ex(el->libctx, el->propq,
 379                               el->md, el->ku,
 380                               quic_v1_ku_label,
 381                               sizeof(quic_v1_ku_label),
 382                               NULL, 0,
 383                               new_ku, secret_len, 1))
 384         return 0;
 385
 386     el_teardown_keyslot(els, enc_level, 0);
 387
 388     /* Setup keyslot for CURRENT "quic ku" key. */
 389     if (!el_setup_keyslot(els, enc_level, QRL_EL_STATE_PROV_NORMAL,
 390                           0, el->ku, secret_len))
 391         return 0;
 392
 393     ++el->key_epoch;
 394     el->op_count = 0;
 395     memcpy(el->ku, new_ku, secret_len);
 396     /* Remain in PROV_NORMAL state */
 397     return 1;
 398 }
 399
 400 /* Transitions from PROV_UPDATING to PROV_COOLDOWN. */
 401 int ossl_qrl_enc_level_set_key_update_done(OSSL_QRL_ENC_LEVEL_SET *els,
 402                                            uint32_t enc_level)
 403 {
 404     OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0);
 405
 406     if (el == NULL || !ossl_assert(enc_level == QUIC_ENC_LEVEL_1RTT)) {
 407         ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT);
 408         return 0;
 409     }
 410
 411     /* No new key yet, but erase key material to aid PFS. */
 412     el_teardown_keyslot(els, enc_level, ~el->key_epoch & 1);
 413     el->state = QRL_EL_STATE_PROV_COOLDOWN;
 414     return 1;
 415 }
 416
 417 /*
 418  * Transitions from PROV_COOLDOWN to PROV_NORMAL. (If in PROV_UPDATING,
 419  * auto-transitions to PROV_COOLDOWN first.)
 420  */
 421 int ossl_qrl_enc_level_set_key_cooldown_done(OSSL_QRL_ENC_LEVEL_SET *els,
 422                                              uint32_t enc_level)
 423 {
 424     OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0);
 425     size_t secret_len;
 426     unsigned char new_ku[EVP_MAX_KEY_LENGTH];
 427
 428     if (el == NULL || !ossl_assert(enc_level == QUIC_ENC_LEVEL_1RTT)) {
 429         ERR_raise(ERR_LIB_SSL, ERR_R_PASSED_INVALID_ARGUMENT);
 430         return 0;
 431     }
 432
 433     if (el->state == QRL_EL_STATE_PROV_UPDATING
 434         && !ossl_qrl_enc_level_set_key_update_done(els, enc_level)) {
 435         ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR);
 436         return 0;
 437     }
 438
 439     if (el->state != QRL_EL_STATE_PROV_COOLDOWN) {
 440         ERR_raise(ERR_LIB_SSL, ERR_R_INTERNAL_ERROR);
 441         return 0;
 442     }
 443
 444     secret_len = ossl_qrl_get_suite_secret_len(el->suite_id);
 445
 446     if (!el_setup_keyslot(els, enc_level, QRL_EL_STATE_PROV_NORMAL,
 447                           ~el->key_epoch & 1, el->ku, secret_len))
 448         return 0;
 449
 450     /* Derive NEXT "quic ku" key (the epoch n+1 secret). */
 451     if (!tls13_hkdf_expand_ex(el->libctx, el->propq,
 452                               el->md,
 453                               el->ku,
 454                               quic_v1_ku_label,
 455                               sizeof(quic_v1_ku_label),
 456                               NULL, 0,
 457                               new_ku, secret_len, 1)) {
 458         el_teardown_keyslot(els, enc_level, ~el->key_epoch & 1);
 459         return 0;
 460     }
 461
 462     memcpy(el->ku, new_ku, secret_len);
 463     el->state = QRL_EL_STATE_PROV_NORMAL;
 464     return 1;
 465 }
 466
 467 /*
 468  * Discards keying material for a given encryption level. Transitions from any
 469  * state to DISCARDED.
 470  */
 471 void ossl_qrl_enc_level_set_discard(OSSL_QRL_ENC_LEVEL_SET *els,
 472                                     uint32_t enc_level)
 473 {
 474     OSSL_QRL_ENC_LEVEL *el = ossl_qrl_enc_level_set_get(els, enc_level, 0);
 475
 476     if (el == NULL || el->state == QRL_EL_STATE_DISCARDED)
 477         return;
 478
 479     if (ossl_qrl_enc_level_set_have_el(els, enc_level) == 1) {
 480         ossl_quic_hdr_protector_cleanup(&el->hpr);
 481
 482         el_teardown_keyslot(els, enc_level, 0);
 483         el_teardown_keyslot(els, enc_level, 1);
 484     }
 485
 486     EVP_MD_free(el->md);
 487     el->md      = NULL;
 488     el->state   = QRL_EL_STATE_DISCARDED;
 489 }