1 /* 2 * Copyright 2022-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 10 #ifndef OSSL_QUIC_TSERVER_H 11 # define OSSL_QUIC_TSERVER_H 12 13 # include <openssl/ssl.h> 14 # include <openssl/bio.h> 15 # include "internal/quic_stream.h" 16 # include "internal/quic_channel.h" 17 # include "internal/statem.h" 18 # include "internal/time.h" 19 20 # ifndef OPENSSL_NO_QUIC 21 22 /* 23 * QUIC Test Server Module 24 * ======================= 25 * 26 * This implements a QUIC test server. Since full QUIC server support is not yet 27 * implemented this server is limited in features and scope. It exists to 28 * provide a target for our QUIC client to talk to for testing purposes. 29 * 30 * A given QUIC test server instance supports only one client at a time. 31 * 32 * Note that this test server is not suitable for production use because it does 33 * not implement address verification, anti-amplification or retry logic. 34 */ 35 typedef struct quic_tserver_st QUIC_TSERVER; 36 37 typedef struct quic_tserver_args_st { 38 OSSL_LIB_CTX *libctx; 39 const char *propq; 40 SSL_CTX *ctx; 41 BIO *net_rbio, *net_wbio; 42 OSSL_TIME (*now_cb)(void *arg); 43 void *now_cb_arg; 44 const unsigned char *alpn; 45 size_t alpnlen; 46 } QUIC_TSERVER_ARGS; 47 48 QUIC_TSERVER *ossl_quic_tserver_new(const QUIC_TSERVER_ARGS *args, 49 const char *certfile, const char *keyfile); 50 51 void ossl_quic_tserver_free(QUIC_TSERVER *srv); 52 53 /* Set mutator callbacks for test framework support */ 54 int ossl_quic_tserver_set_plain_packet_mutator(QUIC_TSERVER *srv, 55 ossl_mutate_packet_cb mutatecb, 56 ossl_finish_mutate_cb finishmutatecb, 57 void *mutatearg); 58 59 int ossl_quic_tserver_set_handshake_mutator(QUIC_TSERVER *srv, 60 ossl_statem_mutate_handshake_cb mutate_handshake_cb, 61 ossl_statem_finish_mutate_handshake_cb finish_mutate_handshake_cb, 62 void *mutatearg); 63 64 /* Advances the state machine. */ 65 int ossl_quic_tserver_tick(QUIC_TSERVER *srv); 66 67 /* Returns 1 if we have a (non-terminated) client. */ 68 int ossl_quic_tserver_is_connected(QUIC_TSERVER *srv); 69 70 /* 71 * Returns 1 if we have finished the TLS handshake 72 */ 73 int ossl_quic_tserver_is_handshake_confirmed(const QUIC_TSERVER *srv); 74 75 /* Returns 1 if the server is in any terminating or terminated state */ 76 int ossl_quic_tserver_is_term_any(const QUIC_TSERVER *srv); 77 78 const QUIC_TERMINATE_CAUSE * 79 ossl_quic_tserver_get_terminate_cause(const QUIC_TSERVER *srv); 80 81 /* Returns 1 if the server is in a terminated state */ 82 int ossl_quic_tserver_is_terminated(const QUIC_TSERVER *srv); 83 84 /* Get out short header conn id length */ 85 size_t ossl_quic_tserver_get_short_header_conn_id_len(const QUIC_TSERVER *srv); 86 87 /* 88 * Attempts to read from stream 0. Writes the number of bytes read to 89 * *bytes_read and returns 1 on success. If no bytes are available, 0 is written 90 * to *bytes_read and 1 is returned (this is considered a success case). 91 * 92 * Returns 0 if connection is not currently active. If the receive part of 93 * the stream has reached the end of stream condition, returns 0; call 94 * ossl_quic_tserver_has_read_ended() to identify this condition. 95 */ 96 int ossl_quic_tserver_read(QUIC_TSERVER *srv, 97 uint64_t stream_id, 98 unsigned char *buf, 99 size_t buf_len, 100 size_t *bytes_read); 101 102 /* 103 * Returns 1 if the read part of the stream has ended normally. 104 */ 105 int ossl_quic_tserver_has_read_ended(QUIC_TSERVER *srv, uint64_t stream_id); 106 107 /* 108 * Attempts to write to the given stream. Writes the number of bytes consumed to 109 * *bytes_written and returns 1 on success. If there is no space currently 110 * available to write any bytes, 0 is written to *consumed and 1 is returned 111 * (this is considered a success case). 112 * 113 * Note that unlike libssl public APIs, this API always works in a 'partial 114 * write' mode. 115 * 116 * Returns 0 if connection is not currently active. 117 */ 118 int ossl_quic_tserver_write(QUIC_TSERVER *srv, 119 uint64_t stream_id, 120 const unsigned char *buf, 121 size_t buf_len, 122 size_t *bytes_written); 123 124 /* 125 * Signals normal end of the stream. 126 */ 127 int ossl_quic_tserver_conclude(QUIC_TSERVER *srv, uint64_t stream_id); 128 129 /* 130 * Create a server-initiated stream. The stream ID of the newly 131 * created stream is written to *stream_id. 132 */ 133 int ossl_quic_tserver_stream_new(QUIC_TSERVER *srv, 134 int is_uni, 135 uint64_t *stream_id); 136 137 BIO *ossl_quic_tserver_get0_rbio(QUIC_TSERVER *srv); 138 139 SSL_CTX *ossl_quic_tserver_get0_ssl_ctx(QUIC_TSERVER *srv); 140 141 /* 142 * Returns 1 if the peer has sent a STOP_SENDING frame for a stream. 143 * app_error_code is written if this returns 1. 144 */ 145 int ossl_quic_tserver_stream_has_peer_stop_sending(QUIC_TSERVER *srv, 146 uint64_t stream_id, 147 uint64_t *app_error_code); 148 149 /* 150 * Returns 1 if the peer has sent a RESET_STREAM frame for a stream. 151 * app_error_code is written if this returns 1. 152 */ 153 int ossl_quic_tserver_stream_has_peer_reset_stream(QUIC_TSERVER *srv, 154 uint64_t stream_id, 155 uint64_t *app_error_code); 156 157 /* 158 * Replaces existing local connection ID in the underlying QUIC_CHANNEL. 159 */ 160 int ossl_quic_tserver_set_new_local_cid(QUIC_TSERVER *srv, 161 const QUIC_CONN_ID *conn_id); 162 163 /* 164 * Returns the stream ID of the next incoming stream, or UINT64_MAX if there 165 * currently is none. 166 */ 167 uint64_t ossl_quic_tserver_pop_incoming_stream(QUIC_TSERVER *srv); 168 169 /* 170 * Returns 1 if all data sent on the given stream_id has been acked by the peer. 171 */ 172 int ossl_quic_tserver_is_stream_totally_acked(QUIC_TSERVER *srv, 173 uint64_t stream_id); 174 175 /* Returns 1 if we are currently interested in reading data from the network */ 176 int ossl_quic_tserver_get_net_read_desired(QUIC_TSERVER *srv); 177 178 /* Returns 1 if we are currently interested in writing data to the network */ 179 int ossl_quic_tserver_get_net_write_desired(QUIC_TSERVER *srv); 180 181 /* Returns the next event deadline */ 182 OSSL_TIME ossl_quic_tserver_get_deadline(QUIC_TSERVER *srv); 183 184 /* 185 * Shutdown the QUIC connection. Returns 1 if the connection is terminated and 186 * 0 otherwise. 187 */ 188 int ossl_quic_tserver_shutdown(QUIC_TSERVER *srv, uint64_t app_error_code); 189 190 /* Force generation of an ACK-eliciting packet. */ 191 int ossl_quic_tserver_ping(QUIC_TSERVER *srv); 192 193 /* Set tracing callback on channel. */ 194 void ossl_quic_tserver_set_msg_callback(QUIC_TSERVER *srv, 195 void (*f)(int write_p, int version, 196 int content_type, 197 const void *buf, size_t len, 198 SSL *ssl, void *arg), 199 void *arg); 200 201 /* 202 * This is similar to ossl_quic_conn_get_channel; it should be used for test 203 * instrumentation only and not to bypass QUIC_TSERVER for 'normal' operations. 204 */ 205 QUIC_CHANNEL *ossl_quic_tserver_get_channel(QUIC_TSERVER *srv); 206 207 /* Send a TLS new session ticket */ 208 int ossl_quic_tserver_new_ticket(QUIC_TSERVER *srv); 209 210 /* 211 * Set the max_early_data value to be sent in NewSessionTickets. Only the 212 * values 0 and 0xffffffff are valid for use in QUIC. 213 */ 214 int ossl_quic_tserver_set_max_early_data(QUIC_TSERVER *srv, 215 uint32_t max_early_data); 216 217 /* Set the find session callback for getting a server PSK */ 218 void ossl_quic_tserver_set_psk_find_session_cb(QUIC_TSERVER *srv, 219 SSL_psk_find_session_cb_func cb); 220 221 # endif 222 223 #endif 224