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