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