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 extention 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_RWLOCK                   *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     /* Connection level FC. */
  73     QUIC_TXFC                       conn_txfc;
  74     QUIC_RXFC                       conn_rxfc;
  75     QUIC_STREAM_MAP                 qsm;
  76     OSSL_STATM                      statm;
  77     OSSL_CC_DATA                    *cc_data;
  78     const OSSL_CC_METHOD            *cc_method;
  79     OSSL_ACKM                       *ackm;
  80
  81     /*
  82      * RX demuxer. We register incoming DCIDs with this. Since we currently only
  83      * support client operation and use one L4 port per connection, we own the
  84      * demuxer and register a single zero-length DCID with it.
  85      */
  86     QUIC_DEMUX                      *demux;
  87
  88     /* Record layers in the TX and RX directions, plus the RX demuxer. */
  89     OSSL_QTX                        *qtx;
  90     OSSL_QRX                        *qrx;
  91
  92     /*
  93      * Send and receive parts of the crypto streams.
  94      * crypto_send[QUIC_PN_SPACE_APP] is the 1-RTT crypto stream. There is no
  95      * 0-RTT crypto stream.
  96      */
  97     QUIC_SSTREAM                    *crypto_send[QUIC_PN_SPACE_NUM];
  98     QUIC_RSTREAM                    *crypto_recv[QUIC_PN_SPACE_NUM];
  99
 100     /*
 101      * Our (currently only) application data stream. This is a bidirectional
 102      * client-initiated stream and thus (in QUICv1) always has a stream ID of 0.
 103      */
 104     QUIC_STREAM                     *stream0;
 105
 106     /* Internal state. */
 107     /*
 108      * Client: The DCID used in the first Initial packet we transmit as a client.
 109      * Server: The DCID used in the first Initial packet the client transmitted.
 110      * Randomly generated and required by RFC to be at least 8 bytes.
 111      */
 112     QUIC_CONN_ID                    init_dcid;
 113
 114     /*
 115      * Client: The SCID found in the first Initial packet from the server.
 116      * Not valid for servers.
 117      * Valid if have_received_enc_pkt is set.
 118      */
 119     QUIC_CONN_ID                    init_scid;
 120
 121     /*
 122      * Client only: The SCID found in an incoming Retry packet we handled.
 123      * Not valid for servers.
 124      */
 125     QUIC_CONN_ID                    retry_scid;
 126
 127     /* Server only: The DCID we currently use to talk to the peer. */
 128     QUIC_CONN_ID                    cur_remote_dcid;
 129     /* Server only: The DCID we currently expect the peer to use to talk to us. */
 130     QUIC_CONN_ID                    cur_local_dcid;
 131
 132     /* Transport parameter values received from server. */
 133     uint64_t                        init_max_stream_data_bidi_local;
 134     uint64_t                        init_max_stream_data_bidi_remote;
 135     uint64_t                        init_max_stream_data_uni_remote;
 136     uint64_t                        rx_max_ack_delay; /* ms */
 137     unsigned char                   rx_ack_delay_exp;
 138
 139     /*
 140      * Temporary staging area to store information about the incoming packet we
 141      * are currently processing.
 142      */
 143     OSSL_QRX_PKT                    *qrx_pkt;
 144
 145     /*
 146      * Current limit on number of streams we may create. Set by transport
 147      * parameters initially and then by MAX_STREAMS frames.
 148      */
 149     uint64_t                        max_local_streams_bidi;
 150     uint64_t                        max_local_streams_uni;
 151
 152     /* The negotiated maximum idle timeout in milliseconds. */
 153     uint64_t                        max_idle_timeout;
 154
 155     /*
 156      * Maximum payload size in bytes for datagrams sent to our peer, as
 157      * negotiated by transport parameters.
 158      */
 159     uint64_t                        rx_max_udp_payload_size;
 160     /* Maximum active CID limit, as negotiated by transport parameters. */
 161     uint64_t                        rx_active_conn_id_limit;
 162
 163     /* Valid if we are in the TERMINATING or TERMINATED states. */
 164     QUIC_TERMINATE_CAUSE            terminate_cause;
 165
 166     /*
 167      * Deadline at which we move to TERMINATING state. Valid if in the
 168      * TERMINATING state.
 169      */
 170     OSSL_TIME                       terminate_deadline;
 171
 172     /*
 173      * Deadline at which connection dies due to idle timeout if no further
 174      * events occur.
 175      */
 176     OSSL_TIME                       idle_deadline;
 177
 178     /*
 179      * Deadline at which we should send an ACK-eliciting packet to ensure
 180      * idle timeout does not occur.
 181      */
 182     OSSL_TIME                       ping_deadline;
 183
 184     /*
 185      * State tracking. QUIC connection-level state is best represented based on
 186      * whether various things have happened yet or not, rather than as an
 187      * explicit FSM. We do have a coarse state variable which tracks the basic
 188      * state of the connection's lifecycle, but more fine-grained conditions of
 189      * the Active state are tracked via flags below. For more details, see
 190      * doc/designs/quic-design/connection-state-machine.md. We are in the Open
 191      * state if the state is QUIC_CSM_STATE_ACTIVE and handshake_confirmed is
 192      * set.
 193      */
 194     unsigned int                    state                   : 3;
 195
 196     /*
 197      * Have we received at least one encrypted packet from the peer?
 198      * (If so, Retry and Version Negotiation messages should no longer
 199      *  be received and should be ignored if they do occur.)
 200      */
 201     unsigned int                    have_received_enc_pkt   : 1;
 202
 203     /*
 204      * Have we sent literally any packet yet? If not, there is no point polling
 205      * RX.
 206      */
 207     unsigned int                    have_sent_any_pkt       : 1;
 208
 209     /*
 210      * Are we currently doing proactive version negotiation?
 211      */
 212     unsigned int                    doing_proactive_ver_neg : 1;
 213
 214     /* We have received transport parameters from the peer. */
 215     unsigned int                    got_remote_transport_params    : 1;
 216
 217     /*
 218      * This monotonically transitions to 1 once the TLS state machine is
 219      * 'complete', meaning that it has both sent a Finished and successfully
 220      * verified the peer's Finished (see RFC 9001 s. 4.1.1). Note that it
 221      * does not transition to 1 at both peers simultaneously.
 222      *
 223      * Handshake completion is not the same as handshake confirmation (see
 224      * below).
 225      */
 226     unsigned int                    handshake_complete      : 1;
 227
 228     /*
 229      * This monotonically transitions to 1 once the handshake is confirmed.
 230      * This happens on the client when we receive a HANDSHAKE_DONE frame.
 231      * At our option, we may also take acknowledgement of any 1-RTT packet
 232      * we sent as a handshake confirmation.
 233      */
 234     unsigned int                    handshake_confirmed     : 1;
 235
 236     /*
 237      * We are sending Initial packets based on a Retry. This means we definitely
 238      * should not receive another Retry, and if we do it is an error.
 239      */
 240     unsigned int                    doing_retry             : 1;
 241
 242     /*
 243      * We don't store the current EL here; the TXP asks the QTX which ELs
 244      * are provisioned to determine which ELs to use.
 245      */
 246
 247     /* Have statm, qsm been initialised? Used to track cleanup. */
 248     unsigned int                    have_statm              : 1;
 249     unsigned int                    have_qsm                : 1;
 250
 251     /*
 252      * Preferred ELs for transmission and reception. This is not strictly needed
 253      * as it can be inferred from what keys we have provisioned, but makes
 254      * determining the current EL simpler and faster. A separate EL for
 255      * transmission and reception is not strictly necessary but makes things
 256      * easier for interoperation with the handshake layer, which likes to invoke
 257      * the yield secret callback at different times for TX and RX.
 258      */
 259     unsigned int                    tx_enc_level            : 3;
 260     unsigned int                    rx_enc_level            : 3;
 261
 262     /* If bit n is set, EL n has been discarded. */
 263     unsigned int                    el_discarded            : 4;
 264
 265     /*
 266      * While in TERMINATING - CLOSING, set when we should generate a connection
 267      * close frame.
 268      */
 269     unsigned int                    conn_close_queued       : 1;
 270
 271     /* Are we in server mode? Never changes after instantiation. */
 272     unsigned int                    is_server               : 1;
 273
 274     /*
 275      * Set temporarily when the handshake layer has given us a new RX secret.
 276      * Used to determine if we need to check our RX queues again.
 277      */
 278     unsigned int                    have_new_rx_secret      : 1;
 279
 280     /*
 281      * Have we sent an ack-eliciting packet since the last successful packet
 282      * reception? Used to determine when to bump idle timer (see RFC 9000 s.
 283      * 10.1).
 284      */
 285     unsigned int                    have_sent_ack_eliciting_since_rx    : 1;
 286 };
 287
 288 # endif
 289
 290 #endif