ssl/quic/quic_channel_local.h

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