]>
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. | |
741170be HL |
214 | * |
215 | * Usually the ossl_quic_channel_raise_protocol_error() function should be used. | |
216 | * The ossl_quic_channel_raise_protocol_error_loc() function can be used | |
217 | * directly for passing through existing call site information from an existing | |
218 | * error. | |
f538b421 | 219 | */ |
741170be HL |
220 | void ossl_quic_channel_raise_protocol_error_loc(QUIC_CHANNEL *ch, |
221 | uint64_t error_code, | |
222 | uint64_t frame_type, | |
223 | const char *reason, | |
7a2bb210 | 224 | ERR_STATE *err_state, |
741170be HL |
225 | const char *src_file, |
226 | int src_line, | |
227 | const char *src_func); | |
228 | ||
229 | #define ossl_quic_channel_raise_protocol_error(ch, error_code, frame_type, reason) \ | |
230 | ossl_quic_channel_raise_protocol_error_loc((ch), (error_code), \ | |
231 | (frame_type), \ | |
232 | (reason), \ | |
7a2bb210 | 233 | NULL, \ |
741170be HL |
234 | OPENSSL_FILE, \ |
235 | OPENSSL_LINE, \ | |
236 | OPENSSL_FUNC) | |
237 | ||
7a2bb210 HL |
238 | #define ossl_quic_channel_raise_protocol_error_state(ch, error_code, frame_type, reason, state) \ |
239 | ossl_quic_channel_raise_protocol_error_loc((ch), (error_code), \ | |
240 | (frame_type), \ | |
241 | (reason), \ | |
242 | (state), \ | |
243 | OPENSSL_FILE, \ | |
244 | OPENSSL_LINE, \ | |
245 | OPENSSL_FUNC) | |
246 | ||
247 | ||
5c3474ea TM |
248 | /* |
249 | * Returns 1 if permanent net error was detected on the QUIC_CHANNEL, | |
250 | * 0 otherwise. | |
251 | */ | |
252 | int ossl_quic_channel_net_error(QUIC_CHANNEL *ch); | |
f538b421 | 253 | |
9c3ea4e1 TM |
254 | /* Restore saved error state (best effort) */ |
255 | void ossl_quic_channel_restore_err_state(QUIC_CHANNEL *ch); | |
256 | ||
f538b421 HL |
257 | /* For RXDP use. */ |
258 | void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch, | |
259 | OSSL_QUIC_FRAME_CONN_CLOSE *f); | |
eff04652 TM |
260 | void ossl_quic_channel_on_new_conn_id(QUIC_CHANNEL *ch, |
261 | OSSL_QUIC_FRAME_NEW_CONN_ID *f); | |
f538b421 HL |
262 | |
263 | /* | |
264 | * Queries and Accessors | |
265 | * ===================== | |
266 | */ | |
267 | ||
268 | /* Gets the reactor which can be used to tick/poll on the channel. */ | |
269 | QUIC_REACTOR *ossl_quic_channel_get_reactor(QUIC_CHANNEL *ch); | |
270 | ||
271 | /* Gets the QSM used with the channel. */ | |
272 | QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch); | |
273 | ||
274 | /* Gets the statistics manager used with the channel. */ | |
275 | OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch); | |
276 | ||
277 | /* | |
278 | * Gets/sets the current peer address. Generally this should be used before | |
279 | * starting a channel in client mode. | |
280 | */ | |
281 | int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL *ch, BIO_ADDR *peer_addr); | |
282 | int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL *ch, const BIO_ADDR *peer_addr); | |
283 | ||
284 | /* Gets/sets the underlying network read and write BIOs. */ | |
285 | BIO *ossl_quic_channel_get_net_rbio(QUIC_CHANNEL *ch); | |
286 | BIO *ossl_quic_channel_get_net_wbio(QUIC_CHANNEL *ch); | |
d1ac77b1 HL |
287 | int ossl_quic_channel_set_net_rbio(QUIC_CHANNEL *ch, BIO *net_rbio); |
288 | int ossl_quic_channel_set_net_wbio(QUIC_CHANNEL *ch, BIO *net_wbio); | |
f538b421 HL |
289 | |
290 | /* | |
291 | * Returns an existing stream by stream ID. Returns NULL if the stream does not | |
292 | * exist. | |
293 | */ | |
294 | QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch, | |
295 | uint64_t stream_id); | |
296 | ||
297 | /* Returns 1 if channel is terminating or terminated. */ | |
c12e1113 | 298 | int ossl_quic_channel_is_term_any(const QUIC_CHANNEL *ch); |
723cbe8a HL |
299 | const QUIC_TERMINATE_CAUSE * |
300 | ossl_quic_channel_get_terminate_cause(const QUIC_CHANNEL *ch); | |
c12e1113 | 301 | int ossl_quic_channel_is_terminated(const QUIC_CHANNEL *ch); |
f538b421 HL |
302 | int ossl_quic_channel_is_active(const QUIC_CHANNEL *ch); |
303 | int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL *ch); | |
ce8f20b6 | 304 | int ossl_quic_channel_is_handshake_confirmed(const QUIC_CHANNEL *ch); |
f538b421 | 305 | |
553a4e00 HL |
306 | QUIC_DEMUX *ossl_quic_channel_get0_demux(QUIC_CHANNEL *ch); |
307 | ||
d03fe5de MC |
308 | SSL *ossl_quic_channel_get0_ssl(QUIC_CHANNEL *ch); |
309 | ||
fb2245c4 | 310 | /* |
4847599b HL |
311 | * Retrieves a pointer to the channel mutex which was provided at the time the |
312 | * channel was instantiated. In order to allow locks to be acquired and released | |
313 | * with the correct granularity, it is the caller's responsibility to ensure | |
314 | * this lock is held for write while calling any QUIC_CHANNEL method, except for | |
315 | * methods explicitly designed otherwise. | |
fb2245c4 HL |
316 | * |
317 | * This method is thread safe and does not require prior locking. It can also be | |
4847599b HL |
318 | * called while the lock is already held. Note that this is simply a convenience |
319 | * function to access the mutex which was passed to the channel at instantiation | |
320 | * time; it does not belong to the channel but rather is presumed to belong to | |
321 | * the owner of the channel. | |
fb2245c4 | 322 | */ |
ffce2946 | 323 | CRYPTO_MUTEX *ossl_quic_channel_get_mutex(QUIC_CHANNEL *ch); |
fb2245c4 | 324 | |
2dbc39de HL |
325 | /* |
326 | * Creates a new locally-initiated stream in the stream mapper, choosing an | |
327 | * appropriate stream ID. If is_uni is 1, creates a unidirectional stream, else | |
f20fdd16 | 328 | * creates a bidirectional stream. Returns NULL on failure. |
2dbc39de | 329 | */ |
f20fdd16 HL |
330 | QUIC_STREAM *ossl_quic_channel_new_stream_local(QUIC_CHANNEL *ch, int is_uni); |
331 | ||
332 | /* | |
333 | * Creates a new remotely-initiated stream in the stream mapper. The stream ID | |
334 | * is used to confirm the initiator and determine the stream type. The stream is | |
335 | * automatically added to the QSM's accept queue. A pointer to the stream is | |
336 | * also returned. Returns NULL on failure. | |
337 | */ | |
338 | QUIC_STREAM *ossl_quic_channel_new_stream_remote(QUIC_CHANNEL *ch, | |
339 | uint64_t stream_id); | |
2dbc39de | 340 | |
995ff282 HL |
341 | /* |
342 | * Configures incoming stream auto-reject. If enabled, incoming streams have | |
343 | * both their sending and receiving parts automatically rejected using | |
344 | * STOP_SENDING and STREAM_RESET frames. aec is the application error | |
345 | * code to be used for those frames. | |
346 | */ | |
347 | void ossl_quic_channel_set_incoming_stream_auto_reject(QUIC_CHANNEL *ch, | |
348 | int enable, | |
349 | uint64_t aec); | |
350 | ||
351 | /* | |
352 | * Causes the channel to reject the sending and receiving parts of a stream, | |
353 | * as though autorejected. Can be used if a stream has already been | |
354 | * accepted. | |
355 | */ | |
356 | void ossl_quic_channel_reject_stream(QUIC_CHANNEL *ch, QUIC_STREAM *qs); | |
357 | ||
bbc97540 TM |
358 | /* Replace local connection ID in TXP and DEMUX for testing purposes. */ |
359 | int ossl_quic_channel_replace_local_cid(QUIC_CHANNEL *ch, | |
360 | const QUIC_CONN_ID *conn_id); | |
361 | ||
5cf99b40 MC |
362 | /* Setters for the msg_callback and msg_callback_arg */ |
363 | void ossl_quic_channel_set_msg_callback(QUIC_CHANNEL *ch, | |
364 | ossl_msg_cb msg_callback, | |
c2786c8e | 365 | SSL *msg_callback_ssl); |
5cf99b40 MC |
366 | void ossl_quic_channel_set_msg_callback_arg(QUIC_CHANNEL *ch, |
367 | void *msg_callback_arg); | |
368 | ||
16f3b542 HL |
369 | /* Testing use only - sets a TXKU threshold packet count override value. */ |
370 | void ossl_quic_channel_set_txku_threshold_override(QUIC_CHANNEL *ch, | |
371 | uint64_t tx_pkt_threshold); | |
372 | ||
373 | /* Testing use only - gets current 1-RTT key epochs for QTX and QRX. */ | |
374 | uint64_t ossl_quic_channel_get_tx_key_epoch(QUIC_CHANNEL *ch); | |
375 | uint64_t ossl_quic_channel_get_rx_key_epoch(QUIC_CHANNEL *ch); | |
376 | ||
2525109f HL |
377 | /* Artificially trigger a spontaneous TXKU if possible. */ |
378 | int ossl_quic_channel_trigger_txku(QUIC_CHANNEL *ch); | |
9280d26a | 379 | int ossl_quic_channel_has_pending(const QUIC_CHANNEL *ch); |
2525109f | 380 | |
9ff3a99e HL |
381 | /* Force transmission of an ACK-eliciting packet. */ |
382 | int ossl_quic_channel_ping(QUIC_CHANNEL *ch); | |
383 | ||
03b38595 HL |
384 | /* For testing use. While enabled, ticking is not performed. */ |
385 | void ossl_quic_channel_set_inhibit_tick(QUIC_CHANNEL *ch, int inhibit); | |
386 | ||
17340e87 HL |
387 | /* |
388 | * These queries exist for diagnostic purposes only. They may roll over. | |
389 | * Do not rely on them for non-testing purposes. | |
390 | */ | |
391 | uint16_t ossl_quic_channel_get_diag_num_rx_ack(QUIC_CHANNEL *ch); | |
392 | ||
6292519c HL |
393 | # endif |
394 | ||
f538b421 | 395 | #endif |