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_DEMUX_H
11 # define OSSL_QUIC_DEMUX_H
13 # include <openssl/ssl.h>
14 # include "internal/quic_types.h"
15 # include "internal/bio_addr.h"
16 # include "internal/time.h"
17 # include "internal/list.h"
23 * The QUIC connection demuxer is the entity responsible for receiving datagrams
24 * from the network via a datagram BIO. It parses packet headers to determine
25 * each packet's destination connection ID (DCID) and hands off processing of
26 * the packet to the correct QUIC Record Layer (QRL)'s RX side (known as the
29 * A QRX is instantiated per QUIC connection and contains the cryptographic
30 * resources needed to decrypt QUIC packets for that connection. Received
31 * datagrams are passed from the demuxer to the QRX via a callback registered
32 * for a specific DCID by the QRX; thus the demuxer has no specific knowledge of
33 * the QRX and is not coupled to it.
35 * A connection may have multiple connection IDs associated with it; a QRX
36 * handles this simply by registering multiple connection IDs with the demuxer
37 * via multiple register calls.
42 * Since the demuxer must handle the initial reception of datagrams from the OS,
43 * RX queue management for new, unprocessed datagrams is also handled by the
46 * The demuxer maintains a queue of Unprocessed RX Entries (URXEs), which store
47 * unprocessed (i.e., encrypted, unvalidated) data received from the network.
48 * The URXE queue is designed to allow multiple datagrams to be received in a
49 * single call to BIO_recvmmsg, where supported.
51 * One URXE is used per received datagram. Each datagram may contain multiple
52 * packets, however, this is not the demuxer's concern. QUIC prohibits different
53 * packets in the same datagram from containing different DCIDs; the demuxer
54 * only considers the DCID of the first packet in a datagram when deciding how
55 * to route a received datagram, and it is the responsibility of the QRX to
56 * enforce this rule. Packets other than the first packet in a datagram are not
57 * examined by the demuxer, and the demuxer does not perform validation of
58 * packet headers other than to the minimum extent necessary to extract the
59 * DCID; further parsing and validation of packet headers is the responsibility
62 * Rather than defining an opaque interface, the URXE structure internals
63 * are exposed. Since the demuxer is only exposed to other parts of the QUIC
64 * implementation internals, this poses no problem, and has a number of
67 * - Fields in the URXE can be allocated to support requirements in other
68 * components, like the QRX, which would otherwise have to allocate extra
69 * memory corresponding to each URXE.
71 * - Other components, like the QRX, can keep the URXE in queues of its own
72 * when it is not being managed by the demuxer.
77 * The URXE queue is maintained as a simple doubly-linked list. URXE entries are
78 * moved between different lists in their lifecycle (for example, from a free
79 * list to a pending list and vice versa). The buffer into which datagrams are
80 * received immediately follows this URXE header structure and is part of the
84 typedef struct quic_urxe_st QUIC_URXE;
86 /* Maximum number of packets we allow to exist in one datagram. */
87 #define QUIC_MAX_PKT_PER_URXE (sizeof(uint64_t) * 8)
90 OSSL_LIST_MEMBER(urxe, QUIC_URXE);
93 * The URXE data starts after this structure so we don't need a pointer.
94 * data_len stores the current length (i.e., the length of the received
95 * datagram) and alloc_len stores the allocation length. The URXE will be
96 * reallocated if we need a larger allocation than is available, though this
97 * should not be common as we will have a good idea of worst-case MTUs up
100 size_t data_len, alloc_len;
103 * Bitfields per packet. processed indicates the packet has been processed
104 * and must not be processed again, hpr_removed indicates header protection
105 * has already been removed. Used by QRX only; not used by the demuxer.
107 uint64_t processed, hpr_removed;
110 * Address of peer we received the datagram from, and the local interface
111 * address we received it on. If local address support is not enabled, local
114 BIO_ADDR peer, local;
117 * Time at which datagram was received (or ossl_time_zero()) if a now
118 * function was not provided).
123 * Used by the QRX to mark whether a datagram has been deferred. Used by the
124 * QRX only; not used by the demuxer.
129 /* Accessors for URXE buffer. */
130 static ossl_unused ossl_inline unsigned char *
131 ossl_quic_urxe_data(const QUIC_URXE *e)
133 return (unsigned char *)&e[1];
136 static ossl_unused ossl_inline unsigned char *
137 ossl_quic_urxe_data_end(const QUIC_URXE *e)
139 return ossl_quic_urxe_data(e) + e->data_len;
142 /* List structure tracking a queue of URXEs. */
143 DEFINE_LIST_OF(urxe, QUIC_URXE);
144 typedef OSSL_LIST(urxe) QUIC_URXE_LIST;
147 * List management helpers. These are used by the demuxer but can also be used
148 * by users of the demuxer to manage URXEs.
150 void ossl_quic_urxe_remove(QUIC_URXE_LIST *l, QUIC_URXE *e);
151 void ossl_quic_urxe_insert_head(QUIC_URXE_LIST *l, QUIC_URXE *e);
152 void ossl_quic_urxe_insert_tail(QUIC_URXE_LIST *l, QUIC_URXE *e);
154 /* Opaque type representing a demuxer. */
155 typedef struct quic_demux_st QUIC_DEMUX;
158 * Called when a datagram is received for a given connection ID.
160 * e is a URXE containing the datagram payload. It is permissible for the callee
161 * to mutate this buffer; once the demuxer calls this callback, it will never
162 * read the buffer again.
164 * The callee must arrange for ossl_quic_demux_release_urxe to be called on the URXE
165 * at some point in the future (this need not be before the callback returns).
167 * At the time the callback is made, the URXE will not be in any queue,
168 * therefore the callee can use the prev and next fields as it wishes.
170 typedef void (ossl_quic_demux_cb_fn)(QUIC_URXE *e, void *arg);
173 * Creates a new demuxer. The given BIO is used to receive datagrams from the
174 * network using BIO_recvmmsg. short_conn_id_len is the length of destination
175 * connection IDs used in RX'd packets; it must have the same value for all
176 * connections used on a socket. default_urxe_alloc_len is the buffer size to
177 * receive datagrams into; it should be a value large enough to contain any
178 * received datagram according to local MTUs, etc.
180 * now is an optional function used to determine the time a datagram was
181 * received. now_arg is an opaque argument passed to the function. If now is
182 * NULL, ossl_time_zero() is used as the datagram reception time.
184 QUIC_DEMUX *ossl_quic_demux_new(BIO *net_bio,
185 size_t short_conn_id_len,
186 size_t default_urxe_alloc_len,
187 OSSL_TIME (*now)(void *arg),
191 * Destroy a demuxer. All URXEs must have been released back to the demuxer
192 * before calling this. No-op if demux is NULL.
194 void ossl_quic_demux_free(QUIC_DEMUX *demux);
197 * Register a datagram handler callback for a connection ID.
199 * ossl_quic_demux_pump will call the specified function if it receives a datagram
200 * the first packet of which has the specified destination connection ID.
202 * It is assumed all packets in a datagram have the same destination connection
203 * ID (as QUIC mandates this), but it is the user's responsibility to check for
204 * this and reject subsequent packets in a datagram that violate this rule.
206 * dst_conn_id is a destination connection ID; it is copied and need not remain
207 * valid after this function returns.
209 * cb_arg is passed to cb when it is called. For information on the callback,
210 * see its typedef above.
212 * Only one handler can be set for a given connection ID. If a handler is
213 * already set for the given connection ID, returns 0.
215 * Returns 1 on success or 0 on failure.
217 int ossl_quic_demux_register(QUIC_DEMUX *demux,
218 const QUIC_CONN_ID *dst_conn_id,
219 ossl_quic_demux_cb_fn *cb,
223 * Unregisters any datagram handler callback set for the given connection ID.
224 * Fails if no handler is registered for the given connection ID.
226 * Returns 1 on success or 0 on failure.
228 int ossl_quic_demux_unregister(QUIC_DEMUX *demux,
229 const QUIC_CONN_ID *dst_conn_id);
232 * Unregisters any datagram handler callback from all connection IDs it is used
233 * for. cb and cb_arg must both match the values passed to
234 * ossl_quic_demux_register.
236 void ossl_quic_demux_unregister_by_cb(QUIC_DEMUX *demux,
237 ossl_quic_demux_cb_fn *cb,
241 * Releases a URXE back to the demuxer. No reference must be made to the URXE or
242 * its buffer after calling this function. The URXE must not be in any queue;
243 * that is, its prev and next pointers must be NULL.
245 void ossl_quic_demux_release_urxe(QUIC_DEMUX *demux,
249 * Process any unprocessed RX'd datagrams, by calling registered callbacks by
250 * connection ID, reading more datagrams from the BIO if necessary.
252 * Returns 1 on success or 0 on failure.
254 int ossl_quic_demux_pump(QUIC_DEMUX *demux);
257 * Artificially inject a packet into the demuxer for testing purposes. The
258 * buffer must not exceed the URXE size being used by the demuxer.
260 * If peer or local are NULL, their respective fields are zeroed in the injected
263 * Returns 1 on success or 0 on failure.
265 int ossl_quic_demux_inject(QUIC_DEMUX *demux,
266 const unsigned char *buf,
268 const BIO_ADDR *peer,
269 const BIO_ADDR *local);