1 /* 2 * Copyright 2022 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 OSSL_QUIC_RECORD_SHARED_H 11 # define OSSL_QUIC_RECORD_SHARED_H 12 13 # include <openssl/ssl.h> 14 # include "internal/quic_types.h" 15 # include "internal/quic_wire_pkt.h" 16 17 /* 18 * QUIC Record Layer EL Management Utilities 19 * ========================================= 20 * 21 * This defines a structure for managing the cryptographic state at a given 22 * encryption level, as this functionality is shared between QRX and QTX. For 23 * QRL use only. 24 */ 25 26 /* 27 * States an EL can be in. The Updating and Cooldown states are used by RX only; 28 * a TX EL in the Provisioned state is always in the Normal substate. 29 * 30 * Key material is available if in the Provisioned state. 31 */ 32 #define QRL_EL_STATE_UNPROV 0 /* Unprovisioned (initial state) */ 33 #define QRL_EL_STATE_PROV_NORMAL 1 /* Provisioned - Normal */ 34 #define QRL_EL_STATE_PROV_UPDATING 2 /* Provisioned - Updating */ 35 #define QRL_EL_STATE_PROV_COOLDOWN 3 /* Provisioned - Cooldown */ 36 #define QRL_EL_STATE_DISCARDED 4 /* Discarded (terminal state) */ 37 38 typedef struct ossl_qrl_enc_level_st { 39 /* 40 * Cryptographic context used to apply and remove header protection from 41 * packet headers. 42 */ 43 QUIC_HDR_PROTECTOR hpr; 44 45 /* Hash function used for key derivation. */ 46 EVP_MD *md; 47 48 /* Context used for packet body ciphering. One for each keyslot. */ 49 EVP_CIPHER_CTX *cctx[2]; 50 51 OSSL_LIB_CTX *libctx; 52 const char *propq; 53 54 /* 55 * Key epoch, essentially the number of times we have done a key update. 56 * 57 * The least significant bit of this is therefore by definition the current 58 * Key Phase bit value. 59 */ 60 uint64_t key_epoch; 61 62 /* Usage counter. The caller maintains this. Used by TX side only. */ 63 uint64_t op_count; 64 65 /* QRL_SUITE_* value. */ 66 uint32_t suite_id; 67 68 /* Length of authentication tag. */ 69 uint32_t tag_len; 70 71 /* Current EL state. */ 72 unsigned char state; /* QRL_EL_STATE_* */ 73 74 /* 1 if for TX, else RX. Initialised when secret provided. */ 75 unsigned char is_tx; 76 77 /* IV used to construct nonces used for AEAD packet body ciphering. */ 78 unsigned char iv[2][EVP_MAX_IV_LENGTH]; 79 80 /* 81 * Secret for next key epoch. 82 */ 83 unsigned char ku[EVP_MAX_KEY_LENGTH]; 84 } OSSL_QRL_ENC_LEVEL; 85 86 typedef struct ossl_qrl_enc_level_set_st { 87 OSSL_QRL_ENC_LEVEL el[QUIC_ENC_LEVEL_NUM]; 88 } OSSL_QRL_ENC_LEVEL_SET; 89 90 /* 91 * Returns 1 if we have key material for a given encryption level (that is, if 92 * we are in the PROVISIONED state), 0 if we do not yet have material (we are in 93 * the UNPROVISIONED state) and -1 if the EL is discarded (we are in the 94 * DISCARDED state). 95 */ 96 int ossl_qrl_enc_level_set_have_el(OSSL_QRL_ENC_LEVEL_SET *els, 97 uint32_t enc_level); 98 99 /* 100 * Returns EL in a set. If enc_level is not a valid QUIC_ENC_LEVEL_* value, 101 * returns NULL. If require_prov is 1, returns NULL if the EL is not in 102 * the PROVISIONED state; otherwise, the returned EL may be in any state. 103 */ 104 OSSL_QRL_ENC_LEVEL *ossl_qrl_enc_level_set_get(OSSL_QRL_ENC_LEVEL_SET *els, 105 uint32_t enc_level, 106 int require_prov); 107 108 /* Provide secret to an EL. md may be NULL. */ 109 int ossl_qrl_enc_level_set_provide_secret(OSSL_QRL_ENC_LEVEL_SET *els, 110 OSSL_LIB_CTX *libctx, 111 const char *propq, 112 uint32_t enc_level, 113 uint32_t suite_id, 114 EVP_MD *md, 115 const unsigned char *secret, 116 size_t secret_len, 117 unsigned char init_key_phase_bit, 118 int is_tx); 119 120 /* 121 * Returns 1 if the given keyslot index is currently valid for a given EL and EL 122 * state. 123 */ 124 int ossl_qrl_enc_level_set_has_keyslot(OSSL_QRL_ENC_LEVEL_SET *els, 125 uint32_t enc_level, 126 unsigned char tgt_state, 127 size_t keyslot); 128 129 /* Perform a key update. Transitions from PROV_NORMAL to PROV_UPDATING. */ 130 int ossl_qrl_enc_level_set_key_update(OSSL_QRL_ENC_LEVEL_SET *els, 131 uint32_t enc_level); 132 133 /* Transitions from PROV_UPDATING to PROV_COOLDOWN. */ 134 int ossl_qrl_enc_level_set_key_update_done(OSSL_QRL_ENC_LEVEL_SET *els, 135 uint32_t enc_level); 136 137 /* 138 * Transitions from PROV_COOLDOWN to PROV_NORMAL. (If in PROV_UPDATING, 139 * auto-transitions to PROV_COOLDOWN first.) 140 */ 141 int ossl_qrl_enc_level_set_key_cooldown_done(OSSL_QRL_ENC_LEVEL_SET *els, 142 uint32_t enc_level); 143 144 /* 145 * Discard an EL. No secret can be provided for the EL ever again. 146 */ 147 void ossl_qrl_enc_level_set_discard(OSSL_QRL_ENC_LEVEL_SET *els, 148 uint32_t enc_level); 149 150 #endif 151
