]> git.ipfire.org Git - thirdparty/openssl.git/blob - include/internal/quic_channel.h
QUIC APL, TSERVER: Start using a QUIC_ENGINE object
[thirdparty/openssl.git] / include / internal / quic_channel.h
1 /*
2 * Copyright 2022-2023 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_record_tx.h"
16 # include "internal/quic_wire.h"
17 # include "internal/quic_predef.h"
18 # include "internal/time.h"
19 # include "internal/thread.h"
20
21 # ifndef OPENSSL_NO_QUIC
22
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.
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)
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.
63 */
64
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 */
73 # define QUIC_NEEDS_LOCK
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)
84 */
85 # define QUIC_TAKES_LOCK
86
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
100 # define QUIC_TODO_LOCK
101
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
107
108 typedef struct quic_channel_args_st {
109 /*
110 * The QUIC_PORT which the channel is to belong to. The lifetime of the
111 * QUIC_PORT must exceed that of the created channel.
112 */
113 QUIC_PORT *port;
114 /* LCIDM to register LCIDs with. */
115 QUIC_LCIDM *lcidm;
116 /* SRTM to register SRTs with. */
117 QUIC_SRTM *srtm;
118
119 int is_server;
120 SSL *tls;
121 } QUIC_CHANNEL_ARGS;
122
123 /* Represents the cause for a connection's termination. */
124 typedef struct quic_terminate_cause_st {
125 /*
126 * If we are in a TERMINATING or TERMINATED state, this is the error code
127 * associated with the error. This field is valid iff we are in the
128 * TERMINATING or TERMINATED states.
129 */
130 uint64_t error_code;
131
132 /*
133 * If terminate_app is set and this is nonzero, this is the frame type which
134 * caused the connection to be terminated.
135 */
136 uint64_t frame_type;
137
138 /*
139 * Optional reason string. When calling ossl_quic_channel_local_close, if a
140 * reason string pointer is passed, it is copied and stored inside
141 * QUIC_CHANNEL for the remainder of the lifetime of the channel object.
142 * Thus the string pointed to by this value, if non-NULL, is valid for the
143 * lifetime of the QUIC_CHANNEL object.
144 */
145 const char *reason;
146
147 /*
148 * Length of reason in bytes. The reason is supposed to contain a UTF-8
149 * string but may be arbitrary data if the reason came from the network.
150 */
151 size_t reason_len;
152
153 /* Is this error code in the transport (0) or application (1) space? */
154 unsigned int app : 1;
155
156 /*
157 * If set, the cause of the termination is a received CONNECTION_CLOSE
158 * frame. Otherwise, we decided to terminate ourselves and sent a
159 * CONNECTION_CLOSE frame (regardless of whether the peer later also sends
160 * one).
161 */
162 unsigned int remote : 1;
163 } QUIC_TERMINATE_CAUSE;
164
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 * Only QUIC_PORT should use this function.
170 */
171 QUIC_CHANNEL *ossl_quic_channel_new(const QUIC_CHANNEL_ARGS *args);
172
173 /* No-op if ch is NULL. */
174 void ossl_quic_channel_free(QUIC_CHANNEL *ch);
175
176 /* Set mutator callbacks for test framework support */
177 int ossl_quic_channel_set_mutator(QUIC_CHANNEL *ch,
178 ossl_mutate_packet_cb mutatecb,
179 ossl_finish_mutate_cb finishmutatecb,
180 void *mutatearg);
181
182 /*
183 * Connection Lifecycle Events
184 * ===========================
185 *
186 * Various events that can be raised on the channel by other parts of the QUIC
187 * implementation. Some of these are suitable for general use by any part of the
188 * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very
189 * specific use by particular components only (e.g.
190 * ossl_quic_channel_on_handshake_confirmed).
191 */
192
193 /*
194 * To be used by a QUIC connection. Starts the channel. For a client-mode
195 * channel, this starts sending the first handshake layer message, etc. Can only
196 * be called in the idle state; successive calls are ignored.
197 */
198 int ossl_quic_channel_start(QUIC_CHANNEL *ch);
199
200 /* Start a locally initiated connection shutdown. */
201 void ossl_quic_channel_local_close(QUIC_CHANNEL *ch, uint64_t app_error_code,
202 const char *app_reason);
203
204 /*
205 * Called when the handshake is confirmed.
206 */
207 int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL *ch);
208
209 /*
210 * Raises a protocol error. This is intended to be the universal call suitable
211 * for handling of all peer-triggered protocol violations or errors detected by
212 * us. We specify a QUIC transport-scope error code and optional frame type
213 * which was responsible. If a frame type is not applicable, specify zero. The
214 * reason string is not currently handled, but should be a string of static
215 * storage duration. If the connection has already terminated due to a previous
216 * protocol error, this is a no-op; first error wins.
217 *
218 * Usually the ossl_quic_channel_raise_protocol_error() function should be used.
219 * The ossl_quic_channel_raise_protocol_error_loc() function can be used
220 * directly for passing through existing call site information from an existing
221 * error.
222 */
223 void ossl_quic_channel_raise_protocol_error_loc(QUIC_CHANNEL *ch,
224 uint64_t error_code,
225 uint64_t frame_type,
226 const char *reason,
227 ERR_STATE *err_state,
228 const char *src_file,
229 int src_line,
230 const char *src_func);
231
232 #define ossl_quic_channel_raise_protocol_error(ch, error_code, frame_type, reason) \
233 ossl_quic_channel_raise_protocol_error_loc((ch), (error_code), \
234 (frame_type), \
235 (reason), \
236 NULL, \
237 OPENSSL_FILE, \
238 OPENSSL_LINE, \
239 OPENSSL_FUNC)
240
241 #define ossl_quic_channel_raise_protocol_error_state(ch, error_code, frame_type, reason, state) \
242 ossl_quic_channel_raise_protocol_error_loc((ch), (error_code), \
243 (frame_type), \
244 (reason), \
245 (state), \
246 OPENSSL_FILE, \
247 OPENSSL_LINE, \
248 OPENSSL_FUNC)
249
250
251 /*
252 * Returns 1 if permanent net error was detected on the QUIC_CHANNEL,
253 * 0 otherwise.
254 */
255 int ossl_quic_channel_net_error(QUIC_CHANNEL *ch);
256
257 /* Restore saved error state (best effort) */
258 void ossl_quic_channel_restore_err_state(QUIC_CHANNEL *ch);
259
260 /* For RXDP use. */
261 void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch,
262 OSSL_QUIC_FRAME_CONN_CLOSE *f);
263 void ossl_quic_channel_on_new_conn_id(QUIC_CHANNEL *ch,
264 OSSL_QUIC_FRAME_NEW_CONN_ID *f);
265
266 /* Temporarily exposed during QUIC_PORT transition. */
267 int ossl_quic_channel_on_new_conn(QUIC_CHANNEL *ch, const BIO_ADDR *peer,
268 const QUIC_CONN_ID *peer_scid,
269 const QUIC_CONN_ID *peer_dcid);
270
271 /* For use by QUIC_PORT. You should not need to call this directly. */
272 void ossl_quic_channel_subtick(QUIC_CHANNEL *ch, QUIC_TICK_RESULT *r,
273 uint32_t flags);
274
275 /* For use by QUIC_PORT only. */
276 void ossl_quic_channel_raise_net_error(QUIC_CHANNEL *ch);
277
278 /* For use by QUIC_PORT only. */
279 void ossl_quic_channel_on_stateless_reset(QUIC_CHANNEL *ch);
280
281 void ossl_quic_channel_inject(QUIC_CHANNEL *ch, QUIC_URXE *e);
282
283 /*
284 * Queries and Accessors
285 * =====================
286 */
287
288 /* Gets the reactor which can be used to tick/poll on the channel. */
289 QUIC_REACTOR *ossl_quic_channel_get_reactor(QUIC_CHANNEL *ch);
290
291 /* Gets the QSM used with the channel. */
292 QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch);
293
294 /* Gets the statistics manager used with the channel. */
295 OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch);
296
297 /*
298 * Gets/sets the current peer address. Generally this should be used before
299 * starting a channel in client mode.
300 */
301 int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL *ch, BIO_ADDR *peer_addr);
302 int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL *ch, const BIO_ADDR *peer_addr);
303
304 /*
305 * Returns an existing stream by stream ID. Returns NULL if the stream does not
306 * exist.
307 */
308 QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch,
309 uint64_t stream_id);
310
311 /* Returns 1 if channel is terminating or terminated. */
312 int ossl_quic_channel_is_term_any(const QUIC_CHANNEL *ch);
313 const QUIC_TERMINATE_CAUSE *
314 ossl_quic_channel_get_terminate_cause(const QUIC_CHANNEL *ch);
315 int ossl_quic_channel_is_closing(const QUIC_CHANNEL *ch);
316 int ossl_quic_channel_is_terminated(const QUIC_CHANNEL *ch);
317 int ossl_quic_channel_is_active(const QUIC_CHANNEL *ch);
318 int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL *ch);
319 int ossl_quic_channel_is_handshake_confirmed(const QUIC_CHANNEL *ch);
320
321 QUIC_PORT *ossl_quic_channel_get0_port(QUIC_CHANNEL *ch);
322 QUIC_ENGINE *ossl_quic_channel_get0_engine(QUIC_CHANNEL *ch);
323 QUIC_DEMUX *ossl_quic_channel_get0_demux(QUIC_CHANNEL *ch);
324
325 SSL *ossl_quic_channel_get0_ssl(QUIC_CHANNEL *ch);
326
327 /*
328 * Retrieves a pointer to the channel mutex which was provided at the time the
329 * channel was instantiated. In order to allow locks to be acquired and released
330 * with the correct granularity, it is the caller's responsibility to ensure
331 * this lock is held for write while calling any QUIC_CHANNEL method, except for
332 * methods explicitly designed otherwise.
333 *
334 * This method is thread safe and does not require prior locking. It can also be
335 * called while the lock is already held. Note that this is simply a convenience
336 * function to access the mutex which was passed to the channel at instantiation
337 * time; it does not belong to the channel but rather is presumed to belong to
338 * the owner of the channel.
339 */
340 CRYPTO_MUTEX *ossl_quic_channel_get_mutex(QUIC_CHANNEL *ch);
341
342 /*
343 * Creates a new locally-initiated stream in the stream mapper, choosing an
344 * appropriate stream ID. If is_uni is 1, creates a unidirectional stream, else
345 * creates a bidirectional stream. Returns NULL on failure.
346 */
347 QUIC_STREAM *ossl_quic_channel_new_stream_local(QUIC_CHANNEL *ch, int is_uni);
348
349 /*
350 * Creates a new remotely-initiated stream in the stream mapper. The stream ID
351 * is used to confirm the initiator and determine the stream type. The stream is
352 * automatically added to the QSM's accept queue. A pointer to the stream is
353 * also returned. Returns NULL on failure.
354 */
355 QUIC_STREAM *ossl_quic_channel_new_stream_remote(QUIC_CHANNEL *ch,
356 uint64_t stream_id);
357
358 /*
359 * Configures incoming stream auto-reject. If enabled, incoming streams have
360 * both their sending and receiving parts automatically rejected using
361 * STOP_SENDING and STREAM_RESET frames. aec is the application error
362 * code to be used for those frames.
363 */
364 void ossl_quic_channel_set_incoming_stream_auto_reject(QUIC_CHANNEL *ch,
365 int enable,
366 uint64_t aec);
367
368 /*
369 * Causes the channel to reject the sending and receiving parts of a stream,
370 * as though autorejected. Can be used if a stream has already been
371 * accepted.
372 */
373 void ossl_quic_channel_reject_stream(QUIC_CHANNEL *ch, QUIC_STREAM *qs);
374
375 /* Replace local connection ID in TXP and DEMUX for testing purposes. */
376 int ossl_quic_channel_replace_local_cid(QUIC_CHANNEL *ch,
377 const QUIC_CONN_ID *conn_id);
378
379 /* Setters for the msg_callback and msg_callback_arg */
380 void ossl_quic_channel_set_msg_callback(QUIC_CHANNEL *ch,
381 ossl_msg_cb msg_callback,
382 SSL *msg_callback_ssl);
383 void ossl_quic_channel_set_msg_callback_arg(QUIC_CHANNEL *ch,
384 void *msg_callback_arg);
385
386 /* Testing use only - sets a TXKU threshold packet count override value. */
387 void ossl_quic_channel_set_txku_threshold_override(QUIC_CHANNEL *ch,
388 uint64_t tx_pkt_threshold);
389
390 /* Testing use only - gets current 1-RTT key epochs for QTX and QRX. */
391 uint64_t ossl_quic_channel_get_tx_key_epoch(QUIC_CHANNEL *ch);
392 uint64_t ossl_quic_channel_get_rx_key_epoch(QUIC_CHANNEL *ch);
393
394 /* Artificially trigger a spontaneous TXKU if possible. */
395 int ossl_quic_channel_trigger_txku(QUIC_CHANNEL *ch);
396 int ossl_quic_channel_has_pending(const QUIC_CHANNEL *ch);
397
398 /* Force transmission of an ACK-eliciting packet. */
399 int ossl_quic_channel_ping(QUIC_CHANNEL *ch);
400
401 /*
402 * These queries exist for diagnostic purposes only. They may roll over.
403 * Do not rely on them for non-testing purposes.
404 */
405 uint16_t ossl_quic_channel_get_diag_num_rx_ack(QUIC_CHANNEL *ch);
406
407 /*
408 * Diagnostic use only. Gets the current local CID.
409 */
410 void ossl_quic_channel_get_diag_local_cid(QUIC_CHANNEL *ch, QUIC_CONN_ID *cid);
411
412 /*
413 * Returns 1 if stream count flow control allows us to create a new
414 * locally-initiated stream.
415 */
416 int ossl_quic_channel_is_new_local_stream_admissible(QUIC_CHANNEL *ch, int is_uni);
417
418 # endif
419
420 #endif