]>
Commit | Line | Data |
---|---|---|
f538b421 HL |
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_CHANNEL_H | |
11 | # define OSSL_QUIC_CHANNEL_H | |
12 | ||
13 | # include <openssl/ssl.h> | |
14 | # include "internal/quic_types.h" | |
15 | # include "internal/quic_stream_map.h" | |
16 | # include "internal/quic_reactor.h" | |
17 | # include "internal/quic_statm.h" | |
18 | # include "internal/time.h" | |
ffce2946 | 19 | # include "internal/thread.h" |
f538b421 | 20 | |
6292519c HL |
21 | # ifndef OPENSSL_NO_QUIC |
22 | ||
f538b421 HL |
23 | /* |
24 | * QUIC Channel | |
25 | * ============ | |
26 | * | |
27 | * A QUIC channel (QUIC_CHANNEL) is an object which binds together all of the | |
28 | * various pieces of QUIC into a single top-level object, and handles connection | |
29 | * state which is not specific to the client or server roles. In particular, it | |
30 | * is strictly separated from the libssl front end I/O API personality layer, | |
31 | * and is not an SSL object. | |
32 | * | |
33 | * The name QUIC_CHANNEL is chosen because QUIC_CONNECTION is already in use, | |
34 | * but functionally these relate to the same thing (a QUIC connection). The use | |
35 | * of two separate objects ensures clean separation between the API personality | |
36 | * layer and common code for handling connections, and between the functionality | |
37 | * which is specific to clients and which is specific to servers, and the | |
38 | * functionality which is common to both. | |
39 | * | |
40 | * The API personality layer provides SSL objects (e.g. a QUIC_CONNECTION) which | |
41 | * consume a QUIC channel and implement a specific public API. Things which are | |
42 | * handled by the API personality layer include emulation of blocking semantics, | |
43 | * handling of SSL object mode flags like non-partial write mode, etc. | |
44 | * | |
45 | * Where the QUIC_CHANNEL is used in a server role, there is one QUIC_CHANNEL | |
46 | * per connection. In the future a QUIC Channel Manager will probably be defined | |
47 | * to handle ownership of resources which are shared between connections (e.g. | |
48 | * demuxers). Since we only use server-side functionality for dummy test servers | |
49 | * for now, which only need to handle one connection at a time, this is not | |
50 | * currently modelled. | |
fb2245c4 HL |
51 | * |
52 | * Synchronisation | |
53 | * --------------- | |
54 | * | |
55 | * To support thread assisted mode, QUIC_CHANNEL can be used by multiple | |
56 | * threads. **It is the caller's responsibility to ensure that the QUIC_CHANNEL | |
57 | * is only accessed (whether via its methods or via direct access to its state) | |
4847599b HL |
58 | * while the channel mutex is held**, except for methods explicitly marked as |
59 | * not requiring prior locking. This is an unchecked precondition. | |
60 | * | |
61 | * The instantiator of the channel is responsible for providing a suitable | |
62 | * mutex which then serves as the channel mutex; see QUIC_CHANNEL_ARGS. | |
f538b421 HL |
63 | */ |
64 | ||
a8489257 HL |
65 | /* |
66 | * The function does not acquire the channel mutex and assumes it is already | |
67 | * held by the calling thread. | |
68 | * | |
69 | * Any function tagged with this has the following precondition: | |
70 | * | |
71 | * Precondition: must hold channel mutex (unchecked) | |
72 | */ | |
d7b1fadd | 73 | # define QUIC_NEEDS_LOCK |
a8489257 HL |
74 | |
75 | /* | |
76 | * The function acquires the channel mutex and releases it before returning in | |
77 | * all circumstances. | |
78 | * | |
79 | * Any function tagged with this has the following precondition and | |
80 | * postcondition: | |
81 | * | |
82 | * Precondition: must not hold channel mutex (unchecked) | |
83 | * Postcondition: channel mutex is not held (by calling thread) | |
a8489257 | 84 | */ |
d7b1fadd | 85 | # define QUIC_TAKES_LOCK |
a8489257 | 86 | |
8b7be3aa HL |
87 | /* |
88 | * The function acquires the channel mutex and leaves it acquired | |
89 | * when returning success. | |
90 | * | |
91 | * Any function tagged with this has the following precondition and | |
92 | * postcondition: | |
93 | * | |
94 | * Precondition: must not hold channel mutex (unchecked) | |
95 | * Postcondition: channel mutex is held by calling thread | |
96 | * or function returned failure | |
97 | */ | |
98 | # define QUIC_ACQUIRES_LOCK | |
99 | ||
d7b1fadd HL |
100 | # define QUIC_TODO_LOCK |
101 | ||
6292519c HL |
102 | # define QUIC_CHANNEL_STATE_IDLE 0 |
103 | # define QUIC_CHANNEL_STATE_ACTIVE 1 | |
104 | # define QUIC_CHANNEL_STATE_TERMINATING_CLOSING 2 | |
105 | # define QUIC_CHANNEL_STATE_TERMINATING_DRAINING 3 | |
106 | # define QUIC_CHANNEL_STATE_TERMINATED 4 | |
f538b421 HL |
107 | |
108 | typedef struct quic_channel_args_st { | |
4847599b HL |
109 | OSSL_LIB_CTX *libctx; |
110 | const char *propq; | |
111 | int is_server; | |
112 | SSL *tls; | |
113 | ||
114 | /* | |
115 | * This must be a mutex the lifetime of which will exceed that of the | |
116 | * channel. The instantiator of the channel is responsible for providing a | |
117 | * mutex as this makes it easier to handle instantiation and teardown of | |
118 | * channels in situations potentially requiring locking. | |
ffce2946 HL |
119 | * |
120 | * Note that this is a MUTEX not a RWLOCK as it needs to be an OS mutex for | |
121 | * compatibility with an OS's condition variable wait API, whereas RWLOCK | |
122 | * may, depending on the build configuration, be implemented using an OS's | |
123 | * mutex primitive or using its RW mutex primitive. | |
4847599b | 124 | */ |
ffce2946 | 125 | CRYPTO_MUTEX *mutex; |
b212d554 HL |
126 | |
127 | /* | |
128 | * Optional function pointer to use to retrieve the current time. If NULL, | |
129 | * ossl_time_now() is used. | |
130 | */ | |
131 | OSSL_TIME (*now_cb)(void *arg); | |
132 | void *now_cb_arg; | |
f538b421 HL |
133 | } QUIC_CHANNEL_ARGS; |
134 | ||
135 | typedef struct quic_channel_st QUIC_CHANNEL; | |
136 | ||
149a8e6c MC |
137 | /* Represents the cause for a connection's termination. */ |
138 | typedef struct quic_terminate_cause_st { | |
139 | /* | |
140 | * If we are in a TERMINATING or TERMINATED state, this is the error code | |
141 | * associated with the error. This field is valid iff we are in the | |
142 | * TERMINATING or TERMINATED states. | |
143 | */ | |
144 | uint64_t error_code; | |
145 | ||
146 | /* | |
147 | * If terminate_app is set and this is nonzero, this is the frame type which | |
148 | * caused the connection to be terminated. | |
149 | */ | |
150 | uint64_t frame_type; | |
151 | ||
152 | /* Is this error code in the transport (0) or application (1) space? */ | |
153 | unsigned int app : 1; | |
154 | ||
155 | /* | |
156 | * If set, the cause of the termination is a received CONNECTION_CLOSE | |
157 | * frame. Otherwise, we decided to terminate ourselves and sent a | |
158 | * CONNECTION_CLOSE frame (regardless of whether the peer later also sends | |
159 | * one). | |
160 | */ | |
161 | unsigned int remote : 1; | |
162 | } QUIC_TERMINATE_CAUSE; | |
163 | ||
164 | ||
f538b421 HL |
165 | /* |
166 | * Create a new QUIC channel using the given arguments. The argument structure | |
167 | * does not need to remain allocated. Returns NULL on failure. | |
168 | */ | |
169 | QUIC_CHANNEL *ossl_quic_channel_new(const QUIC_CHANNEL_ARGS *args); | |
170 | ||
171 | /* No-op if ch is NULL. */ | |
172 | void ossl_quic_channel_free(QUIC_CHANNEL *ch); | |
173 | ||
14e31409 MC |
174 | /* Set mutator callbacks for test framework support */ |
175 | int ossl_quic_channel_set_mutator(QUIC_CHANNEL *ch, | |
176 | ossl_mutate_packet_cb mutatecb, | |
177 | ossl_finish_mutate_cb finishmutatecb, | |
178 | void *mutatearg); | |
179 | ||
f538b421 HL |
180 | /* |
181 | * Connection Lifecycle Events | |
182 | * =========================== | |
183 | * | |
184 | * Various events that can be raised on the channel by other parts of the QUIC | |
185 | * implementation. Some of these are suitable for general use by any part of the | |
186 | * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very | |
187 | * specific use by particular components only (e.g. | |
188 | * ossl_quic_channel_on_handshake_confirmed). | |
f538b421 HL |
189 | */ |
190 | ||
191 | /* | |
192 | * To be used by a QUIC connection. Starts the channel. For a client-mode | |
193 | * channel, this starts sending the first handshake layer message, etc. Can only | |
194 | * be called in the idle state; successive calls are ignored. | |
195 | */ | |
196 | int ossl_quic_channel_start(QUIC_CHANNEL *ch); | |
197 | ||
198 | /* Start a locally initiated connection shutdown. */ | |
e8043229 | 199 | void ossl_quic_channel_local_close(QUIC_CHANNEL *ch, uint64_t app_error_code); |
f538b421 HL |
200 | |
201 | /* | |
202 | * Called when the handshake is confirmed. | |
203 | */ | |
204 | int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL *ch); | |
205 | ||
206 | /* | |
207 | * Raises a protocol error. This is intended to be the universal call suitable | |
208 | * for handling of all peer-triggered protocol violations or errors detected by | |
209 | * us. We specify a QUIC transport-scope error code and optional frame type | |
210 | * which was responsible. If a frame type is not applicable, specify zero. The | |
211 | * reason string is not currently handled, but should be a string of static | |
212 | * storage duration. If the connection has already terminated due to a previous | |
213 | * protocol error, this is a no-op; first error wins. | |
214 | */ | |
215 | void ossl_quic_channel_raise_protocol_error(QUIC_CHANNEL *ch, | |
216 | uint64_t error_code, | |
217 | uint64_t frame_type, | |
218 | const char *reason); | |
219 | ||
220 | /* For RXDP use. */ | |
221 | void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch, | |
222 | OSSL_QUIC_FRAME_CONN_CLOSE *f); | |
eff04652 TM |
223 | void ossl_quic_channel_on_new_conn_id(QUIC_CHANNEL *ch, |
224 | OSSL_QUIC_FRAME_NEW_CONN_ID *f); | |
f538b421 HL |
225 | |
226 | /* | |
227 | * Queries and Accessors | |
228 | * ===================== | |
229 | */ | |
230 | ||
231 | /* Gets the reactor which can be used to tick/poll on the channel. */ | |
232 | QUIC_REACTOR *ossl_quic_channel_get_reactor(QUIC_CHANNEL *ch); | |
233 | ||
234 | /* Gets the QSM used with the channel. */ | |
235 | QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch); | |
236 | ||
237 | /* Gets the statistics manager used with the channel. */ | |
238 | OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch); | |
239 | ||
240 | /* | |
241 | * Gets/sets the current peer address. Generally this should be used before | |
242 | * starting a channel in client mode. | |
243 | */ | |
244 | int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL *ch, BIO_ADDR *peer_addr); | |
245 | int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL *ch, const BIO_ADDR *peer_addr); | |
246 | ||
247 | /* Gets/sets the underlying network read and write BIOs. */ | |
248 | BIO *ossl_quic_channel_get_net_rbio(QUIC_CHANNEL *ch); | |
249 | BIO *ossl_quic_channel_get_net_wbio(QUIC_CHANNEL *ch); | |
d1ac77b1 HL |
250 | int ossl_quic_channel_set_net_rbio(QUIC_CHANNEL *ch, BIO *net_rbio); |
251 | int ossl_quic_channel_set_net_wbio(QUIC_CHANNEL *ch, BIO *net_wbio); | |
f538b421 HL |
252 | |
253 | /* | |
254 | * Returns an existing stream by stream ID. Returns NULL if the stream does not | |
255 | * exist. | |
256 | */ | |
257 | QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch, | |
258 | uint64_t stream_id); | |
259 | ||
260 | /* Returns 1 if channel is terminating or terminated. */ | |
c12e1113 | 261 | int ossl_quic_channel_is_term_any(const QUIC_CHANNEL *ch); |
723cbe8a HL |
262 | const QUIC_TERMINATE_CAUSE * |
263 | ossl_quic_channel_get_terminate_cause(const QUIC_CHANNEL *ch); | |
c12e1113 MC |
264 | int ossl_quic_channel_is_terminating(const QUIC_CHANNEL *ch); |
265 | int ossl_quic_channel_is_terminated(const QUIC_CHANNEL *ch); | |
f538b421 HL |
266 | int ossl_quic_channel_is_active(const QUIC_CHANNEL *ch); |
267 | int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL *ch); | |
ce8f20b6 | 268 | int ossl_quic_channel_is_handshake_confirmed(const QUIC_CHANNEL *ch); |
f538b421 | 269 | |
553a4e00 HL |
270 | QUIC_DEMUX *ossl_quic_channel_get0_demux(QUIC_CHANNEL *ch); |
271 | ||
d03fe5de MC |
272 | SSL *ossl_quic_channel_get0_ssl(QUIC_CHANNEL *ch); |
273 | ||
fb2245c4 | 274 | /* |
4847599b HL |
275 | * Retrieves a pointer to the channel mutex which was provided at the time the |
276 | * channel was instantiated. In order to allow locks to be acquired and released | |
277 | * with the correct granularity, it is the caller's responsibility to ensure | |
278 | * this lock is held for write while calling any QUIC_CHANNEL method, except for | |
279 | * methods explicitly designed otherwise. | |
fb2245c4 HL |
280 | * |
281 | * This method is thread safe and does not require prior locking. It can also be | |
4847599b HL |
282 | * called while the lock is already held. Note that this is simply a convenience |
283 | * function to access the mutex which was passed to the channel at instantiation | |
284 | * time; it does not belong to the channel but rather is presumed to belong to | |
285 | * the owner of the channel. | |
fb2245c4 | 286 | */ |
ffce2946 | 287 | CRYPTO_MUTEX *ossl_quic_channel_get_mutex(QUIC_CHANNEL *ch); |
fb2245c4 | 288 | |
2dbc39de HL |
289 | /* |
290 | * Creates a new locally-initiated stream in the stream mapper, choosing an | |
291 | * appropriate stream ID. If is_uni is 1, creates a unidirectional stream, else | |
f20fdd16 | 292 | * creates a bidirectional stream. Returns NULL on failure. |
2dbc39de | 293 | */ |
f20fdd16 HL |
294 | QUIC_STREAM *ossl_quic_channel_new_stream_local(QUIC_CHANNEL *ch, int is_uni); |
295 | ||
296 | /* | |
297 | * Creates a new remotely-initiated stream in the stream mapper. The stream ID | |
298 | * is used to confirm the initiator and determine the stream type. The stream is | |
299 | * automatically added to the QSM's accept queue. A pointer to the stream is | |
300 | * also returned. Returns NULL on failure. | |
301 | */ | |
302 | QUIC_STREAM *ossl_quic_channel_new_stream_remote(QUIC_CHANNEL *ch, | |
303 | uint64_t stream_id); | |
2dbc39de | 304 | |
995ff282 HL |
305 | /* |
306 | * Configures incoming stream auto-reject. If enabled, incoming streams have | |
307 | * both their sending and receiving parts automatically rejected using | |
308 | * STOP_SENDING and STREAM_RESET frames. aec is the application error | |
309 | * code to be used for those frames. | |
310 | */ | |
311 | void ossl_quic_channel_set_incoming_stream_auto_reject(QUIC_CHANNEL *ch, | |
312 | int enable, | |
313 | uint64_t aec); | |
314 | ||
315 | /* | |
316 | * Causes the channel to reject the sending and receiving parts of a stream, | |
317 | * as though autorejected. Can be used if a stream has already been | |
318 | * accepted. | |
319 | */ | |
320 | void ossl_quic_channel_reject_stream(QUIC_CHANNEL *ch, QUIC_STREAM *qs); | |
321 | ||
bbc97540 TM |
322 | /* Replace local connection ID in TXP and DEMUX for testing purposes. */ |
323 | int ossl_quic_channel_replace_local_cid(QUIC_CHANNEL *ch, | |
324 | const QUIC_CONN_ID *conn_id); | |
325 | ||
5cf99b40 MC |
326 | /* Setters for the msg_callback and msg_callback_arg */ |
327 | void ossl_quic_channel_set_msg_callback(QUIC_CHANNEL *ch, | |
328 | ossl_msg_cb msg_callback, | |
c2786c8e | 329 | SSL *msg_callback_ssl); |
5cf99b40 MC |
330 | void ossl_quic_channel_set_msg_callback_arg(QUIC_CHANNEL *ch, |
331 | void *msg_callback_arg); | |
332 | ||
16f3b542 HL |
333 | /* Testing use only - sets a TXKU threshold packet count override value. */ |
334 | void ossl_quic_channel_set_txku_threshold_override(QUIC_CHANNEL *ch, | |
335 | uint64_t tx_pkt_threshold); | |
336 | ||
337 | /* Testing use only - gets current 1-RTT key epochs for QTX and QRX. */ | |
338 | uint64_t ossl_quic_channel_get_tx_key_epoch(QUIC_CHANNEL *ch); | |
339 | uint64_t ossl_quic_channel_get_rx_key_epoch(QUIC_CHANNEL *ch); | |
340 | ||
6292519c HL |
341 | # endif |
342 | ||
f538b421 | 343 | #endif |