1 /* 2 * Copyright 2022-2024 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/qlog.h" 19 # include "internal/time.h" 20 # include "internal/thread.h" 21 22 # ifndef OPENSSL_NO_QUIC 23 24 /* 25 * QUIC Channel 26 * ============ 27 * 28 * A QUIC channel (QUIC_CHANNEL) is an object which binds together all of the 29 * various pieces of QUIC into a single top-level object, and handles connection 30 * state which is not specific to the client or server roles. In particular, it 31 * is strictly separated from the libssl front end I/O API personality layer, 32 * and is not an SSL object. 33 * 34 * The name QUIC_CHANNEL is chosen because QUIC_CONNECTION is already in use, 35 * but functionally these relate to the same thing (a QUIC connection). The use 36 * of two separate objects ensures clean separation between the API personality 37 * layer and common code for handling connections, and between the functionality 38 * which is specific to clients and which is specific to servers, and the 39 * functionality which is common to both. 40 * 41 * The API personality layer provides SSL objects (e.g. a QUIC_CONNECTION) which 42 * consume a QUIC channel and implement a specific public API. Things which are 43 * handled by the API personality layer include emulation of blocking semantics, 44 * handling of SSL object mode flags like non-partial write mode, etc. 45 * 46 * Where the QUIC_CHANNEL is used in a server role, there is one QUIC_CHANNEL 47 * per connection. In the future a QUIC Channel Manager will probably be defined 48 * to handle ownership of resources which are shared between connections (e.g. 49 * demuxers). Since we only use server-side functionality for dummy test servers 50 * for now, which only need to handle one connection at a time, this is not 51 * currently modelled. 52 * 53 * Synchronisation 54 * --------------- 55 * 56 * To support thread assisted mode, QUIC_CHANNEL can be used by multiple 57 * threads. **It is the caller's responsibility to ensure that the QUIC_CHANNEL 58 * is only accessed (whether via its methods or via direct access to its state) 59 * while the channel mutex is held**, except for methods explicitly marked as 60 * not requiring prior locking. This is an unchecked precondition. 61 * 62 * The instantiator of the channel is responsible for providing a suitable 63 * mutex which then serves as the channel mutex; see QUIC_CHANNEL_ARGS. 64 */ 65 66 /* 67 * The function does not acquire the channel mutex and assumes it is already 68 * held by the calling thread. 69 * 70 * Any function tagged with this has the following precondition: 71 * 72 * Precondition: must hold channel mutex (unchecked) 73 */ 74 # define QUIC_NEEDS_LOCK 75 76 /* 77 * The function acquires the channel mutex and releases it before returning in 78 * all circumstances. 79 * 80 * Any function tagged with this has the following precondition and 81 * postcondition: 82 * 83 * Precondition: must not hold channel mutex (unchecked) 84 * Postcondition: channel mutex is not held (by calling thread) 85 */ 86 # define QUIC_TAKES_LOCK 87 88 /* 89 * The function acquires the channel mutex and leaves it acquired 90 * when returning success. 91 * 92 * Any function tagged with this has the following precondition and 93 * postcondition: 94 * 95 * Precondition: must not hold channel mutex (unchecked) 96 * Postcondition: channel mutex is held by calling thread 97 * or function returned failure 98 */ 99 # define QUIC_ACQUIRES_LOCK 100 101 # define QUIC_TODO_LOCK 102 103 # define QUIC_CHANNEL_STATE_IDLE 0 104 # define QUIC_CHANNEL_STATE_ACTIVE 1 105 # define QUIC_CHANNEL_STATE_TERMINATING_CLOSING 2 106 # define QUIC_CHANNEL_STATE_TERMINATING_DRAINING 3 107 # define QUIC_CHANNEL_STATE_TERMINATED 4 108 109 typedef struct quic_channel_args_st { 110 /* 111 * The QUIC_PORT which the channel is to belong to. The lifetime of the 112 * QUIC_PORT must exceed that of the created channel. 113 */ 114 QUIC_PORT *port; 115 /* LCIDM to register LCIDs with. */ 116 QUIC_LCIDM *lcidm; 117 /* SRTM to register SRTs with. */ 118 QUIC_SRTM *srtm; 119 120 int is_server; 121 SSL *tls; 122 123 /* Whether to use qlog. */ 124 int use_qlog; 125 126 /* Title to use for the qlog session, or NULL. */ 127 const char *qlog_title; 128 } QUIC_CHANNEL_ARGS; 129 130 /* Represents the cause for a connection's termination. */ 131 typedef struct quic_terminate_cause_st { 132 /* 133 * If we are in a TERMINATING or TERMINATED state, this is the error code 134 * associated with the error. This field is valid iff we are in the 135 * TERMINATING or TERMINATED states. 136 */ 137 uint64_t error_code; 138 139 /* 140 * If terminate_app is set and this is nonzero, this is the frame type which 141 * caused the connection to be terminated. 142 */ 143 uint64_t frame_type; 144 145 /* 146 * Optional reason string. When calling ossl_quic_channel_local_close, if a 147 * reason string pointer is passed, it is copied and stored inside 148 * QUIC_CHANNEL for the remainder of the lifetime of the channel object. 149 * Thus the string pointed to by this value, if non-NULL, is valid for the 150 * lifetime of the QUIC_CHANNEL object. 151 */ 152 const char *reason; 153 154 /* 155 * Length of reason in bytes. The reason is supposed to contain a UTF-8 156 * string but may be arbitrary data if the reason came from the network. 157 */ 158 size_t reason_len; 159 160 /* Is this error code in the transport (0) or application (1) space? */ 161 unsigned int app : 1; 162 163 /* 164 * If set, the cause of the termination is a received CONNECTION_CLOSE 165 * frame. Otherwise, we decided to terminate ourselves and sent a 166 * CONNECTION_CLOSE frame (regardless of whether the peer later also sends 167 * one). 168 */ 169 unsigned int remote : 1; 170 } QUIC_TERMINATE_CAUSE; 171 172 /* 173 * Create a new QUIC channel using the given arguments. The argument structure 174 * does not need to remain allocated. Returns NULL on failure. 175 * 176 * Only QUIC_PORT should use this function. 177 */ 178 QUIC_CHANNEL *ossl_quic_channel_new(const QUIC_CHANNEL_ARGS *args); 179 180 /* No-op if ch is NULL. */ 181 void ossl_quic_channel_free(QUIC_CHANNEL *ch); 182 183 /* Set mutator callbacks for test framework support */ 184 int ossl_quic_channel_set_mutator(QUIC_CHANNEL *ch, 185 ossl_mutate_packet_cb mutatecb, 186 ossl_finish_mutate_cb finishmutatecb, 187 void *mutatearg); 188 189 /* 190 * Connection Lifecycle Events 191 * =========================== 192 * 193 * Various events that can be raised on the channel by other parts of the QUIC 194 * implementation. Some of these are suitable for general use by any part of the 195 * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very 196 * specific use by particular components only (e.g. 197 * ossl_quic_channel_on_handshake_confirmed). 198 */ 199 200 /* 201 * To be used by a QUIC connection. Starts the channel. For a client-mode 202 * channel, this starts sending the first handshake layer message, etc. Can only 203 * be called in the idle state; successive calls are ignored. 204 */ 205 int ossl_quic_channel_start(QUIC_CHANNEL *ch); 206 207 /* Start a locally initiated connection shutdown. */ 208 void ossl_quic_channel_local_close(QUIC_CHANNEL *ch, uint64_t app_error_code, 209 const char *app_reason); 210 211 /* 212 * Called when the handshake is confirmed. 213 */ 214 int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL *ch); 215 216 /* 217 * Raises a protocol error. This is intended to be the universal call suitable 218 * for handling of all peer-triggered protocol violations or errors detected by 219 * us. We specify a QUIC transport-scope error code and optional frame type 220 * which was responsible. If a frame type is not applicable, specify zero. The 221 * reason string is not currently handled, but should be a string of static 222 * storage duration. If the connection has already terminated due to a previous 223 * protocol error, this is a no-op; first error wins. 224 * 225 * Usually the ossl_quic_channel_raise_protocol_error() function should be used. 226 * The ossl_quic_channel_raise_protocol_error_loc() function can be used 227 * directly for passing through existing call site information from an existing 228 * error. 229 */ 230 void ossl_quic_channel_raise_protocol_error_loc(QUIC_CHANNEL *ch, 231 uint64_t error_code, 232 uint64_t frame_type, 233 const char *reason, 234 ERR_STATE *err_state, 235 const char *src_file, 236 int src_line, 237 const char *src_func); 238 239 #define ossl_quic_channel_raise_protocol_error(ch, error_code, frame_type, reason) \ 240 ossl_quic_channel_raise_protocol_error_loc((ch), (error_code), \ 241 (frame_type), \ 242 (reason), \ 243 NULL, \ 244 OPENSSL_FILE, \ 245 OPENSSL_LINE, \ 246 OPENSSL_FUNC) 247 248 #define ossl_quic_channel_raise_protocol_error_state(ch, error_code, frame_type, reason, state) \ 249 ossl_quic_channel_raise_protocol_error_loc((ch), (error_code), \ 250 (frame_type), \ 251 (reason), \ 252 (state), \ 253 OPENSSL_FILE, \ 254 OPENSSL_LINE, \ 255 OPENSSL_FUNC) 256 257 258 /* 259 * Returns 1 if permanent net error was detected on the QUIC_CHANNEL, 260 * 0 otherwise. 261 */ 262 int ossl_quic_channel_net_error(QUIC_CHANNEL *ch); 263 264 /* Restore saved error state (best effort) */ 265 void ossl_quic_channel_restore_err_state(QUIC_CHANNEL *ch); 266 267 /* For RXDP use. */ 268 void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch, 269 OSSL_QUIC_FRAME_CONN_CLOSE *f); 270 void ossl_quic_channel_on_new_conn_id(QUIC_CHANNEL *ch, 271 OSSL_QUIC_FRAME_NEW_CONN_ID *f); 272 273 /* Temporarily exposed during QUIC_PORT transition. */ 274 int ossl_quic_channel_on_new_conn(QUIC_CHANNEL *ch, const BIO_ADDR *peer, 275 const QUIC_CONN_ID *peer_scid, 276 const QUIC_CONN_ID *peer_dcid); 277 278 /* For use by QUIC_PORT. You should not need to call this directly. */ 279 void ossl_quic_channel_subtick(QUIC_CHANNEL *ch, QUIC_TICK_RESULT *r, 280 uint32_t flags); 281 282 /* For use by QUIC_PORT only. */ 283 void ossl_quic_channel_raise_net_error(QUIC_CHANNEL *ch); 284 285 /* For use by QUIC_PORT only. */ 286 void ossl_quic_channel_on_stateless_reset(QUIC_CHANNEL *ch); 287 288 void ossl_quic_channel_inject(QUIC_CHANNEL *ch, QUIC_URXE *e); 289 290 /* 291 * Queries and Accessors 292 * ===================== 293 */ 294 295 /* Gets the reactor which can be used to tick/poll on the channel. */ 296 QUIC_REACTOR *ossl_quic_channel_get_reactor(QUIC_CHANNEL *ch); 297 298 /* Gets the QSM used with the channel. */ 299 QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch); 300 301 /* Gets the statistics manager used with the channel. */ 302 OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch); 303 304 /* 305 * Gets/sets the current peer address. Generally this should be used before 306 * starting a channel in client mode. 307 */ 308 int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL *ch, BIO_ADDR *peer_addr); 309 int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL *ch, const BIO_ADDR *peer_addr); 310 311 /* 312 * Returns an existing stream by stream ID. Returns NULL if the stream does not 313 * exist. 314 */ 315 QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch, 316 uint64_t stream_id); 317 318 /* Returns 1 if channel is terminating or terminated. */ 319 int ossl_quic_channel_is_term_any(const QUIC_CHANNEL *ch); 320 const QUIC_TERMINATE_CAUSE * 321 ossl_quic_channel_get_terminate_cause(const QUIC_CHANNEL *ch); 322 int ossl_quic_channel_is_closing(const QUIC_CHANNEL *ch); 323 int ossl_quic_channel_is_terminated(const QUIC_CHANNEL *ch); 324 int ossl_quic_channel_is_active(const QUIC_CHANNEL *ch); 325 int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL *ch); 326 int ossl_quic_channel_is_handshake_confirmed(const QUIC_CHANNEL *ch); 327 328 QUIC_PORT *ossl_quic_channel_get0_port(QUIC_CHANNEL *ch); 329 QUIC_ENGINE *ossl_quic_channel_get0_engine(QUIC_CHANNEL *ch); 330 QUIC_DEMUX *ossl_quic_channel_get0_demux(QUIC_CHANNEL *ch); 331 332 SSL *ossl_quic_channel_get0_ssl(QUIC_CHANNEL *ch); 333 334 /* 335 * Retrieves a pointer to the channel mutex which was provided at the time the 336 * channel was instantiated. In order to allow locks to be acquired and released 337 * with the correct granularity, it is the caller's responsibility to ensure 338 * this lock is held for write while calling any QUIC_CHANNEL method, except for 339 * methods explicitly designed otherwise. 340 * 341 * This method is thread safe and does not require prior locking. It can also be 342 * called while the lock is already held. Note that this is simply a convenience 343 * function to access the mutex which was passed to the channel at instantiation 344 * time; it does not belong to the channel but rather is presumed to belong to 345 * the owner of the channel. 346 */ 347 CRYPTO_MUTEX *ossl_quic_channel_get_mutex(QUIC_CHANNEL *ch); 348 349 /* 350 * Creates a new locally-initiated stream in the stream mapper, choosing an 351 * appropriate stream ID. If is_uni is 1, creates a unidirectional stream, else 352 * creates a bidirectional stream. Returns NULL on failure. 353 */ 354 QUIC_STREAM *ossl_quic_channel_new_stream_local(QUIC_CHANNEL *ch, int is_uni); 355 356 /* 357 * Creates a new remotely-initiated stream in the stream mapper. The stream ID 358 * is used to confirm the initiator and determine the stream type. The stream is 359 * automatically added to the QSM's accept queue. A pointer to the stream is 360 * also returned. Returns NULL on failure. 361 */ 362 QUIC_STREAM *ossl_quic_channel_new_stream_remote(QUIC_CHANNEL *ch, 363 uint64_t stream_id); 364 365 /* 366 * Configures incoming stream auto-reject. If enabled, incoming streams have 367 * both their sending and receiving parts automatically rejected using 368 * STOP_SENDING and STREAM_RESET frames. aec is the application error 369 * code to be used for those frames. 370 */ 371 void ossl_quic_channel_set_incoming_stream_auto_reject(QUIC_CHANNEL *ch, 372 int enable, 373 uint64_t aec); 374 375 /* 376 * Causes the channel to reject the sending and receiving parts of a stream, 377 * as though autorejected. Can be used if a stream has already been 378 * accepted. 379 */ 380 void ossl_quic_channel_reject_stream(QUIC_CHANNEL *ch, QUIC_STREAM *qs); 381 382 /* Replace local connection ID in TXP and DEMUX for testing purposes. */ 383 int ossl_quic_channel_replace_local_cid(QUIC_CHANNEL *ch, 384 const QUIC_CONN_ID *conn_id); 385 386 /* Setters for the msg_callback and msg_callback_arg */ 387 void ossl_quic_channel_set_msg_callback(QUIC_CHANNEL *ch, 388 ossl_msg_cb msg_callback, 389 SSL *msg_callback_ssl); 390 void ossl_quic_channel_set_msg_callback_arg(QUIC_CHANNEL *ch, 391 void *msg_callback_arg); 392 393 /* Testing use only - sets a TXKU threshold packet count override value. */ 394 void ossl_quic_channel_set_txku_threshold_override(QUIC_CHANNEL *ch, 395 uint64_t tx_pkt_threshold); 396 397 /* Testing use only - gets current 1-RTT key epochs for QTX and QRX. */ 398 uint64_t ossl_quic_channel_get_tx_key_epoch(QUIC_CHANNEL *ch); 399 uint64_t ossl_quic_channel_get_rx_key_epoch(QUIC_CHANNEL *ch); 400 401 /* Artificially trigger a spontaneous TXKU if possible. */ 402 int ossl_quic_channel_trigger_txku(QUIC_CHANNEL *ch); 403 int ossl_quic_channel_has_pending(const QUIC_CHANNEL *ch); 404 405 /* Force transmission of an ACK-eliciting packet. */ 406 int ossl_quic_channel_ping(QUIC_CHANNEL *ch); 407 408 /* 409 * These queries exist for diagnostic purposes only. They may roll over. 410 * Do not rely on them for non-testing purposes. 411 */ 412 uint16_t ossl_quic_channel_get_diag_num_rx_ack(QUIC_CHANNEL *ch); 413 414 /* 415 * Diagnostic use only. Gets the current local CID. 416 */ 417 void ossl_quic_channel_get_diag_local_cid(QUIC_CHANNEL *ch, QUIC_CONN_ID *cid); 418 419 /* 420 * Returns 1 if stream count flow control allows us to create a new 421 * locally-initiated stream. 422 */ 423 int ossl_quic_channel_is_new_local_stream_admissible(QUIC_CHANNEL *ch, int is_uni); 424 425 /* 426 * Returns the number of additional streams that can currently be created based 427 * on flow control. 428 */ 429 uint64_t ossl_quic_channel_get_local_stream_count_avail(const QUIC_CHANNEL *ch, 430 int is_uni); 431 uint64_t ossl_quic_channel_get_remote_stream_count_avail(const QUIC_CHANNEL *ch, 432 int is_uni); 433 434 /* 435 * Returns 1 if we have generated our local transport parameters yet. 436 */ 437 int ossl_quic_channel_have_generated_transport_params(const QUIC_CHANNEL *ch); 438 439 /* Configures the idle timeout to request from peer (milliseconds, 0=no timeout). */ 440 void ossl_quic_channel_set_max_idle_timeout_request(QUIC_CHANNEL *ch, uint64_t ms); 441 /* Get the configured idle timeout to request from peer. */ 442 uint64_t ossl_quic_channel_get_max_idle_timeout_request(const QUIC_CHANNEL *ch); 443 /* Get the idle timeout requested by the peer. */ 444 uint64_t ossl_quic_channel_get_max_idle_timeout_peer_request(const QUIC_CHANNEL *ch); 445 /* Get the idle timeout actually negotiated. */ 446 uint64_t ossl_quic_channel_get_max_idle_timeout_actual(const QUIC_CHANNEL *ch); 447 448 # endif 449 450 #endif 451