1 /* 2 * Copyright 2022-2024 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_TX_H 11 # define OSSL_QUIC_RECORD_TX_H 12 13 # include <openssl/ssl.h> 14 # include "internal/quic_wire_pkt.h" 15 # include "internal/quic_types.h" 16 # include "internal/quic_predef.h" 17 # include "internal/quic_record_util.h" 18 # include "internal/qlog.h" 19 20 # ifndef OPENSSL_NO_QUIC 21 22 /* 23 * QUIC Record Layer - TX 24 * ====================== 25 */ 26 typedef struct ossl_qtx_iovec_st { 27 const unsigned char *buf; 28 size_t buf_len; 29 } OSSL_QTX_IOVEC; 30 31 typedef struct ossl_qtx_st OSSL_QTX; 32 33 typedef int (*ossl_mutate_packet_cb)(const QUIC_PKT_HDR *hdrin, 34 const OSSL_QTX_IOVEC *iovecin, size_t numin, 35 QUIC_PKT_HDR **hdrout, 36 const OSSL_QTX_IOVEC **iovecout, 37 size_t *numout, 38 void *arg); 39 40 typedef void (*ossl_finish_mutate_cb)(void *arg); 41 42 typedef struct ossl_qtx_args_st { 43 OSSL_LIB_CTX *libctx; 44 const char *propq; 45 46 /* BIO to transmit to. */ 47 BIO *bio; 48 49 /* Maximum datagram payload length (MDPL) for TX purposes. */ 50 size_t mdpl; 51 52 /* Callback returning QLOG instance to use, or NULL. */ 53 QLOG *(*get_qlog_cb)(void *arg); 54 void *get_qlog_cb_arg; 55 } OSSL_QTX_ARGS; 56 57 /* Instantiates a new QTX. */ 58 OSSL_QTX *ossl_qtx_new(const OSSL_QTX_ARGS *args); 59 60 /* Frees the QTX. */ 61 void ossl_qtx_free(OSSL_QTX *qtx); 62 63 /* Set mutator callbacks for test framework support */ 64 void ossl_qtx_set_mutator(OSSL_QTX *qtx, ossl_mutate_packet_cb mutatecb, 65 ossl_finish_mutate_cb finishmutatecb, void *mutatearg); 66 67 /* Setters for the msg_callback and the msg_callback_arg */ 68 void ossl_qtx_set_msg_callback(OSSL_QTX *qtx, ossl_msg_cb msg_callback, 69 SSL *msg_callback_ssl); 70 void ossl_qtx_set_msg_callback_arg(OSSL_QTX *qtx, void *msg_callback_arg); 71 72 /* Change QLOG instance retrieval callback in use after instantiation. */ 73 void ossl_qtx_set_qlog_cb(OSSL_QTX *qtx, QLOG *(*get_qlog_cb)(void *arg), 74 void *get_qlog_cb_arg); 75 76 /* 77 * Secret Management 78 * ----------------- 79 */ 80 81 /* 82 * Provides a secret to the QTX, which arises due to an encryption level change. 83 * enc_level is a QUIC_ENC_LEVEL_* value. 84 * 85 * This function can be used to initialise the INITIAL encryption level, but you 86 * should not do so directly; see the utility function 87 * ossl_qrl_provide_initial_secret() instead, which can initialise the INITIAL 88 * encryption level of a QRX and QTX simultaneously without duplicating certain 89 * key derivation steps. 90 * 91 * You must call this function for a given EL before transmitting packets at 92 * that EL using this QTX, otherwise ossl_qtx_write_pkt will fail. 93 * 94 * suite_id is a QRL_SUITE_* value which determines the AEAD function used for 95 * the QTX. 96 * 97 * The secret passed is used directly to derive the "quic key", "quic iv" and 98 * "quic hp" values. 99 * 100 * secret_len is the length of the secret buffer in bytes. The buffer must be 101 * sized correctly to the chosen suite, else the function fails. 102 * 103 * This function can only be called once for a given EL, except for the INITIAL 104 * EL, as the INITIAL EL can need to be rekeyed if connection retry occurs. 105 * Subsequent calls for non-INITIAL ELs fail. Calls made after a corresponding 106 * call to ossl_qtx_discard_enc_level for a given EL also fail, including for 107 * the INITIAL EL. The secret for a non-INITIAL EL cannot be changed after it is 108 * set because QUIC has no facility for introducing additional key material 109 * after an EL is setup. (QUIC key updates generate new keys from existing key 110 * material and do not introduce new entropy into a connection's key material.) 111 * 112 * Returns 1 on success or 0 on failure. 113 */ 114 int ossl_qtx_provide_secret(OSSL_QTX *qtx, 115 uint32_t enc_level, 116 uint32_t suite_id, 117 EVP_MD *md, 118 const unsigned char *secret, 119 size_t secret_len); 120 121 /* 122 * Informs the QTX that it can now discard key material for a given EL. The QTX 123 * will no longer be able to generate packets at that EL. This function is 124 * idempotent and succeeds if the EL has already been discarded. 125 * 126 * Returns 1 on success and 0 on failure. 127 */ 128 int ossl_qtx_discard_enc_level(OSSL_QTX *qtx, uint32_t enc_level); 129 130 /* Returns 1 if the given encryption level is provisioned. */ 131 int ossl_qtx_is_enc_level_provisioned(OSSL_QTX *qtx, uint32_t enc_level); 132 133 /* 134 * Given the value ciphertext_len representing an encrypted packet payload 135 * length in bytes, determines how many plaintext bytes it will decrypt to. 136 * Returns 0 if the specified EL is not provisioned or ciphertext_len is too 137 * small. The result is written to *plaintext_len. 138 */ 139 int ossl_qtx_calculate_plaintext_payload_len(OSSL_QTX *qtx, uint32_t enc_level, 140 size_t ciphertext_len, 141 size_t *plaintext_len); 142 143 /* 144 * Given the value plaintext_len represented a plaintext packet payload length 145 * in bytes, determines how many ciphertext bytes it will encrypt to. The value 146 * output does not include packet headers. Returns 0 if the specified EL is not 147 * provisioned. The result is written to *ciphertext_len. 148 */ 149 int ossl_qtx_calculate_ciphertext_payload_len(OSSL_QTX *qtx, uint32_t enc_level, 150 size_t plaintext_len, 151 size_t *ciphertext_len); 152 153 uint32_t ossl_qrl_get_suite_cipher_tag_len(uint32_t suite_id); 154 155 156 /* 157 * Packet Transmission 158 * ------------------- 159 */ 160 161 struct ossl_qtx_pkt_st { 162 /* Logical packet header to be serialized. */ 163 QUIC_PKT_HDR *hdr; 164 165 /* 166 * iovecs expressing the logical packet payload buffer. Zero-length entries 167 * are permitted. 168 */ 169 const OSSL_QTX_IOVEC *iovec; 170 size_t num_iovec; 171 172 /* Destination address. Will be passed through to the BIO if non-NULL. */ 173 const BIO_ADDR *peer; 174 175 /* 176 * Local address (optional). Specify as non-NULL only if TX BIO 177 * has local address support enabled. 178 */ 179 const BIO_ADDR *local; 180 181 /* 182 * Logical PN. Used for encryption. This will automatically be encoded to 183 * hdr->pn, which need not be initialized. 184 */ 185 QUIC_PN pn; 186 187 /* Packet flags. Zero or more OSSL_QTX_PKT_FLAG_* values. */ 188 uint32_t flags; 189 }; 190 191 /* 192 * More packets will be written which should be coalesced into a single 193 * datagram; do not send this packet yet. To use this, set this flag for all 194 * packets but the final packet in a datagram, then send the final packet 195 * without this flag set. 196 * 197 * This flag is not a guarantee and the QTX may transmit immediately anyway if 198 * it is not possible to fit any more packets in the current datagram. 199 * 200 * If the caller change its mind and needs to cause a packet queued with 201 * COALESCE after having passed it to this function but without writing another 202 * packet, it should call ossl_qtx_flush_pkt(). 203 */ 204 #define OSSL_QTX_PKT_FLAG_COALESCE (1U << 0) 205 206 /* 207 * Writes a packet. 208 * 209 * *pkt need be valid only for the duration of the call to this function. 210 * 211 * pkt->hdr->data and pkt->hdr->len are unused. The payload buffer is specified 212 * via an array of OSSL_QTX_IOVEC structures. The API is designed to support 213 * single-copy transmission; data is copied from the iovecs as it is encrypted 214 * into an internal staging buffer for transmission. 215 * 216 * The function may modify and clobber pkt->hdr->data, pkt->hdr->len, 217 * pkt->hdr->key_phase and pkt->hdr->pn for its own internal use. No other 218 * fields of pkt or pkt->hdr will be modified. 219 * 220 * It is the callers responsibility to determine how long the PN field in the 221 * encoded packet should be by setting pkt->hdr->pn_len. This function takes 222 * care of the PN encoding. Set pkt->pn to the desired PN. 223 * 224 * Note that 1-RTT packets do not have a DCID Length field, therefore the DCID 225 * length must be understood contextually. This function assumes the caller 226 * knows what it is doing and will serialize a DCID of whatever length is given. 227 * It is the caller's responsibility to ensure it uses a consistent DCID length 228 * for communication with any given set of remote peers. 229 * 230 * The packet is queued regardless of whether it is able to be sent immediately. 231 * This enables packets to be batched and sent at once on systems which support 232 * system calls to send multiple datagrams in a single system call (see 233 * BIO_sendmmsg). To flush queued datagrams to the network, see 234 * ossl_qtx_flush_net(). 235 * 236 * Returns 1 on success or 0 on failure. 237 */ 238 int ossl_qtx_write_pkt(OSSL_QTX *qtx, const OSSL_QTX_PKT *pkt); 239 240 /* 241 * Finish any incomplete datagrams for transmission which were flagged for 242 * coalescing. If there is no current coalescing datagram, this is a no-op. 243 */ 244 void ossl_qtx_finish_dgram(OSSL_QTX *qtx); 245 246 /* 247 * (Attempt to) flush any datagrams which are queued for transmission. Note that 248 * this does not cancel coalescing; call ossl_qtx_finish_dgram() first if that 249 * is desired. The queue is drained into the OS's sockets as much as possible. 250 * To determine if there is still data to be sent after calling this function, 251 * use ossl_qtx_get_queue_len_bytes(). 252 * 253 * Returns one of the following values: 254 * 255 * QTX_FLUSH_NET_RES_OK 256 * Either no packets are currently queued for transmission, 257 * or at least one packet was successfully submitted. 258 * 259 * QTX_FLUSH_NET_RES_TRANSIENT_FAIL 260 * The underlying network write BIO indicated a transient error 261 * (e.g. buffers full). 262 * 263 * QTX_FLUSH_NET_RES_PERMANENT_FAIL 264 * Internal error (e.g. assertion or allocation error) 265 * or the underlying network write BIO indicated a non-transient 266 * error. 267 */ 268 #define QTX_FLUSH_NET_RES_OK 1 269 #define QTX_FLUSH_NET_RES_TRANSIENT_FAIL (-1) 270 #define QTX_FLUSH_NET_RES_PERMANENT_FAIL (-2) 271 272 int ossl_qtx_flush_net(OSSL_QTX *qtx); 273 274 /* 275 * Diagnostic function. If there is any datagram pending transmission, pops it 276 * and writes the details of the datagram as they would have been passed to 277 * *msg. Returns 1, or 0 if there are no datagrams pending. For test use only. 278 */ 279 int ossl_qtx_pop_net(OSSL_QTX *qtx, BIO_MSG *msg); 280 281 /* Returns number of datagrams which are fully-formed but not yet sent. */ 282 size_t ossl_qtx_get_queue_len_datagrams(OSSL_QTX *qtx); 283 284 /* 285 * Returns number of payload bytes across all datagrams which are fully-formed 286 * but not yet sent. Does not count any incomplete coalescing datagram. 287 */ 288 size_t ossl_qtx_get_queue_len_bytes(OSSL_QTX *qtx); 289 290 /* 291 * Returns number of bytes in the current coalescing datagram, or 0 if there is 292 * no current coalescing datagram. Returns 0 after a call to 293 * ossl_qtx_finish_dgram(). 294 */ 295 size_t ossl_qtx_get_cur_dgram_len_bytes(OSSL_QTX *qtx); 296 297 /* 298 * Returns number of queued coalesced packets which have not been put into a 299 * datagram yet. If this is non-zero, ossl_qtx_flush_pkt() needs to be called. 300 */ 301 size_t ossl_qtx_get_unflushed_pkt_count(OSSL_QTX *qtx); 302 303 /* 304 * Change the BIO being used by the QTX. May be NULL if actual transmission is 305 * not currently required. Does not up-ref the BIO; the caller is responsible 306 * for ensuring the lifetime of the BIO exceeds the lifetime of the QTX. 307 */ 308 void ossl_qtx_set_bio(OSSL_QTX *qtx, BIO *bio); 309 310 /* Changes the MDPL. */ 311 int ossl_qtx_set_mdpl(OSSL_QTX *qtx, size_t mdpl); 312 313 /* Retrieves the current MDPL. */ 314 size_t ossl_qtx_get_mdpl(OSSL_QTX *qtx); 315 316 317 /* 318 * Key Update 319 * ---------- 320 * 321 * For additional discussion of key update considerations, see QRX header file. 322 */ 323 324 /* 325 * Triggers a key update. The key update will be started by inverting the Key 326 * Phase bit of the next packet transmitted; no key update occurs until the next 327 * packet is transmitted. Thus, this function should generally be called 328 * immediately before queueing the next packet. 329 * 330 * There are substantial requirements imposed by RFC 9001 on under what 331 * circumstances a key update can be initiated. The caller is responsible for 332 * meeting most of these requirements. For example, this function cannot be 333 * called too soon after a previous key update has occurred. Key updates also 334 * cannot be initiated until the 1-RTT encryption level is reached. 335 * 336 * As a sanity check, this function will fail and return 0 if the non-1RTT 337 * encryption levels have not yet been dropped. 338 * 339 * The caller may decide itself to initiate a key update, but it also MUST 340 * initiate a key update where it detects that the peer has initiated a key 341 * update. The caller is responsible for initiating a TX key update by calling 342 * this function in this circumstance; thus, the caller is responsible for 343 * coupling the RX and TX QUIC record layers in this way. 344 */ 345 int ossl_qtx_trigger_key_update(OSSL_QTX *qtx); 346 347 348 /* 349 * Key Expiration 350 * -------------- 351 */ 352 353 /* 354 * Returns the number of packets which have been encrypted for transmission with 355 * the current set of TX keys (the current "TX key epoch"). Reset to zero after 356 * a key update and incremented for each packet queued. If enc_level is not 357 * valid or relates to an EL which is not currently available, returns 358 * UINT64_MAX. 359 */ 360 uint64_t ossl_qtx_get_cur_epoch_pkt_count(OSSL_QTX *qtx, uint32_t enc_level); 361 362 /* 363 * Returns the maximum number of packets which the record layer will permit to 364 * be encrypted using the current set of TX keys. If this limit is reached (that 365 * is, if the counter returned by ossl_qrx_tx_get_cur_epoch_pkt_count() reaches 366 * this value), as a safety measure, the QTX will not permit any further packets 367 * to be queued. All calls to ossl_qrx_write_pkt that try to send packets of a 368 * kind which need to be encrypted will fail. It is not possible to recover from 369 * this condition and the QTX must then be destroyed; therefore, callers should 370 * ensure they always trigger a key update well in advance of reaching this 371 * limit. 372 * 373 * The value returned by this function is based on the ciphersuite configured 374 * for the given encryption level. If keys have not been provisioned for the 375 * specified enc_level or the enc_level argument is invalid, this function 376 * returns UINT64_MAX, which is not a valid value. Note that it is not possible 377 * to perform a key update at any encryption level other than 1-RTT, therefore 378 * if this limit is reached at earlier encryption levels (which should not be 379 * possible) the connection must be terminated. Since this condition precludes 380 * the transmission of further packets, the only possible signalling of such an 381 * error condition to a peer is a Stateless Reset packet. 382 */ 383 uint64_t ossl_qtx_get_max_epoch_pkt_count(OSSL_QTX *qtx, uint32_t enc_level); 384 385 /* 386 * Get the 1-RTT EL key epoch number for the QTX. This is intended for 387 * diagnostic purposes. Returns 0 if 1-RTT EL is not provisioned yet. 388 */ 389 uint64_t ossl_qtx_get_key_epoch(OSSL_QTX *qtx); 390 391 # endif 392 393 #endif 394
