1 #ifndef OSSL_QUIC_CHANNEL_LOCAL_H 2 #define OSSL_QUIC_CHANNEL_LOCAL_H 3 4 #include "internal/quic_channel.h" 5 6 #ifndef OPENSSL_NO_QUIC 7 8 #include <openssl/lhash.h> 9 #include "internal/list.h" 10 #include "internal/quic_predef.h" 11 #include "internal/quic_fc.h" 12 #include "internal/quic_stream_map.h" 13 #include "internal/quic_tls.h" 14 15 /* 16 * This is a part of PATH_CHALLENGE flood [1] mitigation. This limits the 17 * number of PATH_CHALLENGE frames QUIC stack is willing to process for 18 * connection. Local QUIC stack creates PATH_RESPONSE frame for PATH_CHALLENGE 19 * frame it receives from remote peer. The response frame is put Control Frame 20 * Queue waiting to be dispatched. The PATH_RESPONSE frame is removed from CFQ 21 * after it is dispatched. The QUIC_PATH_RESPONSE_QLEN limits the number of 22 * PATH_RESPONSE frames waiting to be dispatched. No new PATH_RESPONSE frames 23 * are inserted into CFQ if queue limit is exceeded. 24 * 25 * QUIC implementations use different limits for PATH_RESPONSE queue lengths: 26 * quic-go defines maxPathResponses as 256 27 * quiche from cloadflare sets DEFAULT_MAX_PATH_CHALLENGE_RX_QUEUE_LEN to 3 28 * t-quic from tencent chooses MAX_PATH_CHALS_RECV to be 8 29 * 30 * OpenSSL here introduces QUIC_PATH_RESPONSE_QLEN as 32. 31 * 32 * [1] https://www.ietf.org/archive/id/draft-chen-quic-logical-vuln-mitigations-00.txt 33 * (section 4.2) 34 */ 35 #define QUIC_PATH_RESPONSE_QLEN 32 36 37 /* 38 * QUIC Channel Structure 39 * ====================== 40 * 41 * QUIC channel internals. It is intended that only the QUIC_CHANNEL 42 * implementation and the RX depacketiser be allowed to access this structure 43 * directly. As the RX depacketiser has no state of its own and computes over a 44 * QUIC_CHANNEL structure, it can be viewed as an extension of the QUIC_CHANNEL 45 * implementation. While the RX depacketiser could be provided with adequate 46 * accessors to do what it needs, this would weaken the abstraction provided by 47 * the QUIC_CHANNEL to other components; moreover the coupling of the RX 48 * depacketiser to QUIC_CHANNEL internals is too deep and bespoke to make this 49 * desirable. 50 * 51 * Other components should not include this header. 52 */ 53 struct quic_channel_st { 54 QUIC_PORT *port; 55 56 /* 57 * QUIC_PORT keeps the channels which belong to it on a list for bookkeeping 58 * purposes. 59 */ 60 OSSL_LIST_MEMBER(ch, QUIC_CHANNEL); 61 OSSL_LIST_MEMBER(incoming_ch, QUIC_CHANNEL); 62 63 /* 64 * The associated TLS 1.3 connection data. Used to provide the handshake 65 * layer; its 'network' side is plugged into the crypto stream for each EL 66 * (other than the 0-RTT EL). Note that the `tls` SSL object is not "owned" 67 * by this channel. It is created and managed elsewhere and is guaranteed 68 * to be valid for the lifetime of the channel. Therefore we do not free it 69 * when we free the channel. 70 */ 71 QUIC_TLS *qtls; 72 SSL *tls; 73 74 /* Port LCIDM we use to register LCIDs. */ 75 QUIC_LCIDM *lcidm; 76 /* SRTM we register SRTs with. */ 77 QUIC_SRTM *srtm; 78 79 /* Optional QLOG instance (or NULL). */ 80 QLOG *qlog; 81 82 /* 83 * The transport parameter block we will send or have sent. 84 * Freed after sending or when connection is freed. 85 */ 86 unsigned char *local_transport_params; 87 88 /* 89 * Pending new token to send once handshake is complete 90 */ 91 uint8_t *pending_new_token; 92 size_t pending_new_token_len; 93 94 /* Our current L4 peer address, if any. */ 95 BIO_ADDR cur_peer_addr; 96 97 /* 98 * Subcomponents of the connection. All of these components are instantiated 99 * and owned by us. 100 */ 101 OSSL_QUIC_TX_PACKETISER *txp; 102 QUIC_TXPIM *txpim; 103 QUIC_CFQ *cfq; 104 /* 105 * Connection level FC. The stream_count RXFCs is used to manage 106 * MAX_STREAMS signalling. 107 */ 108 QUIC_TXFC conn_txfc; 109 QUIC_RXFC conn_rxfc, crypto_rxfc[QUIC_PN_SPACE_NUM]; 110 QUIC_RXFC max_streams_bidi_rxfc, max_streams_uni_rxfc; 111 QUIC_STREAM_MAP qsm; 112 OSSL_STATM statm; 113 OSSL_CC_DATA *cc_data; 114 const OSSL_CC_METHOD *cc_method; 115 OSSL_ACKM *ackm; 116 117 /* Record layers in the TX and RX directions. */ 118 OSSL_QTX *qtx; 119 OSSL_QRX *qrx; 120 121 /* Message callback related arguments */ 122 ossl_msg_cb msg_callback; 123 void *msg_callback_arg; 124 SSL *msg_callback_ssl; 125 126 /* 127 * Send and receive parts of the crypto streams. 128 * crypto_send[QUIC_PN_SPACE_APP] is the 1-RTT crypto stream. There is no 129 * 0-RTT crypto stream. 130 */ 131 QUIC_SSTREAM *crypto_send[QUIC_PN_SPACE_NUM]; 132 QUIC_RSTREAM *crypto_recv[QUIC_PN_SPACE_NUM]; 133 134 /* Internal state. */ 135 /* 136 * Client: The DCID used in the first Initial packet we transmit as a client. 137 * Server: The DCID used in the first Initial packet the client transmitted. 138 * Randomly generated and required by RFC to be at least 8 bytes. 139 */ 140 QUIC_CONN_ID init_dcid; 141 142 /* 143 * Server: If this channel is created in response to an init packet sent 144 * after the server has sent a retry packet to do address validation, this 145 * field stores the original connection id from the first init packet sent 146 */ 147 QUIC_CONN_ID odcid; 148 149 /* 150 * Client: The SCID found in the first Initial packet from the server. 151 * Not valid for servers. 152 * Valid if have_received_enc_pkt is set. 153 */ 154 QUIC_CONN_ID init_scid; 155 156 /* 157 * Client only: The SCID found in an incoming Retry packet we handled. 158 * Not valid for servers. 159 */ 160 QUIC_CONN_ID retry_scid; 161 162 /* Server only: The DCID we currently expect the peer to use to talk to us. */ 163 QUIC_CONN_ID cur_local_cid; 164 165 /* 166 * The DCID we currently use to talk to the peer and its sequence num. 167 */ 168 QUIC_CONN_ID cur_remote_dcid; 169 uint64_t cur_remote_seq_num; 170 uint64_t cur_retire_prior_to; 171 172 /* Transport parameter values we send to our peer. */ 173 uint64_t tx_init_max_stream_data_bidi_local; 174 uint64_t tx_init_max_stream_data_bidi_remote; 175 uint64_t tx_init_max_stream_data_uni; 176 uint64_t tx_max_ack_delay; /* ms */ 177 178 /* Transport parameter values received from server. */ 179 uint64_t rx_init_max_stream_data_bidi_local; 180 uint64_t rx_init_max_stream_data_bidi_remote; 181 uint64_t rx_init_max_stream_data_uni; 182 uint64_t rx_max_ack_delay; /* ms */ 183 unsigned char rx_ack_delay_exp; 184 185 /* Diagnostic counters for testing purposes only. May roll over. */ 186 uint16_t diag_num_rx_ack; /* Number of ACK frames received */ 187 188 /* 189 * Temporary staging area to store information about the incoming packet we 190 * are currently processing. 191 */ 192 OSSL_QRX_PKT *qrx_pkt; 193 194 /* 195 * Current limit on number of streams we may create. Set by transport 196 * parameters initially and then by MAX_STREAMS frames. 197 */ 198 uint64_t max_local_streams_bidi; 199 uint64_t max_local_streams_uni; 200 201 /* The idle timeout values we and our peer requested. */ 202 uint64_t max_idle_timeout_local_req; 203 uint64_t max_idle_timeout_remote_req; 204 205 /* The negotiated maximum idle timeout in milliseconds. */ 206 uint64_t max_idle_timeout; 207 208 /* 209 * Maximum payload size in bytes for datagrams sent to our peer, as 210 * negotiated by transport parameters. 211 */ 212 uint64_t rx_max_udp_payload_size; 213 /* Maximum active CID limit, as negotiated by transport parameters. */ 214 uint64_t rx_active_conn_id_limit; 215 216 /* 217 * Used to allocate stream IDs. This is a stream ordinal, i.e., a stream ID 218 * without the low two bits designating type and initiator. Shift and or in 219 * the type bits to convert to a stream ID. 220 */ 221 uint64_t next_local_stream_ordinal_bidi; 222 uint64_t next_local_stream_ordinal_uni; 223 224 /* 225 * Used to track which stream ordinals within a given stream type have been 226 * used by the remote peer. This is an optimisation used to determine 227 * which streams should be implicitly created due to usage of a higher 228 * stream ordinal. 229 */ 230 uint64_t next_remote_stream_ordinal_bidi; 231 uint64_t next_remote_stream_ordinal_uni; 232 233 /* 234 * Application error code to be used for STOP_SENDING/RESET_STREAM frames 235 * used to autoreject incoming streams. 236 */ 237 uint64_t incoming_stream_auto_reject_aec; 238 239 /* 240 * Override packet count threshold at which we do a spontaneous TXKU. 241 * Usually UINT64_MAX in which case a suitable value is chosen based on AEAD 242 * limit advice from the QRL utility functions. This is intended for testing 243 * use only. Usually set to UINT64_MAX. 244 */ 245 uint64_t txku_threshold_override; 246 247 /* Valid if we are in the TERMINATING or TERMINATED states. */ 248 QUIC_TERMINATE_CAUSE terminate_cause; 249 250 /* 251 * Deadline at which we move to TERMINATING state. Valid if in the 252 * TERMINATING state. 253 */ 254 OSSL_TIME terminate_deadline; 255 256 /* 257 * Deadline at which connection dies due to idle timeout if no further 258 * events occur. 259 */ 260 OSSL_TIME idle_deadline; 261 262 /* 263 * Deadline at which we should send an ACK-eliciting packet to ensure 264 * idle timeout does not occur. 265 */ 266 OSSL_TIME ping_deadline; 267 268 /* 269 * The deadline at which the period in which it is RECOMMENDED that we not 270 * initiate any spontaneous TXKU ends. This is zero if no such deadline 271 * applies. 272 */ 273 OSSL_TIME txku_cooldown_deadline; 274 275 /* 276 * The deadline at which we take the QRX out of UPDATING and back to NORMAL. 277 * Valid if rxku_in_progress in 1. 278 */ 279 OSSL_TIME rxku_update_end_deadline; 280 281 /* 282 * The first (application space) PN sent with a new key phase. Valid if the 283 * QTX key epoch is greater than 0. Once a packet we sent with a PN p (p >= 284 * txku_pn) is ACKed, the TXKU is considered completed and txku_in_progress 285 * becomes 0. For sanity's sake, such a PN p should also be <= the highest 286 * PN we have ever sent, of course. 287 */ 288 QUIC_PN txku_pn; 289 290 /* 291 * The (application space) PN which triggered RXKU detection. Valid if 292 * rxku_pending_confirm. 293 */ 294 QUIC_PN rxku_trigger_pn; 295 296 /* 297 * State tracking. QUIC connection-level state is best represented based on 298 * whether various things have happened yet or not, rather than as an 299 * explicit FSM. We do have a coarse state variable which tracks the basic 300 * state of the connection's lifecycle, but more fine-grained conditions of 301 * the Active state are tracked via flags below. For more details, see 302 * doc/designs/quic-design/connection-state-machine.md. We are in the Open 303 * state if the state is QUIC_CHANNEL_STATE_ACTIVE and handshake_confirmed is 304 * set. 305 */ 306 unsigned int state : 3; 307 308 /* 309 * Have we received at least one encrypted packet from the peer? 310 * (If so, Retry and Version Negotiation messages should no longer 311 * be received and should be ignored if they do occur.) 312 */ 313 unsigned int have_received_enc_pkt : 1; 314 315 /* 316 * Have we successfully processed any packet, including a Version 317 * Negotiation packet? If so, further Version Negotiation packets should be 318 * ignored. 319 */ 320 unsigned int have_processed_any_pkt : 1; 321 322 /* 323 * Have we sent literally any packet yet? If not, there is no point polling 324 * RX. 325 */ 326 unsigned int have_sent_any_pkt : 1; 327 328 /* 329 * Are we currently doing proactive version negotiation? 330 */ 331 unsigned int doing_proactive_ver_neg : 1; 332 333 /* We have received transport parameters from the peer. */ 334 unsigned int got_remote_transport_params : 1; 335 /* We have generated our local transport parameters. */ 336 unsigned int got_local_transport_params : 1; 337 338 /* 339 * This monotonically transitions to 1 once the TLS state machine is 340 * 'complete', meaning that it has both sent a Finished and successfully 341 * verified the peer's Finished (see RFC 9001 s. 4.1.1). Note that it 342 * does not transition to 1 at both peers simultaneously. 343 * 344 * Handshake completion is not the same as handshake confirmation (see 345 * below). 346 */ 347 unsigned int handshake_complete : 1; 348 349 /* 350 * This monotonically transitions to 1 once the handshake is confirmed. 351 * This happens on the client when we receive a HANDSHAKE_DONE frame. 352 * At our option, we may also take acknowledgement of any 1-RTT packet 353 * we sent as a handshake confirmation. 354 */ 355 unsigned int handshake_confirmed : 1; 356 357 /* 358 * We are sending Initial packets based on a Retry. This means we definitely 359 * should not receive another Retry, and if we do it is an error. 360 */ 361 unsigned int doing_retry : 1; 362 363 /* 364 * We don't store the current EL here; the TXP asks the QTX which ELs 365 * are provisioned to determine which ELs to use. 366 */ 367 368 /* Have statm, qsm been initialised? Used to track cleanup. */ 369 unsigned int have_statm : 1; 370 unsigned int have_qsm : 1; 371 372 /* 373 * Preferred ELs for transmission and reception. This is not strictly needed 374 * as it can be inferred from what keys we have provisioned, but makes 375 * determining the current EL simpler and faster. A separate EL for 376 * transmission and reception is not strictly necessary but makes things 377 * easier for interoperation with the handshake layer, which likes to invoke 378 * the yield secret callback at different times for TX and RX. 379 */ 380 unsigned int tx_enc_level : 3; 381 unsigned int rx_enc_level : 3; 382 383 /* If bit n is set, EL n has been discarded. */ 384 unsigned int el_discarded : 4; 385 386 /* 387 * While in TERMINATING - CLOSING, set when we should generate a connection 388 * close frame. 389 */ 390 unsigned int conn_close_queued : 1; 391 392 /* Are we in server mode? Never changes after instantiation. */ 393 unsigned int is_server : 1; 394 395 /* 396 * Set temporarily when the handshake layer has given us a new RX secret. 397 * Used to determine if we need to check our RX queues again. 398 */ 399 unsigned int have_new_rx_secret : 1; 400 401 /* Have we ever called QUIC_TLS yet during RX processing? */ 402 unsigned int did_tls_tick : 1; 403 /* Has any CRYPTO frame been processed during this tick? */ 404 unsigned int did_crypto_frame : 1; 405 406 /* 407 * Have we sent an ack-eliciting packet since the last successful packet 408 * reception? Used to determine when to bump idle timer (see RFC 9000 s. 409 * 10.1). 410 */ 411 unsigned int have_sent_ack_eliciting_since_rx : 1; 412 413 /* Should incoming streams automatically be rejected? */ 414 unsigned int incoming_stream_auto_reject : 1; 415 416 /* 417 * 1 if a key update sequence was locally initiated, meaning we sent the 418 * TXKU first and the resultant RXKU shouldn't result in our triggering 419 * another TXKU. 0 if a key update sequence was initiated by the peer, 420 * meaning we detect a RXKU first and have to generate a TXKU in response. 421 */ 422 unsigned int ku_locally_initiated : 1; 423 424 /* 425 * 1 if we have triggered TXKU (whether spontaneous or solicited) but are 426 * waiting for any PN using that new KP to be ACKed. While this is set, we 427 * are not allowed to trigger spontaneous TXKU (but solicited TXKU is 428 * potentially still possible). 429 */ 430 unsigned int txku_in_progress : 1; 431 432 /* 433 * We have received an RXKU event and currently are going through 434 * UPDATING/COOLDOWN on the QRX. COOLDOWN is currently not used. Since RXKU 435 * cannot be detected in this state, this doesn't cause a protocol error or 436 * anything similar if a peer tries TXKU in this state. That traffic would 437 * simply be dropped. It's only used to track that our UPDATING timer is 438 * active so we know when to take the QRX out of UPDATING and back to 439 * NORMAL. 440 */ 441 unsigned int rxku_in_progress : 1; 442 443 /* 444 * We have received an RXKU but have yet to send an ACK for it, which means 445 * no further RXKUs are allowed yet. Note that we cannot detect further 446 * RXKUs anyway while the QRX remains in the UPDATING/COOLDOWN states, so 447 * this restriction comes into play if we take more than PTO time to send 448 * an ACK for it (not likely). 449 */ 450 unsigned int rxku_pending_confirm : 1; 451 452 /* Temporary variable indicating rxku_pending_confirm is to become 0. */ 453 unsigned int rxku_pending_confirm_done : 1; 454 455 /* 456 * If set, RXKU is expected (because we initiated a spontaneous TXKU). 457 */ 458 unsigned int rxku_expected : 1; 459 460 /* Permanent net error encountered */ 461 unsigned int net_error : 1; 462 463 /* 464 * Protocol error encountered. Note that you should refer to the state field 465 * rather than this. This is only used so we can ignore protocol errors 466 * after the first protocol error, but still record the first protocol error 467 * if it happens during the TERMINATING state. 468 */ 469 unsigned int protocol_error : 1; 470 471 /* Are we using addressed mode? */ 472 unsigned int addressed_mode : 1; 473 474 /* Are we on the QUIC_PORT linked list of channels? */ 475 unsigned int on_port_list : 1; 476 477 /* Has qlog been requested? */ 478 unsigned int use_qlog : 1; 479 480 /* Has qlog been requested? */ 481 unsigned int is_tserver_ch : 1; 482 /* 483 * RFC 9000 Section 9.2.1 says: 484 * However, an endpoint SHOULD NOT send multiple 485 * PATH_CHALLENGE frames in a single packet. 486 * The counter here allows us to detect multiple presence 487 * of PATH_CHALLENGE frame in packet. We process only the 488 * first PATH_CHALLENGE frame found in packet. Remaining PATH_CHALLENGE 489 * frames are ignored. 490 * seen_path_challenge flag is always reset before 491 * ossl_quic_handle_frames() gets called. 492 */ 493 unsigned int seen_path_challenge : 1; 494 495 /* Saved error stack in case permanent error was encountered */ 496 ERR_STATE *err_state; 497 498 /* Scratch area for use by RXDP to store decoded ACK ranges. */ 499 OSSL_QUIC_ACK_RANGE *ack_range_scratch; 500 size_t num_ack_range_scratch; 501 502 /* Title for qlog purposes. We own this copy. */ 503 char *qlog_title; 504 /* 505 * number of path responses waiting to be dispatched 506 * from control frame queue (CFQ) 507 */ 508 unsigned int path_response_limit; 509 /* number of path challenge frames received */ 510 unsigned int path_challenge_rx; 511 /* number of path response frames sent */ 512 unsigned int path_response_tx; 513 }; 514 515 #endif 516 517 #endif 518
Indexes created Fri Jun 26 00:24:39 UTC 2026