include/internal/quic_port.h

   1 /*
   2  * Copyright 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 #ifndef OSSL_QUIC_PORT_H
  10 # define OSSL_QUIC_PORT_H
  11
  12 # include <openssl/ssl.h>
  13 # include "internal/quic_types.h"
  14 # include "internal/quic_reactor.h"
  15 # include "internal/quic_demux.h"
  16 # include "internal/quic_predef.h"
  17 # include "internal/thread_arch.h"
  18
  19 # ifndef OPENSSL_NO_QUIC
  20
  21 /*
  22  * QUIC Port
  23  * =========
  24  *
  25  * A QUIC Port (QUIC_PORT) represents a single UDP network socket and contains
  26  * zero or more subsidiary QUIC_CHANNEL instances, each of which represents a
  27  * single QUIC connection. All QUIC_CHANNEL instances must belong to a
  28  * QUIC_PORT.
  29  *
  30  * A QUIC port is responsible for managing a set of channels which all use the
  31  * same UDP socket, and (in future) for automatically creating new channels when
  32  * incoming connections are received.
  33  *
  34  * In order to retain compatibility with QUIC_TSERVER, it also supports a point
  35  * of legacy compatibility where a caller can create an incoming (server role)
  36  * channel and that channel will be automatically be bound to the next incoming
  37  * connection. In the future this will go away once QUIC_TSERVER is removed.
  38  */
  39 typedef struct quic_port_args_st {
  40     /* All channels in a QUIC event domain share the same (libctx, propq). */
  41     OSSL_LIB_CTX    *libctx;
  42     const char      *propq;
  43
  44     /*
  45      * This must be a mutex the lifetime of which will exceed that of the port
  46      * and all channels. The instantiator of the port is responsible for
  47      * providing a mutex as this makes it easier to handle instantiation and
  48      * teardown of channels in situations potentially requiring locking.
  49      *
  50      * Note that this is a MUTEX not a RWLOCK as it needs to be an OS mutex for
  51      * compatibility with an OS's condition variable wait API, whereas RWLOCK
  52      * may, depending on the build configuration, be implemented using an OS's
  53      * mutex primitive or using its RW mutex primitive.
  54      */
  55     CRYPTO_MUTEX    *mutex;
  56
  57     /*
  58      * Optional function pointer to use to retrieve the current time. If NULL,
  59      * ossl_time_now() is used.
  60      */
  61     OSSL_TIME       (*now_cb)(void *arg);
  62     void            *now_cb_arg;
  63
  64     /*
  65      * This SSL_CTX will be used when constructing the handshake layer object
  66      * inside newly created channels.
  67      */
  68     SSL_CTX         *channel_ctx;
  69
  70     /*
  71      * If 1, this port is to be used for multiple connections, so
  72      * non-zero-length CIDs should be used. If 0, this port will only be used
  73      * for a single connection, so a zero-length local CID can be used.
  74      */
  75     int             is_multi_conn;
  76 } QUIC_PORT_ARGS;
  77
  78 QUIC_PORT *ossl_quic_port_new(const QUIC_PORT_ARGS *args);
  79
  80 void ossl_quic_port_free(QUIC_PORT *port);
  81
  82 /*
  83  * Operations
  84  * ==========
  85  */
  86
  87 /* Create an outgoing channel using this port. */
  88 QUIC_CHANNEL *ossl_quic_port_create_outgoing(QUIC_PORT *port, SSL *tls);
  89
  90 /*
  91  * Create an incoming channel using this port. XXX for temporary TSERVER use
  92  * only - will be removed.
  93  */
  94 QUIC_CHANNEL *ossl_quic_port_create_incoming(QUIC_PORT *port, SSL *tls);
  95
  96 /*
  97  * Queries and Accessors
  98  * =====================
  99  */
 100
 101 /* Gets/sets the underlying network read and write BIO. */
 102 BIO *ossl_quic_port_get_net_rbio(QUIC_PORT *port);
 103 BIO *ossl_quic_port_get_net_wbio(QUIC_PORT *port);
 104 int ossl_quic_port_set_net_rbio(QUIC_PORT *port, BIO *net_rbio);
 105 int ossl_quic_port_set_net_wbio(QUIC_PORT *port, BIO *net_wbio);
 106
 107 /*
 108  * Re-poll the network BIOs already set to determine if their support
 109  * for polling has changed.
 110  */
 111 int ossl_quic_port_update_poll_descriptors(QUIC_PORT *port);
 112
 113 /* Gets the reactor which can be used to tick/poll on the port. */
 114 QUIC_REACTOR *ossl_quic_port_get0_reactor(QUIC_PORT *port);
 115
 116 /* Gets the demuxer belonging to the port. */
 117 QUIC_DEMUX *ossl_quic_port_get0_demux(QUIC_PORT *port);
 118
 119 /* Gets the mutex used by the port. */
 120 CRYPTO_MUTEX *ossl_quic_port_get0_mutex(QUIC_PORT *port);
 121
 122 /* Gets the current time. */
 123 OSSL_TIME ossl_quic_port_get_time(QUIC_PORT *port);
 124
 125 int ossl_quic_port_get_rx_short_dcid_len(const QUIC_PORT *port);
 126 int ossl_quic_port_get_tx_init_dcid_len(const QUIC_PORT *port);
 127
 128 /* For testing use. While enabled, ticking is not performed. */
 129 void ossl_quic_port_set_inhibit_tick(QUIC_PORT *port, int inhibit);
 130
 131 /* Returns 1 if the port is running/healthy, 0 if it has failed. */
 132 int ossl_quic_port_is_running(const QUIC_PORT *port);
 133
 134 /*
 135  * Restores port-level error to the error stack. To be called only if
 136  * the port is no longer running.
 137  */
 138 void ossl_quic_port_restore_err_state(const QUIC_PORT *port);
 139
 140 /*
 141  * Events
 142  * ======
 143  */
 144
 145 /*
 146  * Called if a permanent network error occurs. Terminates all channels
 147  * immediately. triggering_ch is an optional argument designating
 148  * a channel which encountered the network error.
 149  */
 150 void ossl_quic_port_raise_net_error(QUIC_PORT *port,
 151                                     QUIC_CHANNEL *triggering_ch);
 152
 153 # endif
 154
 155 #endif