include/internal/quic_channel.h

   1 /*
   2  * Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #ifndef OSSL_QUIC_CHANNEL_H
  11 # define OSSL_QUIC_CHANNEL_H
  12
  13 # include <openssl/ssl.h>
  14 # include "internal/quic_types.h"
  15 # include "internal/quic_record_tx.h"
  16 # include "internal/quic_wire.h"
  17 # include "internal/quic_predef.h"
  18 # include "internal/qlog.h"
  19 # include "internal/time.h"
  20 # include "internal/thread.h"
  21
  22 # ifndef OPENSSL_NO_QUIC
  23
  24 /*
  25  * QUIC Channel
  26  * ============
  27  *
  28  * A QUIC channel (QUIC_CHANNEL) is an object which binds together all of the
  29  * various pieces of QUIC into a single top-level object, and handles connection
  30  * state which is not specific to the client or server roles. In particular, it
  31  * is strictly separated from the libssl front end I/O API personality layer,
  32  * and is not an SSL object.
  33  *
  34  * The name QUIC_CHANNEL is chosen because QUIC_CONNECTION is already in use,
  35  * but functionally these relate to the same thing (a QUIC connection). The use
  36  * of two separate objects ensures clean separation between the API personality
  37  * layer and common code for handling connections, and between the functionality
  38  * which is specific to clients and which is specific to servers, and the
  39  * functionality which is common to both.
  40  *
  41  * The API personality layer provides SSL objects (e.g. a QUIC_CONNECTION) which
  42  * consume a QUIC channel and implement a specific public API. Things which are
  43  * handled by the API personality layer include emulation of blocking semantics,
  44  * handling of SSL object mode flags like non-partial write mode, etc.
  45  *
  46  * Where the QUIC_CHANNEL is used in a server role, there is one QUIC_CHANNEL
  47  * per connection. In the future a QUIC Channel Manager will probably be defined
  48  * to handle ownership of resources which are shared between connections (e.g.
  49  * demuxers). Since we only use server-side functionality for dummy test servers
  50  * for now, which only need to handle one connection at a time, this is not
  51  * currently modelled.
  52  *
  53  * Synchronisation
  54  * ---------------
  55  *
  56  * To support thread assisted mode, QUIC_CHANNEL can be used by multiple
  57  * threads. **It is the caller's responsibility to ensure that the QUIC_CHANNEL
  58  * is only accessed (whether via its methods or via direct access to its state)
  59  * while the channel mutex is held**, except for methods explicitly marked as
  60  * not requiring prior locking. This is an unchecked precondition.
  61  *
  62  * The instantiator of the channel is responsible for providing a suitable
  63  * mutex which then serves as the channel mutex; see QUIC_CHANNEL_ARGS.
  64  */
  65
  66 /*
  67  * The function does not acquire the channel mutex and assumes it is already
  68  * held by the calling thread.
  69  *
  70  * Any function tagged with this has the following precondition:
  71  *
  72  *   Precondition: must hold channel mutex (unchecked)
  73  */
  74 #  define QUIC_NEEDS_LOCK
  75
  76 /*
  77  * The function acquires the channel mutex and releases it before returning in
  78  * all circumstances.
  79  *
  80  * Any function tagged with this has the following precondition and
  81  * postcondition:
  82  *
  83  *   Precondition: must not hold channel mutex (unchecked)
  84  *   Postcondition: channel mutex is not held (by calling thread)
  85  */
  86 #  define QUIC_TAKES_LOCK
  87
  88 /*
  89  * The function acquires the channel mutex and leaves it acquired
  90  * when returning success.
  91  *
  92  * Any function tagged with this has the following precondition and
  93  * postcondition:
  94  *
  95  *   Precondition: must not hold channel mutex (unchecked)
  96  *   Postcondition: channel mutex is held by calling thread
  97  *      or function returned failure
  98  */
  99 #  define QUIC_ACQUIRES_LOCK
 100
 101 #  define QUIC_TODO_LOCK
 102
 103 #  define QUIC_CHANNEL_STATE_IDLE                        0
 104 #  define QUIC_CHANNEL_STATE_ACTIVE                      1
 105 #  define QUIC_CHANNEL_STATE_TERMINATING_CLOSING         2
 106 #  define QUIC_CHANNEL_STATE_TERMINATING_DRAINING        3
 107 #  define QUIC_CHANNEL_STATE_TERMINATED                  4
 108
 109 typedef struct quic_channel_args_st {
 110     /*
 111      * The QUIC_PORT which the channel is to belong to. The lifetime of the
 112      * QUIC_PORT must exceed that of the created channel.
 113      */
 114     QUIC_PORT       *port;
 115     /* LCIDM to register LCIDs with. */
 116     QUIC_LCIDM      *lcidm;
 117     /* SRTM to register SRTs with. */
 118     QUIC_SRTM       *srtm;
 119
 120     int             is_server;
 121     SSL             *tls;
 122
 123     /* Whether to use qlog. */
 124     int             use_qlog;
 125
 126     /* Title to use for the qlog session, or NULL. */
 127     const char      *qlog_title;
 128 } QUIC_CHANNEL_ARGS;
 129
 130 /* Represents the cause for a connection's termination. */
 131 typedef struct quic_terminate_cause_st {
 132     /*
 133      * If we are in a TERMINATING or TERMINATED state, this is the error code
 134      * associated with the error. This field is valid iff we are in the
 135      * TERMINATING or TERMINATED states.
 136      */
 137     uint64_t                        error_code;
 138
 139     /*
 140      * If terminate_app is set and this is nonzero, this is the frame type which
 141      * caused the connection to be terminated.
 142      */
 143     uint64_t                        frame_type;
 144
 145     /*
 146      * Optional reason string. When calling ossl_quic_channel_local_close, if a
 147      * reason string pointer is passed, it is copied and stored inside
 148      * QUIC_CHANNEL for the remainder of the lifetime of the channel object.
 149      * Thus the string pointed to by this value, if non-NULL, is valid for the
 150      * lifetime of the QUIC_CHANNEL object.
 151      */
 152     const char                      *reason;
 153
 154     /*
 155      * Length of reason in bytes. The reason is supposed to contain a UTF-8
 156      * string but may be arbitrary data if the reason came from the network.
 157      */
 158     size_t                          reason_len;
 159
 160     /* Is this error code in the transport (0) or application (1) space? */
 161     unsigned int                    app : 1;
 162
 163     /*
 164      * If set, the cause of the termination is a received CONNECTION_CLOSE
 165      * frame. Otherwise, we decided to terminate ourselves and sent a
 166      * CONNECTION_CLOSE frame (regardless of whether the peer later also sends
 167      * one).
 168      */
 169     unsigned int                    remote : 1;
 170 } QUIC_TERMINATE_CAUSE;
 171
 172 /*
 173  * Create a new QUIC channel using the given arguments. The argument structure
 174  * does not need to remain allocated. Returns NULL on failure.
 175  *
 176  * Only QUIC_PORT should use this function.
 177  */
 178 QUIC_CHANNEL *ossl_quic_channel_new(const QUIC_CHANNEL_ARGS *args);
 179
 180 /* No-op if ch is NULL. */
 181 void ossl_quic_channel_free(QUIC_CHANNEL *ch);
 182
 183 /* Set mutator callbacks for test framework support */
 184 int ossl_quic_channel_set_mutator(QUIC_CHANNEL *ch,
 185                                   ossl_mutate_packet_cb mutatecb,
 186                                   ossl_finish_mutate_cb finishmutatecb,
 187                                   void *mutatearg);
 188
 189 /*
 190  * Connection Lifecycle Events
 191  * ===========================
 192  *
 193  * Various events that can be raised on the channel by other parts of the QUIC
 194  * implementation. Some of these are suitable for general use by any part of the
 195  * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very
 196  * specific use by particular components only (e.g.
 197  * ossl_quic_channel_on_handshake_confirmed).
 198  */
 199
 200 /*
 201  * To be used by a QUIC connection. Starts the channel. For a client-mode
 202  * channel, this starts sending the first handshake layer message, etc. Can only
 203  * be called in the idle state; successive calls are ignored.
 204  */
 205 int ossl_quic_channel_start(QUIC_CHANNEL *ch);
 206
 207 /* Start a locally initiated connection shutdown. */
 208 void ossl_quic_channel_local_close(QUIC_CHANNEL *ch, uint64_t app_error_code,
 209                                    const char *app_reason);
 210
 211 /*
 212  * Called when the handshake is confirmed.
 213  */
 214 int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL *ch);
 215
 216 /*
 217  * Raises a protocol error. This is intended to be the universal call suitable
 218  * for handling of all peer-triggered protocol violations or errors detected by
 219  * us. We specify a QUIC transport-scope error code and optional frame type
 220  * which was responsible. If a frame type is not applicable, specify zero. The
 221  * reason string is not currently handled, but should be a string of static
 222  * storage duration. If the connection has already terminated due to a previous
 223  * protocol error, this is a no-op; first error wins.
 224  *
 225  * Usually the ossl_quic_channel_raise_protocol_error() function should be used.
 226  * The ossl_quic_channel_raise_protocol_error_loc() function can be used
 227  * directly for passing through existing call site information from an existing
 228  * error.
 229  */
 230 void ossl_quic_channel_raise_protocol_error_loc(QUIC_CHANNEL *ch,
 231                                                 uint64_t error_code,
 232                                                 uint64_t frame_type,
 233                                                 const char *reason,
 234                                                 ERR_STATE *err_state,
 235                                                 const char *src_file,
 236                                                 int src_line,
 237                                                 const char *src_func);
 238
 239 #define ossl_quic_channel_raise_protocol_error(ch, error_code, frame_type, reason) \
 240     ossl_quic_channel_raise_protocol_error_loc((ch), (error_code),  \
 241                                                (frame_type),        \
 242                                                (reason),            \
 243                                                NULL,                \
 244                                                OPENSSL_FILE,        \
 245                                                OPENSSL_LINE,        \
 246                                                OPENSSL_FUNC)
 247
 248 #define ossl_quic_channel_raise_protocol_error_state(ch, error_code, frame_type, reason, state) \
 249     ossl_quic_channel_raise_protocol_error_loc((ch), (error_code),  \
 250                                                (frame_type),        \
 251                                                (reason),            \
 252                                                (state),             \
 253                                                OPENSSL_FILE,        \
 254                                                OPENSSL_LINE,        \
 255                                                OPENSSL_FUNC)
 256
 257
 258 /*
 259  * Returns 1 if permanent net error was detected on the QUIC_CHANNEL,
 260  * 0 otherwise.
 261  */
 262 int ossl_quic_channel_net_error(QUIC_CHANNEL *ch);
 263
 264 /* Restore saved error state (best effort) */
 265 void ossl_quic_channel_restore_err_state(QUIC_CHANNEL *ch);
 266
 267 /* For RXDP use. */
 268 void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch,
 269                                             OSSL_QUIC_FRAME_CONN_CLOSE *f);
 270 void ossl_quic_channel_on_new_conn_id(QUIC_CHANNEL *ch,
 271                                       OSSL_QUIC_FRAME_NEW_CONN_ID *f);
 272
 273 /* Temporarily exposed during QUIC_PORT transition. */
 274 int ossl_quic_channel_on_new_conn(QUIC_CHANNEL *ch, const BIO_ADDR *peer,
 275                                   const QUIC_CONN_ID *peer_scid,
 276                                   const QUIC_CONN_ID *peer_dcid);
 277
 278 /* For use by QUIC_PORT. You should not need to call this directly. */
 279 void ossl_quic_channel_subtick(QUIC_CHANNEL *ch, QUIC_TICK_RESULT *r,
 280                                uint32_t flags);
 281
 282 /* For use by QUIC_PORT only. */
 283 void ossl_quic_channel_raise_net_error(QUIC_CHANNEL *ch);
 284
 285 /* For use by QUIC_PORT only. */
 286 void ossl_quic_channel_on_stateless_reset(QUIC_CHANNEL *ch);
 287
 288 void ossl_quic_channel_inject(QUIC_CHANNEL *ch, QUIC_URXE *e);
 289
 290 /*
 291  * Queries and Accessors
 292  * =====================
 293  */
 294
 295 /* Gets the reactor which can be used to tick/poll on the channel. */
 296 QUIC_REACTOR *ossl_quic_channel_get_reactor(QUIC_CHANNEL *ch);
 297
 298 /* Gets the QSM used with the channel. */
 299 QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch);
 300
 301 /* Gets the statistics manager used with the channel. */
 302 OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch);
 303
 304 /*
 305  * Gets/sets the current peer address. Generally this should be used before
 306  * starting a channel in client mode.
 307  */
 308 int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL *ch, BIO_ADDR *peer_addr);
 309 int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL *ch, const BIO_ADDR *peer_addr);
 310
 311 /*
 312  * Returns an existing stream by stream ID. Returns NULL if the stream does not
 313  * exist.
 314  */
 315 QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch,
 316                                                 uint64_t stream_id);
 317
 318 /* Returns 1 if channel is terminating or terminated. */
 319 int ossl_quic_channel_is_term_any(const QUIC_CHANNEL *ch);
 320 const QUIC_TERMINATE_CAUSE *
 321 ossl_quic_channel_get_terminate_cause(const QUIC_CHANNEL *ch);
 322 int ossl_quic_channel_is_closing(const QUIC_CHANNEL *ch);
 323 int ossl_quic_channel_is_terminated(const QUIC_CHANNEL *ch);
 324 int ossl_quic_channel_is_active(const QUIC_CHANNEL *ch);
 325 int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL *ch);
 326 int ossl_quic_channel_is_handshake_confirmed(const QUIC_CHANNEL *ch);
 327
 328 QUIC_PORT *ossl_quic_channel_get0_port(QUIC_CHANNEL *ch);
 329 QUIC_ENGINE *ossl_quic_channel_get0_engine(QUIC_CHANNEL *ch);
 330 QUIC_DEMUX *ossl_quic_channel_get0_demux(QUIC_CHANNEL *ch);
 331
 332 SSL *ossl_quic_channel_get0_ssl(QUIC_CHANNEL *ch);
 333
 334 /*
 335  * Retrieves a pointer to the channel mutex which was provided at the time the
 336  * channel was instantiated. In order to allow locks to be acquired and released
 337  * with the correct granularity, it is the caller's responsibility to ensure
 338  * this lock is held for write while calling any QUIC_CHANNEL method, except for
 339  * methods explicitly designed otherwise.
 340  *
 341  * This method is thread safe and does not require prior locking. It can also be
 342  * called while the lock is already held. Note that this is simply a convenience
 343  * function to access the mutex which was passed to the channel at instantiation
 344  * time; it does not belong to the channel but rather is presumed to belong to
 345  * the owner of the channel.
 346  */
 347 CRYPTO_MUTEX *ossl_quic_channel_get_mutex(QUIC_CHANNEL *ch);
 348
 349 /*
 350  * Creates a new locally-initiated stream in the stream mapper, choosing an
 351  * appropriate stream ID. If is_uni is 1, creates a unidirectional stream, else
 352  * creates a bidirectional stream. Returns NULL on failure.
 353  */
 354 QUIC_STREAM *ossl_quic_channel_new_stream_local(QUIC_CHANNEL *ch, int is_uni);
 355
 356 /*
 357  * Creates a new remotely-initiated stream in the stream mapper. The stream ID
 358  * is used to confirm the initiator and determine the stream type. The stream is
 359  * automatically added to the QSM's accept queue. A pointer to the stream is
 360  * also returned. Returns NULL on failure.
 361  */
 362 QUIC_STREAM *ossl_quic_channel_new_stream_remote(QUIC_CHANNEL *ch,
 363                                                  uint64_t stream_id);
 364
 365 /*
 366  * Configures incoming stream auto-reject. If enabled, incoming streams have
 367  * both their sending and receiving parts automatically rejected using
 368  * STOP_SENDING and STREAM_RESET frames. aec is the application error
 369  * code to be used for those frames.
 370  */
 371 void ossl_quic_channel_set_incoming_stream_auto_reject(QUIC_CHANNEL *ch,
 372                                                        int enable,
 373                                                        uint64_t aec);
 374
 375 /*
 376  * Causes the channel to reject the sending and receiving parts of a stream,
 377  * as though autorejected. Can be used if a stream has already been
 378  * accepted.
 379  */
 380 void ossl_quic_channel_reject_stream(QUIC_CHANNEL *ch, QUIC_STREAM *qs);
 381
 382 /* Replace local connection ID in TXP and DEMUX for testing purposes. */
 383 int ossl_quic_channel_replace_local_cid(QUIC_CHANNEL *ch,
 384                                         const QUIC_CONN_ID *conn_id);
 385
 386 /* Setters for the msg_callback and msg_callback_arg */
 387 void ossl_quic_channel_set_msg_callback(QUIC_CHANNEL *ch,
 388                                         ossl_msg_cb msg_callback,
 389                                         SSL *msg_callback_ssl);
 390 void ossl_quic_channel_set_msg_callback_arg(QUIC_CHANNEL *ch,
 391                                             void *msg_callback_arg);
 392
 393 /* Testing use only - sets a TXKU threshold packet count override value. */
 394 void ossl_quic_channel_set_txku_threshold_override(QUIC_CHANNEL *ch,
 395                                                    uint64_t tx_pkt_threshold);
 396
 397 /* Testing use only - gets current 1-RTT key epochs for QTX and QRX. */
 398 uint64_t ossl_quic_channel_get_tx_key_epoch(QUIC_CHANNEL *ch);
 399 uint64_t ossl_quic_channel_get_rx_key_epoch(QUIC_CHANNEL *ch);
 400
 401 /* Artificially trigger a spontaneous TXKU if possible. */
 402 int ossl_quic_channel_trigger_txku(QUIC_CHANNEL *ch);
 403 int ossl_quic_channel_has_pending(const QUIC_CHANNEL *ch);
 404
 405 /* Force transmission of an ACK-eliciting packet. */
 406 int ossl_quic_channel_ping(QUIC_CHANNEL *ch);
 407
 408 /*
 409  * These queries exist for diagnostic purposes only. They may roll over.
 410  * Do not rely on them for non-testing purposes.
 411  */
 412 uint16_t ossl_quic_channel_get_diag_num_rx_ack(QUIC_CHANNEL *ch);
 413
 414 /*
 415  * Diagnostic use only. Gets the current local CID.
 416  */
 417 void ossl_quic_channel_get_diag_local_cid(QUIC_CHANNEL *ch, QUIC_CONN_ID *cid);
 418
 419 /*
 420  * Returns 1 if stream count flow control allows us to create a new
 421  * locally-initiated stream.
 422  */
 423 int ossl_quic_channel_is_new_local_stream_admissible(QUIC_CHANNEL *ch, int is_uni);
 424
 425 /*
 426  * Returns the number of additional streams that can currently be created based
 427  * on flow control.
 428  */
 429 uint64_t ossl_quic_channel_get_local_stream_count_avail(const QUIC_CHANNEL *ch,
 430                                                         int is_uni);
 431 uint64_t ossl_quic_channel_get_remote_stream_count_avail(const QUIC_CHANNEL *ch,
 432                                                          int is_uni);
 433
 434 /*
 435  * Returns 1 if we have generated our local transport parameters yet.
 436  */
 437 int ossl_quic_channel_have_generated_transport_params(const QUIC_CHANNEL *ch);
 438
 439 /* Configures the idle timeout to request from peer (milliseconds, 0=no timeout). */
 440 void ossl_quic_channel_set_max_idle_timeout_request(QUIC_CHANNEL *ch, uint64_t ms);
 441 /* Get the configured idle timeout to request from peer. */
 442 uint64_t ossl_quic_channel_get_max_idle_timeout_request(const QUIC_CHANNEL *ch);
 443 /* Get the idle timeout requested by the peer. */
 444 uint64_t ossl_quic_channel_get_max_idle_timeout_peer_request(const QUIC_CHANNEL *ch);
 445 /* Get the idle timeout actually negotiated. */
 446 uint64_t ossl_quic_channel_get_max_idle_timeout_actual(const QUIC_CHANNEL *ch);
 447
 448 # endif
 449
 450 #endif