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 #  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