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