2 * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
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
10 #ifndef OSSL_QUIC_RECORD_RX_H
11 # define OSSL_QUIC_RECORD_RX_H
13 # include <openssl/ssl.h>
14 # include "internal/quic_wire_pkt.h"
15 # include "internal/quic_types.h"
16 # include "internal/quic_record_util.h"
17 # include "internal/quic_demux.h"
19 # ifndef OPENSSL_NO_QUIC
22 * QUIC Record Layer - RX
23 * ======================
25 typedef struct ossl_qrx_st OSSL_QRX;
27 typedef struct ossl_qrx_args_st {
31 /* Demux to receive datagrams from. */
34 /* Length of connection IDs used in short-header packets in bytes. */
35 size_t short_conn_id_len;
38 * Maximum number of deferred datagrams buffered at any one time.
39 * Suggested value: 32.
43 /* Initial reference PN used for RX. */
44 QUIC_PN init_largest_pn[QUIC_PN_SPACE_NUM];
46 /* Initial key phase. For debugging use only; always 0 in real use. */
47 unsigned char init_key_phase_bit;
49 /* Message callback related arguments */
50 ossl_msg_cb msg_callback;
51 void *msg_callback_arg;
55 /* Instantiates a new QRX. */
56 OSSL_QRX *ossl_qrx_new(const OSSL_QRX_ARGS *args);
59 * Frees the QRX. All packets obtained using ossl_qrx_read_pkt must already
60 * have been released by calling ossl_qrx_release_pkt.
62 * You do not need to call ossl_qrx_remove_dst_conn_id first; this function will
63 * unregister the QRX from the demuxer for all registered destination connection
64 * IDs (DCIDs) automatically.
66 void ossl_qrx_free(OSSL_QRX *qrx);
74 * Adds a given DCID to the QRX. The QRX will register the DCID with the demuxer
75 * so that incoming packets with that DCID are passed to the given QRX. Multiple
76 * DCIDs may be associated with a QRX at any one time. You will need to add at
77 * least one DCID after instantiating the QRX. A zero-length DCID is a valid
78 * input to this function. This function fails if the DCID is already
81 * Returns 1 on success or 0 on error.
83 int ossl_qrx_add_dst_conn_id(OSSL_QRX *qrx,
84 const QUIC_CONN_ID *dst_conn_id);
87 * Remove a DCID previously registered with ossl_qrx_add_dst_conn_id. The DCID
88 * is unregistered from the demuxer. Fails if the DCID is not registered with
91 * Returns 1 on success or 0 on error.
93 int ossl_qrx_remove_dst_conn_id(OSSL_QRX *qrx,
94 const QUIC_CONN_ID *dst_conn_id);
100 * A QRX has several encryption levels (Initial, Handshake, 0-RTT, 1-RTT) and
101 * two directions (RX, TX). At any given time, key material is managed for each
102 * (EL, RX/TX) combination.
104 * Broadly, for a given (EL, RX/TX), the following state machine is applicable:
106 * WAITING_FOR_KEYS --[Provide]--> HAVE_KEYS --[Discard]--> | DISCARDED |
107 * \-------------------------------------[Discard]--> | |
109 * To transition the RX side of an EL from WAITING_FOR_KEYS to HAVE_KEYS, call
110 * ossl_qrx_provide_secret (for the INITIAL EL, use of
111 * ossl_quic_provide_initial_secret is recommended).
113 * Once keys have been provisioned for an EL, you call
114 * ossl_qrx_discard_enc_level to transition the EL to the DISCARDED state. You
115 * can also call this function to transition directly to the DISCARDED state
116 * even before any keys have been provisioned for that EL.
118 * The DISCARDED state is terminal for a given EL; you cannot provide a secret
119 * again for that EL after reaching it.
121 * Incoming packets cannot be processed and decrypted if they target an EL
122 * not in the HAVE_KEYS state. However, there is a distinction between
123 * the WAITING_FOR_KEYS and DISCARDED states:
125 * - In the WAITING_FOR_KEYS state, the QRX assumes keys for the given
126 * EL will eventually arrive. Therefore, if it receives any packet
127 * for an EL in this state, it buffers it and tries to process it
128 * again once the EL reaches HAVE_KEYS.
130 * - In the DISCARDED state, the QRX assumes no keys for the given
131 * EL will ever arrive again. If it receives any packet for an EL
132 * in this state, it is simply discarded.
134 * If the user wishes to instantiate a new QRX to replace an old one for
135 * whatever reason, for example to take over for an already established QUIC
136 * connection, it is important that all ELs no longer being used (i.e., INITIAL,
137 * 0-RTT, 1-RTT) are transitioned to the DISCARDED state. Otherwise, the QRX
138 * will assume that keys for these ELs will arrive in future, and will buffer
139 * any received packets for those ELs perpetually. This can be done by calling
140 * ossl_qrx_discard_enc_level for all non-1-RTT ELs immediately after
141 * instantiating the QRX.
143 * The INITIAL EL is not setup automatically when the QRX is instantiated. This
144 * allows the caller to instead discard it immediately after instantiation of
145 * the QRX if it is not needed, for example if the QRX is being instantiated to
146 * take over handling of an existing connection which has already passed the
147 * INITIAL phase. This avoids the unnecessary derivation of INITIAL keys where
148 * they are not needed. In the ordinary case, ossl_quic_provide_initial_secret
149 * should be called immediately after instantiation.
153 * Provides a secret to the QRX, which arises due to an encryption level change.
154 * enc_level is a QUIC_ENC_LEVEL_* value. To initialise the INITIAL encryption
155 * level, it is recommended to use ossl_quic_provide_initial_secret instead.
157 * You should seek to call this function for a given EL before packets of that
158 * EL arrive and are processed by the QRX. However, if packets have already
159 * arrived for a given EL, the QRX will defer processing of them and perform
160 * processing of them when this function is eventually called for the EL in
163 * suite_id is a QRL_SUITE_* value which determines the AEAD function used for
166 * The secret passed is used directly to derive the "quic key", "quic iv" and
169 * secret_len is the length of the secret buffer in bytes. The buffer must be
170 * sized correctly to the chosen suite, else the function fails.
172 * This function can only be called once for a given EL, except for the INITIAL
173 * EL, which can need rekeying when a connection retry occurs. Subsequent calls
174 * for non-INITIAL ELs fail, as do calls made after a corresponding call to
175 * ossl_qrx_discard_enc_level for that EL. The secret for a non-INITIAL EL
176 * cannot be changed after it is set because QUIC has no facility for
177 * introducing additional key material after an EL is setup. QUIC key updates
178 * are managed semi-automatically by the QRX but do require some caller handling
181 * md is for internal use and should be NULL.
183 * Returns 1 on success or 0 on failure.
185 int ossl_qrx_provide_secret(OSSL_QRX *qrx,
189 const unsigned char *secret,
193 * Informs the QRX that it can now discard key material for a given EL. The QRX
194 * will no longer be able to process incoming packets received at that
195 * encryption level. This function is idempotent and succeeds if the EL has
196 * already been discarded.
198 * Returns 1 on success and 0 on failure.
200 int ossl_qrx_discard_enc_level(OSSL_QRX *qrx, uint32_t enc_level);
207 /* Information about a received packet. */
208 typedef struct ossl_qrx_pkt_st {
210 * Points to a logical representation of the decoded QUIC packet header. The
211 * data and len fields point to the decrypted QUIC payload (i.e., to a
212 * sequence of zero or more (potentially malformed) frames to be decoded).
217 * Address the packet was received from. If this is not available for this
218 * packet, this field is NULL (but this can only occur for manually injected
221 const BIO_ADDR *peer;
224 * Local address the packet was sent to. If this is not available for this
225 * packet, this field is NULL.
227 const BIO_ADDR *local;
230 * This is the length of the datagram which contained this packet. Note that
231 * the datagram may have contained other packets than this. The intended use
232 * for this is so that the user can enforce minimum datagram sizes (e.g. for
233 * datagrams containing INITIAL packets), as required by RFC 9000.
237 /* The PN which was decoded for the packet, if the packet has a PN field. */
241 * Time the packet was received, or ossl_time_zero() if the demuxer is not
242 * using a now() function.
246 /* The QRX which was used to receive the packet. */
251 * Tries to read a new decrypted packet from the QRX.
253 * On success, *pkt points to a OSSL_QRX_PKT structure. The structure should be
254 * freed when no longer needed by calling ossl_qrx_pkt_release(). The structure
255 * is refcounted; to gain extra references, call ossl_qrx_pkt_up_ref(). This
256 * will cause a corresponding number of calls to ossl_qrx_pkt_release() to be
259 * The resources referenced by (*pkt)->hdr, (*pkt)->hdr->data and (*pkt)->peer
260 * have the same lifetime as *pkt.
262 * Returns 1 on success and 0 on failure.
264 int ossl_qrx_read_pkt(OSSL_QRX *qrx, OSSL_QRX_PKT **pkt);
267 * Decrement the reference count for the given packet and frees it if the
268 * reference count drops to zero. No-op if pkt is NULL.
270 void ossl_qrx_pkt_release(OSSL_QRX_PKT *pkt);
272 /* Increments the reference count for the given packet. */
273 void ossl_qrx_pkt_up_ref(OSSL_QRX_PKT *pkt);
276 * Returns 1 if there are any already processed (i.e. decrypted) packets waiting
277 * to be read from the QRX.
279 int ossl_qrx_processed_read_pending(OSSL_QRX *qrx);
282 * Returns 1 if there are any unprocessed (i.e. not yet decrypted) packets
283 * waiting to be processed by the QRX. These may or may not result in
284 * successfully decrypted packets once processed. This indicates whether
285 * unprocessed data is buffered by the QRX, not whether any data is available in
286 * a kernel socket buffer.
288 int ossl_qrx_unprocessed_read_pending(OSSL_QRX *qrx);
291 * Returns the number of UDP payload bytes received from the network so far
292 * since the last time this counter was cleared. If clear is 1, clears the
293 * counter and returns the old value.
295 * The intended use of this is to allow callers to determine how much credit to
296 * add to their anti-amplification budgets. This is reported separately instead
297 * of in the OSSL_QRX_PKT structure so that a caller can apply
298 * anti-amplification credit as soon as a datagram is received, before it has
299 * necessarily read all processed packets contained within that datagram from
302 uint64_t ossl_qrx_get_bytes_received(OSSL_QRX *qrx, int clear);
305 * Sets a callback which is called when a packet is received and being
306 * validated before being queued in the read queue. This is called before packet
307 * body decryption. pn_space is a QUIC_PN_SPACE_* value denoting which PN space
310 * If this callback returns 1, processing continues normally.
311 * If this callback returns 0, the packet is discarded.
313 * Other packets in the same datagram will still be processed where possible.
315 * The intended use for this function is to allow early validation of whether
316 * a PN is a potential duplicate before spending CPU time decrypting the
319 * The callback is optional and can be unset by passing NULL for cb.
320 * cb_arg is an opaque value passed to cb.
322 typedef int (ossl_qrx_early_validation_cb)(QUIC_PN pn, int pn_space,
325 int ossl_qrx_set_early_validation_cb(OSSL_QRX *qrx,
326 ossl_qrx_early_validation_cb *cb,
330 * Forcibly injects a URXE which has been issued by the DEMUX into the QRX for
331 * processing. This can be used to pass a received datagram to the QRX if it
332 * would not be correctly routed to the QRX via standard DCID-based routing; for
333 * example, when handling an incoming Initial packet which is attempting to
334 * establish a new connection.
336 void ossl_qrx_inject_urxe(OSSL_QRX *qrx, QUIC_URXE *e);
342 * Key update on the RX side is a largely but not entirely automatic process.
344 * Key update is initially triggered by receiving a 1-RTT packet with a
345 * different Key Phase value. This could be caused by an attacker in the network
346 * flipping random bits, therefore such a key update is tentative until the
347 * packet payload is successfully decrypted and authenticated by the AEAD with
348 * the 'next' keys. These 'next' keys then become the 'current' keys and the
349 * 'current' keys then become the 'previous' keys. The 'previous' keys must be
350 * kept around temporarily as some packets may still be in flight in the network
351 * encrypted with the old keys. If the old Key Phase value is X and the new Key
352 * Phase Value is Y (where obviously X != Y), this creates an ambiguity as any
353 * new packet received with a KP of X could either be an attempt to initiate yet
354 * another key update right after the last one, or an old packet encrypted
355 * before the key update.
357 * RFC 9001 provides some guidance on handling this issue:
360 * Three keys, disambiguation using packet numbers
362 * "A recovered PN that is lower than any PN from the current KP uses the
363 * previous packet protection keys; a recovered PN that is higher than any
364 * PN from the current KP requires use of the next packet protection
368 * Two keys and a timer
370 * "Alternatively, endpoints can retain only two sets of packet protection
371 * keys, swapping previous keys for next after enough time has passed to
372 * allow for reordering in the network. In this case, the KP bit alone can
373 * be used to select keys."
375 * Strategy 2 is more efficient (we can keep fewer cipher contexts around) and
376 * should cover all actually possible network conditions. It also allows a delay
377 * after we make the 'next' keys our 'current' keys before we generate new
378 * 'next' keys, which allows us to mitigate against malicious peers who try to
379 * initiate an excessive number of key updates.
381 * We therefore model the following state machine:
385 * _______________________________
387 * UNPROVISIONED --|----> NORMAL <----------\ |------> DISCARDED
398 * | \---------------| |
399 * |_______________________________|
402 * The RX starts (once a secret has been provisioned) in the NORMAL state. In
403 * the NORMAL state, the current expected value of the Key Phase bit is
404 * recorded. When a flipped Key Phase bit is detected, the RX attempts to
405 * decrypt and authenticate the received packet with the 'next' keys rather than
406 * the 'current' keys. If (and only if) this authentication is successful, we
407 * move to the UPDATING state. (An attacker in the network could flip
408 * the Key Phase bit randomly, so it is essential we do nothing until AEAD
409 * authentication is complete.)
411 * In the UPDATING state, we know a key update is occurring and record
412 * the new Key Phase bit value as the newly current value, but we still keep the
413 * old keys around so that we can still process any packets which were still in
414 * flight when the key update was initiated. In the UPDATING state, a
415 * Key Phase bit value different to the current expected value is treated not as
416 * the initiation of another key update, but a reference to our old keys.
418 * Eventually we will be reasonably sure we are not going to receive any more
419 * packets with the old keys. At this point, we can transition to the COOLDOWN
420 * state. This transition occurs automatically after a certain amount of time;
421 * RFC 9001 recommends it be the PTO interval, which relates to our RTT to the
422 * peer. The duration also SHOULD NOT exceed three times the PTO to assist with
425 * In the COOLDOWN phase, the old keys have been securely erased and only one
426 * set of keys can be used: the current keys. If a packet is received with a Key
427 * Phase bit value different to the current Key Phase Bit value, this is treated
428 * as a request for a Key Update, but this request is ignored and the packet is
429 * treated as malformed. We do this to allow mitigation against malicious peers
430 * trying to initiate an excessive number of Key Updates. The timeout for the
431 * transition from UPDATING to COOLDOWN is recommended as adequate for
432 * this purpose in itself by the RFC, so the normal additional timeout value for
433 * the transition from COOLDOWN to normal is zero (immediate transition).
435 * A summary of each state:
437 * Epoch Exp KP Uses Keys KS0 KS1 If Non-Expected KP Bit
438 * ----- ------ --------- ------ ----- ----------------------
439 * NORMAL 0 0 Keyset 0 Gen 0 Gen 1 → UPDATING
440 * UPDATING 1 1 Keyset 1 Gen 0 Gen 1 Use Keyset 0
441 * COOLDOWN 1 1 Keyset 1 Erased Gen 1 Ignore Packet (*)
443 * NORMAL 1 1 Keyset 1 Gen 2 Gen 1 → UPDATING
444 * UPDATING 2 0 Keyset 0 Gen 2 Gen 1 Use Keyset 1
445 * COOLDOWN 2 0 Keyset 0 Gen 2 Erased Ignore Packet (*)
447 * (*) Actually implemented by attempting to decrypt the packet with the
448 * wrong keys (which ultimately has the same outcome), as recommended
449 * by RFC 9001 to avoid creating timing channels.
451 * Note that the key material for the next key generation ("key epoch") is
452 * always kept in the NORMAL state (necessary to avoid side-channel attacks).
453 * This material is derived during the transition from COOLDOWN to NORMAL.
455 * Note that when a peer initiates a Key Update, we MUST also initiate a Key
456 * Update as per the RFC. The caller is responsible for detecting this condition
457 * and making the necessary calls to the TX side by detecting changes to the
458 * return value of ossl_qrx_get_key_epoch().
460 * The above states (NORMAL, UPDATING, COOLDOWN) can themselves be
461 * considered substates of the PROVISIONED state. Providing a secret to the QRX
462 * for an EL transitions from UNPROVISIONED, the initial state, to PROVISIONED
463 * (NORMAL). Dropping key material for an EL transitions from whatever the
464 * current substate of the PROVISIONED state is to the DISCARDED state, which is
465 * the terminal state.
467 * Note that non-1RTT ELs cannot undergo key update, therefore a non-1RTT EL is
468 * always in the NORMAL substate if it is in the PROVISIONED state.
472 * Return the current RX key epoch for the 1-RTT encryption level. This is
473 * initially zero and is incremented by one for every Key Update successfully
474 * signalled by the peer. If the 1-RTT EL has not yet been provisioned or has
475 * been discarded, returns UINT64_MAX.
477 * A necessary implication of this API is that the least significant bit of the
478 * returned value corresponds to the currently expected Key Phase bit, though
479 * callers are not anticipated to have any need of this information.
481 * It is not possible for the returned value to overflow, as a QUIC connection
482 * cannot support more than 2**62 packet numbers, and a connection must be
483 * terminated if this limit is reached.
485 * The caller should use this function to detect when the key epoch has changed
486 * and use it to initiate a key update on the TX side.
488 * The value returned by this function increments specifically at the transition
489 * from the NORMAL to the UPDATING state discussed above.
491 uint64_t ossl_qrx_get_key_epoch(OSSL_QRX *qrx);
494 * Sets an optional callback which will be called when the key epoch changes.
496 * The callback is optional and can be unset by passing NULL for cb.
497 * cb_arg is an opaque value passed to cb.
499 typedef void (ossl_qrx_key_update_cb)(void *arg);
501 int ossl_qrx_set_key_update_cb(OSSL_QRX *qrx,
502 ossl_qrx_key_update_cb *cb, void *cb_arg);
505 * Relates to the 1-RTT encryption level. The caller should call this after the
506 * UPDATING state is reached, after a timeout to be determined by the caller.
508 * This transitions from the UPDATING state to the COOLDOWN state (if
509 * still in the UPDATING state). If normal is 1, then transitions from
510 * the COOLDOWN state to the NORMAL state. Both transitions can be performed at
513 * If in the normal state, or if in the COOLDOWN state and normal is 0, this is
514 * a no-op and returns 1. Returns 0 if the 1-RTT EL has not been provisioned or
517 * It is essential that the caller call this within a few PTO intervals of a key
518 * update occurring (as detected by the caller in a call to
519 * ossl_qrx_key_get_key_epoch()), as otherwise the peer will not be able to
520 * perform a Key Update ever again.
522 int ossl_qrx_key_update_timeout(OSSL_QRX *qrx, int normal);
531 * Returns the number of seemingly forged packets which have been received by
532 * the QRX. If this value reaches the value returned by
533 * ossl_qrx_get_max_epoch_forged_pkt_count() for a given EL, all further
534 * received encrypted packets for that EL will be discarded without processing.
536 * Note that the forged packet limit is for the connection lifetime, thus it is
537 * not reset by a key update. It is suggested that the caller terminate the
538 * connection a reasonable margin before the limit is reached. However, the
539 * exact limit imposed does vary by EL due to the possibility that different ELs
540 * use different AEADs.
542 uint64_t ossl_qrx_get_cur_forged_pkt_count(OSSL_QRX *qrx);
545 * Returns the maximum number of forged packets which the record layer will
546 * permit to be verified using this QRX instance.
548 uint64_t ossl_qrx_get_max_forged_pkt_count(OSSL_QRX *qrx,