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