]>
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; | |
63dfde87 MC |
133 | |
134 | /* Message callback related arguments */ | |
135 | ossl_msg_cb msg_callback; | |
136 | void *msg_callback_arg; | |
137 | SSL *msg_callback_s; | |
f538b421 HL |
138 | } QUIC_CHANNEL_ARGS; |
139 | ||
140 | typedef struct quic_channel_st QUIC_CHANNEL; | |
141 | ||
149a8e6c MC |
142 | /* Represents the cause for a connection's termination. */ |
143 | typedef struct quic_terminate_cause_st { | |
144 | /* | |
145 | * If we are in a TERMINATING or TERMINATED state, this is the error code | |
146 | * associated with the error. This field is valid iff we are in the | |
147 | * TERMINATING or TERMINATED states. | |
148 | */ | |
149 | uint64_t error_code; | |
150 | ||
151 | /* | |
152 | * If terminate_app is set and this is nonzero, this is the frame type which | |
153 | * caused the connection to be terminated. | |
154 | */ | |
155 | uint64_t frame_type; | |
156 | ||
157 | /* Is this error code in the transport (0) or application (1) space? */ | |
158 | unsigned int app : 1; | |
159 | ||
160 | /* | |
161 | * If set, the cause of the termination is a received CONNECTION_CLOSE | |
162 | * frame. Otherwise, we decided to terminate ourselves and sent a | |
163 | * CONNECTION_CLOSE frame (regardless of whether the peer later also sends | |
164 | * one). | |
165 | */ | |
166 | unsigned int remote : 1; | |
167 | } QUIC_TERMINATE_CAUSE; | |
168 | ||
169 | ||
f538b421 HL |
170 | /* |
171 | * Create a new QUIC channel using the given arguments. The argument structure | |
172 | * does not need to remain allocated. Returns NULL on failure. | |
173 | */ | |
174 | QUIC_CHANNEL *ossl_quic_channel_new(const QUIC_CHANNEL_ARGS *args); | |
175 | ||
176 | /* No-op if ch is NULL. */ | |
177 | void ossl_quic_channel_free(QUIC_CHANNEL *ch); | |
178 | ||
14e31409 MC |
179 | /* Set mutator callbacks for test framework support */ |
180 | int ossl_quic_channel_set_mutator(QUIC_CHANNEL *ch, | |
181 | ossl_mutate_packet_cb mutatecb, | |
182 | ossl_finish_mutate_cb finishmutatecb, | |
183 | void *mutatearg); | |
184 | ||
f538b421 HL |
185 | /* |
186 | * Connection Lifecycle Events | |
187 | * =========================== | |
188 | * | |
189 | * Various events that can be raised on the channel by other parts of the QUIC | |
190 | * implementation. Some of these are suitable for general use by any part of the | |
191 | * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very | |
192 | * specific use by particular components only (e.g. | |
193 | * ossl_quic_channel_on_handshake_confirmed). | |
f538b421 HL |
194 | */ |
195 | ||
196 | /* | |
197 | * To be used by a QUIC connection. Starts the channel. For a client-mode | |
198 | * channel, this starts sending the first handshake layer message, etc. Can only | |
199 | * be called in the idle state; successive calls are ignored. | |
200 | */ | |
201 | int ossl_quic_channel_start(QUIC_CHANNEL *ch); | |
202 | ||
203 | /* Start a locally initiated connection shutdown. */ | |
e8043229 | 204 | void ossl_quic_channel_local_close(QUIC_CHANNEL *ch, uint64_t app_error_code); |
f538b421 HL |
205 | |
206 | /* | |
207 | * Called when the handshake is confirmed. | |
208 | */ | |
209 | int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL *ch); | |
210 | ||
211 | /* | |
212 | * Raises a protocol error. This is intended to be the universal call suitable | |
213 | * for handling of all peer-triggered protocol violations or errors detected by | |
214 | * us. We specify a QUIC transport-scope error code and optional frame type | |
215 | * which was responsible. If a frame type is not applicable, specify zero. The | |
216 | * reason string is not currently handled, but should be a string of static | |
217 | * storage duration. If the connection has already terminated due to a previous | |
218 | * protocol error, this is a no-op; first error wins. | |
219 | */ | |
220 | void ossl_quic_channel_raise_protocol_error(QUIC_CHANNEL *ch, | |
221 | uint64_t error_code, | |
222 | uint64_t frame_type, | |
223 | const char *reason); | |
224 | ||
225 | /* For RXDP use. */ | |
226 | void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch, | |
227 | OSSL_QUIC_FRAME_CONN_CLOSE *f); | |
eff04652 TM |
228 | void ossl_quic_channel_on_new_conn_id(QUIC_CHANNEL *ch, |
229 | OSSL_QUIC_FRAME_NEW_CONN_ID *f); | |
f538b421 HL |
230 | |
231 | /* | |
232 | * Queries and Accessors | |
233 | * ===================== | |
234 | */ | |
235 | ||
236 | /* Gets the reactor which can be used to tick/poll on the channel. */ | |
237 | QUIC_REACTOR *ossl_quic_channel_get_reactor(QUIC_CHANNEL *ch); | |
238 | ||
239 | /* Gets the QSM used with the channel. */ | |
240 | QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch); | |
241 | ||
242 | /* Gets the statistics manager used with the channel. */ | |
243 | OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch); | |
244 | ||
245 | /* | |
246 | * Gets/sets the current peer address. Generally this should be used before | |
247 | * starting a channel in client mode. | |
248 | */ | |
249 | int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL *ch, BIO_ADDR *peer_addr); | |
250 | int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL *ch, const BIO_ADDR *peer_addr); | |
251 | ||
252 | /* Gets/sets the underlying network read and write BIOs. */ | |
253 | BIO *ossl_quic_channel_get_net_rbio(QUIC_CHANNEL *ch); | |
254 | BIO *ossl_quic_channel_get_net_wbio(QUIC_CHANNEL *ch); | |
d1ac77b1 HL |
255 | int ossl_quic_channel_set_net_rbio(QUIC_CHANNEL *ch, BIO *net_rbio); |
256 | int ossl_quic_channel_set_net_wbio(QUIC_CHANNEL *ch, BIO *net_wbio); | |
f538b421 HL |
257 | |
258 | /* | |
259 | * Returns an existing stream by stream ID. Returns NULL if the stream does not | |
260 | * exist. | |
261 | */ | |
262 | QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch, | |
263 | uint64_t stream_id); | |
264 | ||
265 | /* Returns 1 if channel is terminating or terminated. */ | |
c12e1113 | 266 | int ossl_quic_channel_is_term_any(const QUIC_CHANNEL *ch); |
723cbe8a HL |
267 | const QUIC_TERMINATE_CAUSE * |
268 | ossl_quic_channel_get_terminate_cause(const QUIC_CHANNEL *ch); | |
c12e1113 MC |
269 | int ossl_quic_channel_is_terminating(const QUIC_CHANNEL *ch); |
270 | int ossl_quic_channel_is_terminated(const QUIC_CHANNEL *ch); | |
f538b421 HL |
271 | int ossl_quic_channel_is_active(const QUIC_CHANNEL *ch); |
272 | int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL *ch); | |
ce8f20b6 | 273 | int ossl_quic_channel_is_handshake_confirmed(const QUIC_CHANNEL *ch); |
f538b421 | 274 | |
553a4e00 HL |
275 | QUIC_DEMUX *ossl_quic_channel_get0_demux(QUIC_CHANNEL *ch); |
276 | ||
d03fe5de MC |
277 | SSL *ossl_quic_channel_get0_ssl(QUIC_CHANNEL *ch); |
278 | ||
fb2245c4 | 279 | /* |
4847599b HL |
280 | * Retrieves a pointer to the channel mutex which was provided at the time the |
281 | * channel was instantiated. In order to allow locks to be acquired and released | |
282 | * with the correct granularity, it is the caller's responsibility to ensure | |
283 | * this lock is held for write while calling any QUIC_CHANNEL method, except for | |
284 | * methods explicitly designed otherwise. | |
fb2245c4 HL |
285 | * |
286 | * This method is thread safe and does not require prior locking. It can also be | |
4847599b HL |
287 | * called while the lock is already held. Note that this is simply a convenience |
288 | * function to access the mutex which was passed to the channel at instantiation | |
289 | * time; it does not belong to the channel but rather is presumed to belong to | |
290 | * the owner of the channel. | |
fb2245c4 | 291 | */ |
ffce2946 | 292 | CRYPTO_MUTEX *ossl_quic_channel_get_mutex(QUIC_CHANNEL *ch); |
fb2245c4 | 293 | |
2dbc39de HL |
294 | /* |
295 | * Creates a new locally-initiated stream in the stream mapper, choosing an | |
296 | * appropriate stream ID. If is_uni is 1, creates a unidirectional stream, else | |
f20fdd16 | 297 | * creates a bidirectional stream. Returns NULL on failure. |
2dbc39de | 298 | */ |
f20fdd16 HL |
299 | QUIC_STREAM *ossl_quic_channel_new_stream_local(QUIC_CHANNEL *ch, int is_uni); |
300 | ||
301 | /* | |
302 | * Creates a new remotely-initiated stream in the stream mapper. The stream ID | |
303 | * is used to confirm the initiator and determine the stream type. The stream is | |
304 | * automatically added to the QSM's accept queue. A pointer to the stream is | |
305 | * also returned. Returns NULL on failure. | |
306 | */ | |
307 | QUIC_STREAM *ossl_quic_channel_new_stream_remote(QUIC_CHANNEL *ch, | |
308 | uint64_t stream_id); | |
2dbc39de | 309 | |
995ff282 HL |
310 | /* |
311 | * Configures incoming stream auto-reject. If enabled, incoming streams have | |
312 | * both their sending and receiving parts automatically rejected using | |
313 | * STOP_SENDING and STREAM_RESET frames. aec is the application error | |
314 | * code to be used for those frames. | |
315 | */ | |
316 | void ossl_quic_channel_set_incoming_stream_auto_reject(QUIC_CHANNEL *ch, | |
317 | int enable, | |
318 | uint64_t aec); | |
319 | ||
320 | /* | |
321 | * Causes the channel to reject the sending and receiving parts of a stream, | |
322 | * as though autorejected. Can be used if a stream has already been | |
323 | * accepted. | |
324 | */ | |
325 | void ossl_quic_channel_reject_stream(QUIC_CHANNEL *ch, QUIC_STREAM *qs); | |
326 | ||
bbc97540 TM |
327 | /* Replace local connection ID in TXP and DEMUX for testing purposes. */ |
328 | int ossl_quic_channel_replace_local_cid(QUIC_CHANNEL *ch, | |
329 | const QUIC_CONN_ID *conn_id); | |
330 | ||
6292519c HL |
331 | # endif |
332 | ||
f538b421 | 333 | #endif |