include/internal/quic_channel.h

   1 /*
   2  * Copyright 2022 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
  20 # ifndef OPENSSL_NO_QUIC
  21
  22 /*
  23  * QUIC Channel
  24  * ============
  25  *
  26  * A QUIC channel (QUIC_CHANNEL) is an object which binds together all of the
  27  * various pieces of QUIC into a single top-level object, and handles connection
  28  * state which is not specific to the client or server roles. In particular, it
  29  * is strictly separated from the libssl front end I/O API personality layer,
  30  * and is not an SSL object.
  31  *
  32  * The name QUIC_CHANNEL is chosen because QUIC_CONNECTION is already in use,
  33  * but functionally these relate to the same thing (a QUIC connection). The use
  34  * of two separate objects ensures clean separation between the API personality
  35  * layer and common code for handling connections, and between the functionality
  36  * which is specific to clients and which is specific to servers, and the
  37  * functionality which is common to both.
  38  *
  39  * The API personality layer provides SSL objects (e.g. a QUIC_CONNECTION) which
  40  * consume a QUIC channel and implement a specific public API. Things which are
  41  * handled by the API personality layer include emulation of blocking semantics,
  42  * handling of SSL object mode flags like non-partial write mode, etc.
  43  *
  44  * Where the QUIC_CHANNEL is used in a server role, there is one QUIC_CHANNEL
  45  * per connection. In the future a QUIC Channel Manager will probably be defined
  46  * to handle ownership of resources which are shared between connections (e.g.
  47  * demuxers). Since we only use server-side functionality for dummy test servers
  48  * for now, which only need to handle one connection at a time, this is not
  49  * currently modelled.
  50  */
  51
  52 #  define QUIC_CHANNEL_STATE_IDLE                        0
  53 #  define QUIC_CHANNEL_STATE_ACTIVE                      1
  54 #  define QUIC_CHANNEL_STATE_TERMINATING_CLOSING         2
  55 #  define QUIC_CHANNEL_STATE_TERMINATING_DRAINING        3
  56 #  define QUIC_CHANNEL_STATE_TERMINATED                  4
  57
  58 typedef struct quic_channel_args_st {
  59     OSSL_LIB_CTX *libctx;
  60     const char *propq;
  61     int is_server;
  62     SSL *tls;
  63 } QUIC_CHANNEL_ARGS;
  64
  65 typedef struct quic_channel_st QUIC_CHANNEL;
  66
  67 /* Represents the cause for a connection's termination. */
  68 typedef struct quic_terminate_cause_st {
  69     /*
  70      * If we are in a TERMINATING or TERMINATED state, this is the error code
  71      * associated with the error. This field is valid iff we are in the
  72      * TERMINATING or TERMINATED states.
  73      */
  74     uint64_t                        error_code;
  75
  76     /*
  77      * If terminate_app is set and this is nonzero, this is the frame type which
  78      * caused the connection to be terminated.
  79      */
  80     uint64_t                        frame_type;
  81
  82     /* Is this error code in the transport (0) or application (1) space? */
  83     unsigned int                    app : 1;
  84
  85     /*
  86      * If set, the cause of the termination is a received CONNECTION_CLOSE
  87      * frame. Otherwise, we decided to terminate ourselves and sent a
  88      * CONNECTION_CLOSE frame (regardless of whether the peer later also sends
  89      * one).
  90      */
  91     unsigned int                    remote : 1;
  92 } QUIC_TERMINATE_CAUSE;
  93
  94
  95 /*
  96  * Create a new QUIC channel using the given arguments. The argument structure
  97  * does not need to remain allocated. Returns NULL on failure.
  98  */
  99 QUIC_CHANNEL *ossl_quic_channel_new(const QUIC_CHANNEL_ARGS *args);
 100
 101 /* No-op if ch is NULL. */
 102 void ossl_quic_channel_free(QUIC_CHANNEL *ch);
 103
 104 /* Set mutator callbacks for test framework support */
 105 int ossl_quic_channel_set_mutator(QUIC_CHANNEL *ch,
 106                                   ossl_mutate_packet_cb mutatecb,
 107                                   ossl_finish_mutate_cb finishmutatecb,
 108                                   void *mutatearg);
 109
 110 /*
 111  * Connection Lifecycle Events
 112  * ===========================
 113  *
 114  * Various events that can be raised on the channel by other parts of the QUIC
 115  * implementation. Some of these are suitable for general use by any part of the
 116  * code (e.g. ossl_quic_channel_raise_protocol_error), others are for very
 117  * specific use by particular components only (e.g.
 118  * ossl_quic_channel_on_handshake_confirmed).
 119  */
 120
 121 /*
 122  * To be used by a QUIC connection. Starts the channel. For a client-mode
 123  * channel, this starts sending the first handshake layer message, etc. Can only
 124  * be called in the idle state; successive calls are ignored.
 125  */
 126 int ossl_quic_channel_start(QUIC_CHANNEL *ch);
 127
 128 /* Start a locally initiated connection shutdown. */
 129 void ossl_quic_channel_local_close(QUIC_CHANNEL *ch, uint64_t app_error_code);
 130
 131 /*
 132  * Called when the handshake is confirmed.
 133  */
 134 int ossl_quic_channel_on_handshake_confirmed(QUIC_CHANNEL *ch);
 135
 136 /*
 137  * Raises a protocol error. This is intended to be the universal call suitable
 138  * for handling of all peer-triggered protocol violations or errors detected by
 139  * us. We specify a QUIC transport-scope error code and optional frame type
 140  * which was responsible. If a frame type is not applicable, specify zero. The
 141  * reason string is not currently handled, but should be a string of static
 142  * storage duration. If the connection has already terminated due to a previous
 143  * protocol error, this is a no-op; first error wins.
 144  */
 145 void ossl_quic_channel_raise_protocol_error(QUIC_CHANNEL *ch,
 146                                             uint64_t error_code,
 147                                             uint64_t frame_type,
 148                                             const char *reason);
 149
 150 /* For RXDP use. */
 151 void ossl_quic_channel_on_remote_conn_close(QUIC_CHANNEL *ch,
 152                                             OSSL_QUIC_FRAME_CONN_CLOSE *f);
 153
 154 /*
 155  * Queries and Accessors
 156  * =====================
 157  */
 158
 159 /* Gets the reactor which can be used to tick/poll on the channel. */
 160 QUIC_REACTOR *ossl_quic_channel_get_reactor(QUIC_CHANNEL *ch);
 161
 162 /* Gets the QSM used with the channel. */
 163 QUIC_STREAM_MAP *ossl_quic_channel_get_qsm(QUIC_CHANNEL *ch);
 164
 165 /* Gets the statistics manager used with the channel. */
 166 OSSL_STATM *ossl_quic_channel_get_statm(QUIC_CHANNEL *ch);
 167
 168 /*
 169  * Gets/sets the current peer address. Generally this should be used before
 170  * starting a channel in client mode.
 171  */
 172 int ossl_quic_channel_get_peer_addr(QUIC_CHANNEL *ch, BIO_ADDR *peer_addr);
 173 int ossl_quic_channel_set_peer_addr(QUIC_CHANNEL *ch, const BIO_ADDR *peer_addr);
 174
 175 /* Gets/sets the underlying network read and write BIOs. */
 176 BIO *ossl_quic_channel_get_net_rbio(QUIC_CHANNEL *ch);
 177 BIO *ossl_quic_channel_get_net_wbio(QUIC_CHANNEL *ch);
 178 int ossl_quic_channel_set_net_rbio(QUIC_CHANNEL *ch, BIO *net_rbio);
 179 int ossl_quic_channel_set_net_wbio(QUIC_CHANNEL *ch, BIO *net_wbio);
 180
 181 /*
 182  * Returns an existing stream by stream ID. Returns NULL if the stream does not
 183  * exist.
 184  */
 185 QUIC_STREAM *ossl_quic_channel_get_stream_by_id(QUIC_CHANNEL *ch,
 186                                                 uint64_t stream_id);
 187
 188 /* Returns 1 if channel is terminating or terminated. */
 189 int ossl_quic_channel_is_term_any(const QUIC_CHANNEL *ch,
 190                                   QUIC_TERMINATE_CAUSE *cause);
 191 int ossl_quic_channel_is_terminating(const QUIC_CHANNEL *ch,
 192                                      QUIC_TERMINATE_CAUSE *cause);
 193 int ossl_quic_channel_is_terminated(const QUIC_CHANNEL *ch,
 194                                     QUIC_TERMINATE_CAUSE *cause);
 195 int ossl_quic_channel_is_active(const QUIC_CHANNEL *ch);
 196 int ossl_quic_channel_is_handshake_complete(const QUIC_CHANNEL *ch);
 197
 198 # endif
 199
 200 #endif