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