Home | History | Annotate | Line # | Download | only in internal 
      1 /*
      2  * Copyright 2023-2025 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  * All QUIC_PORT instances are created by a QUIC_ENGINE.
     40  */
     41 typedef struct quic_port_args_st {
     42     /* The engine which the QUIC port is to be a child of. */
     43     QUIC_ENGINE *engine;
     44 
     45     /*
     46      * This callback allows port_new_handshake_layer to pre-create a quic
     47      * connection object for the incoming channel
     48      * user_ssl_arg is expected to point to a quic listener object
     49      */
     50     SSL *(*get_conn_user_ssl)(QUIC_CHANNEL *ch, void *arg);
     51     void *user_ssl_arg;
     52 
     53     /*
     54      * This SSL_CTX will be used when constructing the handshake layer object
     55      * inside newly created channels.
     56      */
     57     SSL_CTX *channel_ctx;
     58 
     59     /*
     60      * If 1, this port is to be used for multiple connections, so
     61      * non-zero-length CIDs should be used. If 0, this port will only be used
     62      * for a single connection, so a zero-length local CID can be used.
     63      */
     64     int is_multi_conn;
     65 
     66     /*
     67      * if 1, this port should do server address validation
     68      */
     69     int do_addr_validation;
     70 } QUIC_PORT_ARGS;
     71 
     72 /* Only QUIC_ENGINE should use this function. */
     73 QUIC_PORT *ossl_quic_port_new(const QUIC_PORT_ARGS *args);
     74 
     75 void ossl_quic_port_free(QUIC_PORT *port);
     76 
     77 /*
     78  * Operations
     79  * ==========
     80  */
     81 
     82 /* Create an outgoing channel using this port. */
     83 QUIC_CHANNEL *ossl_quic_port_create_outgoing(QUIC_PORT *port, SSL *tls);
     84 
     85 /*
     86  * Create an incoming channel using this port.
     87  *
     88  * TODO(QUIC FUTURE): temporary TSERVER use only - will be removed.
     89  */
     90 QUIC_CHANNEL *ossl_quic_port_create_incoming(QUIC_PORT *port, SSL *tls);
     91 
     92 /*
     93  * Pop an incoming channel from the incoming channel queue. Returns NULL if
     94  * there are no pending incoming channels.
     95  */
     96 QUIC_CHANNEL *ossl_quic_port_pop_incoming(QUIC_PORT *port);
     97 
     98 /* Returns 1 if there is at least one connection incoming. */
     99 int ossl_quic_port_have_incoming(QUIC_PORT *port);
    100 
    101 /*
    102  * Delete any channels which are pending acceptance.
    103  */
    104 void ossl_quic_port_drop_incoming(QUIC_PORT *port);
    105 
    106 /*
    107  * Queries and Accessors
    108  * =====================
    109  */
    110 
    111 /* Gets/sets the underlying network read and write BIO. */
    112 BIO *ossl_quic_port_get_net_rbio(QUIC_PORT *port);
    113 BIO *ossl_quic_port_get_net_wbio(QUIC_PORT *port);
    114 int ossl_quic_port_set_net_rbio(QUIC_PORT *port, BIO *net_rbio);
    115 int ossl_quic_port_set_net_wbio(QUIC_PORT *port, BIO *net_wbio);
    116 SSL_CTX *ossl_quic_port_get_channel_ctx(QUIC_PORT *port);
    117 
    118 /*
    119  * Re-poll the network BIOs already set to determine if their support for
    120  * polling has changed. If force is 0, only check again if the BIOs have been
    121  * changed.
    122  */
    123 int ossl_quic_port_update_poll_descriptors(QUIC_PORT *port, int force);
    124 
    125 /* Gets the engine which this port is a child of. */
    126 QUIC_ENGINE *ossl_quic_port_get0_engine(QUIC_PORT *port);
    127 
    128 /* Gets the reactor which can be used to tick/poll on the port. */
    129 QUIC_REACTOR *ossl_quic_port_get0_reactor(QUIC_PORT *port);
    130 
    131 /* Gets the demuxer belonging to the port. */
    132 QUIC_DEMUX *ossl_quic_port_get0_demux(QUIC_PORT *port);
    133 
    134 /* Gets the mutex used by the port. */
    135 CRYPTO_MUTEX *ossl_quic_port_get0_mutex(QUIC_PORT *port);
    136 
    137 /* Gets the current time. */
    138 OSSL_TIME ossl_quic_port_get_time(QUIC_PORT *port);
    139 
    140 int ossl_quic_port_get_rx_short_dcid_len(const QUIC_PORT *port);
    141 int ossl_quic_port_get_tx_init_dcid_len(const QUIC_PORT *port);
    142 
    143 /* Returns 1 if the port is running/healthy, 0 if it has failed. */
    144 int ossl_quic_port_is_running(const QUIC_PORT *port);
    145 
    146 /*
    147  * Restores port-level error to the error stack. To be called only if
    148  * the port is no longer running.
    149  */
    150 void ossl_quic_port_restore_err_state(const QUIC_PORT *port);
    151 
    152 /* For use by QUIC_ENGINE. You should not need to call this directly. */
    153 void ossl_quic_port_subtick(QUIC_PORT *port, QUIC_TICK_RESULT *r,
    154     uint32_t flags);
    155 
    156 /* Returns the number of queued incoming channels. */
    157 size_t ossl_quic_port_get_num_incoming_channels(const QUIC_PORT *port);
    158 
    159 /* Sets if incoming connections should currently be allowed. */
    160 void ossl_quic_port_set_allow_incoming(QUIC_PORT *port, int allow_incoming);
    161 
    162 /* Returns 1 if we are using addressed mode on the read side. */
    163 int ossl_quic_port_is_addressed_r(const QUIC_PORT *port);
    164 
    165 /* Returns 1 if we are using addressed mode on the write side. */
    166 int ossl_quic_port_is_addressed_w(const QUIC_PORT *port);
    167 
    168 /* Returns 1 if we are using addressed mode. */
    169 int ossl_quic_port_is_addressed(const QUIC_PORT *port);
    170 
    171 /*
    172  * Returns the current network BIO epoch. This increments whenever the network
    173  * BIO configuration changes.
    174  */
    175 uint64_t ossl_quic_port_get_net_bio_epoch(const QUIC_PORT *port);
    176 
    177 /*
    178  * Events
    179  * ======
    180  */
    181 
    182 /*
    183  * Called if a permanent network error occurs. Terminates all channels
    184  * immediately. triggering_ch is an optional argument designating
    185  * a channel which encountered the network error.
    186  */
    187 void ossl_quic_port_raise_net_error(QUIC_PORT *port,
    188     QUIC_CHANNEL *triggering_ch);
    189 
    190 #endif
    191 
    192 #endif
    193