| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "OPENSSL-QUIC 7SSL" |
| 58 |
.TH OPENSSL-QUIC 7SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
openssl\-quic \- OpenSSL QUIC |
| 65 |
.SH DESCRIPTION |
| 66 |
.IX Header "DESCRIPTION" |
| 67 |
OpenSSL 3.2 and later features support for the QUIC transport protocol. |
| 68 |
You can use OpenSSL's QUIC capabilities for both client and server applications. |
| 69 |
This man page describes how to let applications use the QUIC protocol using the |
| 70 |
libssl API. |
| 71 |
.PP |
| 72 |
The QUIC protocol maps to the standard SSL API. A QUIC connection is represented |
| 73 |
by an SSL object in the same way that a TLS connection is. Only minimal changes |
| 74 |
are needed to existing applications which use libssl API to bring QUIC protocol |
| 75 |
support in. QUIC clients can use \fBOSSL_QUIC_client_method\fR\|(3) or |
| 76 |
\&\fBOSSL_QUIC_client_thread_method\fR\|(3) with \fBSSL_CTX_new\fR\|(3). See below for more |
| 77 |
details about the difference between the two. For servers, there is only one |
| 78 |
option: SSL method \fBOSSL_QUIC_server_method\fR\|(3) with \fBSSL_CTX_new\fR\|(3). |
| 79 |
.PP |
| 80 |
The remainder of this man page discusses, in order: |
| 81 |
.IP \(bu 4 |
| 82 |
Default stream mode versus multi-stream mode for clients; |
| 83 |
.IP \(bu 4 |
| 84 |
The changes to existing libssl APIs which are driven by QUIC-related |
| 85 |
implementation requirements, which existing applications should bear in mind; |
| 86 |
.IP \(bu 4 |
| 87 |
Aspects which must be considered by existing applications when adopting QUIC, |
| 88 |
including potential changes which may be needed. |
| 89 |
.IP \(bu 4 |
| 90 |
Recommended usage approaches for new applications. |
| 91 |
.IP \(bu 4 |
| 92 |
New, QUIC-specific APIs. |
| 93 |
.SH "CLIENT MODES OF OPERATION" |
| 94 |
.IX Header "CLIENT MODES OF OPERATION" |
| 95 |
When a client creates a QUIC connection, by default, it operates in default |
| 96 |
stream mode, which is intended to provide compatibility with existing non-QUIC |
| 97 |
application usage patterns. In this mode, the connection has a single stream |
| 98 |
associated with it. Calls to \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) on the QUIC |
| 99 |
connection SSL object read and write from that stream. Whether the stream is |
| 100 |
client-initiated or server-initiated from a QUIC perspective depends on whether |
| 101 |
\&\fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called first. |
| 102 |
.PP |
| 103 |
Default stream mode is primarily for compatibility with existing applications. |
| 104 |
For new applications utilizing QUIC, it's recommended to disable this mode and |
| 105 |
instead adopt the multi-stream API. See the RECOMMENDATIONS FOR NEW APPLICATIONS |
| 106 |
section for more details. |
| 107 |
.SS "Default Stream Mode" |
| 108 |
.IX Subsection "Default Stream Mode" |
| 109 |
A QUIC client connection can be used in either default stream mode or |
| 110 |
multi-stream mode. By default, a newly created QUIC connection SSL object uses |
| 111 |
default stream mode. |
| 112 |
.PP |
| 113 |
In default stream mode, a stream is implicitly created and bound to the QUIC |
| 114 |
connection SSL object; \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls to the QUIC |
| 115 |
connection SSL object work by default and are mapped to that stream. |
| 116 |
.PP |
| 117 |
When default stream mode is used, any API function which can be called on a QUIC |
| 118 |
stream SSL object can also be called on a QUIC connection SSL object, in which |
| 119 |
case it affects the default stream bound to the connection. |
| 120 |
.PP |
| 121 |
The identity of a QUIC stream, including its stream ID, varies depending on |
| 122 |
whether a stream is client-initiated or server-initiated. In default stream |
| 123 |
mode, if a client application calls \fBSSL_read\fR\|(3) first before any call to |
| 124 |
\&\fBSSL_write\fR\|(3) on the connection, it is assumed that the application protocol |
| 125 |
is using a server-initiated stream, and the \fBSSL_read\fR\|(3) call will not |
| 126 |
complete (either blocking, or failing appropriately if nonblocking mode is |
| 127 |
configured) until the server initiates a stream. Conversely, if the client |
| 128 |
application calls \fBSSL_write\fR\|(3) before any call to \fBSSL_read\fR\|(3) on the |
| 129 |
connection, it is assumed that a client-initiated stream is to be used |
| 130 |
and such a stream is created automatically. |
| 131 |
.PP |
| 132 |
Default stream mode is intended to aid compatibility with legacy applications. |
| 133 |
New applications adopting QUIC should use multi-stream mode, described below, |
| 134 |
and avoid use of the default stream functionality. |
| 135 |
.PP |
| 136 |
It is possible to use additional streams in default stream mode using |
| 137 |
\&\fBSSL_new_stream\fR\|(3) and \fBSSL_accept_stream\fR\|(3); note that the default incoming |
| 138 |
stream policy will need to be changed using \fBSSL_set_incoming_stream_policy\fR\|(3) |
| 139 |
in order to use \fBSSL_accept_stream\fR\|(3) in this case. However, applications |
| 140 |
using additional streams are strongly recommended to use multi-stream mode |
| 141 |
instead. |
| 142 |
.PP |
| 143 |
Calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) before a default stream |
| 144 |
has been associated with the QUIC connection SSL object will inhibit future |
| 145 |
creation of a default stream. |
| 146 |
.SS "Multi-Stream Mode" |
| 147 |
.IX Subsection "Multi-Stream Mode" |
| 148 |
The recommended usage mode for new applications adopting QUIC is multi-stream |
| 149 |
mode, in which no default stream is attached to the QUIC connection SSL object |
| 150 |
and attempts to call \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) on the QUIC connection |
| 151 |
SSL object fail. Instead, an application calls \fBSSL_new_stream\fR\|(3) or |
| 152 |
\&\fBSSL_accept_stream\fR\|(3) to create individual stream SSL objects for sending and |
| 153 |
receiving application data using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3). |
| 154 |
.PP |
| 155 |
To use multi-stream mode, call \fBSSL_set_default_stream_mode\fR\|(3) with an |
| 156 |
argument of \fBSSL_DEFAULT_STREAM_MODE_NONE\fR; this function must be called prior |
| 157 |
to initiating the connection. The default stream mode cannot be changed after |
| 158 |
initiating a connection. |
| 159 |
.PP |
| 160 |
When multi-stream mode is used, meaning that no default stream is associated |
| 161 |
with the connection, calls to API functions which are defined as operating on a |
| 162 |
QUIC stream fail if called on the QUIC connection SSL object. For example, calls |
| 163 |
such as \fBSSL_write\fR\|(3) or \fBSSL_get_stream_id\fR\|(3) will fail. |
| 164 |
.SH "CHANGES TO EXISTING APIS" |
| 165 |
.IX Header "CHANGES TO EXISTING APIS" |
| 166 |
Most SSL APIs, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), function as they do |
| 167 |
for TLS connections and do not have changed semantics, with some exceptions. The |
| 168 |
changes to the semantics of existing APIs are as follows: |
| 169 |
.IP \(bu 4 |
| 170 |
Since QUIC uses UDP, \fBSSL_set_bio\fR\|(3), \fBSSL_set0_rbio\fR\|(3) and |
| 171 |
\&\fBSSL_set0_wbio\fR\|(3) function as before, but must now receive a BIO with datagram |
| 172 |
semantics. There are broadly four options for applications to use as a network |
| 173 |
BIO: |
| 174 |
.RS 4 |
| 175 |
.IP \(bu 4 |
| 176 |
\&\fBBIO_s_datagram\fR\|(3), recommended for most applications, replaces |
| 177 |
\&\fBBIO_s_socket\fR\|(3) and provides a UDP socket. |
| 178 |
.IP \(bu 4 |
| 179 |
\&\fBBIO_s_dgram_pair\fR\|(3) provides BIO pair-like functionality but with datagram |
| 180 |
semantics, and is recommended for existing applications which use a BIO pair or |
| 181 |
memory BIO to manage libssl's communication with the network. |
| 182 |
.IP \(bu 4 |
| 183 |
\&\fBBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO-like interface but with |
| 184 |
datagram semantics. Unlike \fBBIO_s_dgram_pair\fR\|(3), it is unidirectional. |
| 185 |
.IP \(bu 4 |
| 186 |
An application may also choose to implement a custom BIO. The new |
| 187 |
\&\fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) APIs must be supported. |
| 188 |
.RE |
| 189 |
.RS 4 |
| 190 |
.RE |
| 191 |
.IP \(bu 4 |
| 192 |
\&\fBSSL_set_fd\fR\|(3), \fBSSL_set_rfd\fR\|(3) and \fBSSL_set_wfd\fR\|(3) traditionally |
| 193 |
instantiate a \fBBIO_s_socket\fR\|(3). For QUIC, these functions instead instantiate |
| 194 |
a \fBBIO_s_datagram\fR\|(3). This is equivalent to instantiating a |
| 195 |
\&\fBBIO_s_datagram\fR\|(3) and using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). |
| 196 |
.IP \(bu 4 |
| 197 |
Traditionally, whether the application-level I/O APIs (such as \fBSSL_read\fR\|(3) |
| 198 |
and \fBSSL_write\fR\|(3) operated in a blocking fashion was directly correlated with |
| 199 |
whether the underlying network socket was configured in a blocking fashion. This |
| 200 |
is no longer the case; applications must explicitly configure the desired |
| 201 |
application-level blocking mode using \fBSSL_set_blocking_mode\fR\|(3). See |
| 202 |
\&\fBSSL_set_blocking_mode\fR\|(3) for details. |
| 203 |
.IP \(bu 4 |
| 204 |
Network-level I/O must always be performed in a nonblocking manner. The |
| 205 |
application can still enjoy blocking semantics for calls to application-level |
| 206 |
I/O functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), but the underlying |
| 207 |
network BIO provided to QUIC (such as a \fBBIO_s_datagram\fR\|(3)) must be configured |
| 208 |
in nonblocking mode. For application-level blocking functionality, see |
| 209 |
\&\fBSSL_set_blocking_mode\fR\|(3). |
| 210 |
.IP \(bu 4 |
| 211 |
\&\fBBIO_new_ssl_connect\fR\|(3) has been changed to automatically use a |
| 212 |
\&\fBBIO_s_datagram\fR\|(3) when used with QUIC, therefore applications which use this |
| 213 |
do not need to change the BIO they use. |
| 214 |
.IP \(bu 4 |
| 215 |
\&\fBBIO_new_buffer_ssl_connect\fR\|(3) cannot be used with QUIC and applications must |
| 216 |
change to use \fBBIO_new_ssl_connect\fR\|(3) instead. |
| 217 |
.IP \(bu 4 |
| 218 |
\&\fBSSL_shutdown\fR\|(3) has significant changes in relation to how QUIC connections |
| 219 |
must be shut down. In particular, applications should be advised that the full |
| 220 |
RFC-conformant QUIC shutdown process may take an extended amount of time. This |
| 221 |
may not be suitable for short-lived processes which should exit immediately |
| 222 |
after their usage of a QUIC connection is completed. A rapid shutdown mode |
| 223 |
is available for such applications. For details, see \fBSSL_shutdown\fR\|(3). |
| 224 |
.IP \(bu 4 |
| 225 |
\&\fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and \fBSSL_want_write\fR\|(3) no longer reflect |
| 226 |
the I/O state of the network BIO passed to the QUIC SSL object, but instead |
| 227 |
reflect the flow control state of the QUIC stream associated with the SSL |
| 228 |
object. |
| 229 |
.Sp |
| 230 |
When used in nonblocking mode, \fBSSL_ERROR_WANT_READ\fR indicates that the |
| 231 |
receive part of a QUIC stream does not currently have any more data available to |
| 232 |
be read, and \fBSSL_ERROR_WANT_WRITE\fR indicates that the stream's internal buffer |
| 233 |
is full. |
| 234 |
.Sp |
| 235 |
To determine if the QUIC implementation currently wishes to be informed of |
| 236 |
incoming network datagrams, use the new function \fBSSL_net_read_desired\fR\|(3); |
| 237 |
likewise, to determine if the QUIC implementation currently wishes to be |
| 238 |
informed when it is possible to transmit network datagrams, use the new function |
| 239 |
\&\fBSSL_net_write_desired\fR\|(3). Only applications which wish to manage their own event |
| 240 |
loops need to use these functions; see \fBAPPLICATION-DRIVEN EVENT LOOPS\fR for |
| 241 |
further discussion. |
| 242 |
.IP \(bu 4 |
| 243 |
The use of ALPN is mandatory when using QUIC. Attempts to connect without |
| 244 |
configuring ALPN will fail. For information on how to configure ALPN, see |
| 245 |
\&\fBSSL_set_alpn_protos\fR\|(3). |
| 246 |
.IP \(bu 4 |
| 247 |
Whether QUIC operates in a client or server mode is determined by the |
| 248 |
\&\fBSSL_METHOD\fR used, rather than by calls to \fBSSL_set_connect_state\fR\|(3) or |
| 249 |
\&\fBSSL_set_accept_state\fR\|(3). It is not necessary to call either of |
| 250 |
\&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state\fR\|(3) before connecting, but |
| 251 |
if either of these are called, the function called must be congruent with the |
| 252 |
\&\fBSSL_METHOD\fR being used. |
| 253 |
.IP \(bu 4 |
| 254 |
The \fBSSL_set_min_proto_version\fR\|(3) and \fBSSL_set_max_proto_version\fR\|(3) APIs are |
| 255 |
not used and the values passed to them are ignored, as OpenSSL QUIC currently |
| 256 |
always uses TLS 1.3. |
| 257 |
.IP \(bu 4 |
| 258 |
The following libssl functionality is not available when used with QUIC. |
| 259 |
.RS 4 |
| 260 |
.IP \(bu 4 |
| 261 |
Async functionality |
| 262 |
.IP \(bu 4 |
| 263 |
\&\fBSSL_MODE_AUTO_RETRY\fR |
| 264 |
.IP \(bu 4 |
| 265 |
Record Padding and Fragmentation (\fBSSL_set_block_padding\fR\|(3), etc.) |
| 266 |
.IP \(bu 4 |
| 267 |
\&\fBSSL_stateless\fR\|(3) support |
| 268 |
.IP \(bu 4 |
| 269 |
SRTP functionality |
| 270 |
.IP \(bu 4 |
| 271 |
TLSv1.3 Early Data |
| 272 |
.IP \(bu 4 |
| 273 |
TLS Next Protocol Negotiation cannot be used and is superseded by ALPN, which |
| 274 |
must be used instead. The use of ALPN is mandatory with QUIC. |
| 275 |
.IP \(bu 4 |
| 276 |
Post-Handshake Client Authentication is not available as QUIC prohibits its use. |
| 277 |
.IP \(bu 4 |
| 278 |
QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant |
| 279 |
to older TLS versions is not available. |
| 280 |
.IP \(bu 4 |
| 281 |
Some cipher suites which are generally available for TLSv1.3 are not available |
| 282 |
for QUIC, such as \fBTLS_AES_128_CCM_8_SHA256\fR. Your application may need to |
| 283 |
adjust the list of acceptable cipher suites it passes to libssl. |
| 284 |
.IP \(bu 4 |
| 285 |
CCM mode is not currently supported. |
| 286 |
.RE |
| 287 |
.RS 4 |
| 288 |
.Sp |
| 289 |
The following libssl functionality is also not available when used with QUIC, |
| 290 |
but calls to the relevant functions are treated as no-ops: |
| 291 |
.IP \(bu 4 |
| 292 |
Readahead (\fBSSL_set_read_ahead\fR\|(3), etc.) |
| 293 |
.RE |
| 294 |
.RS 4 |
| 295 |
.RE |
| 296 |
.SH "CONSIDERATIONS FOR EXISTING APPLICATIONS" |
| 297 |
.IX Header "CONSIDERATIONS FOR EXISTING APPLICATIONS" |
| 298 |
Existing applications seeking to adopt QUIC should apply the following list to |
| 299 |
determine what changes they will need to make: |
| 300 |
.IP \(bu 4 |
| 301 |
A client application wishing to use QUIC must use \fBOSSL_QUIC_client_method\fR\|(3) |
| 302 |
or \fBOSSL_QUIC_client_thread_method\fR\|(3) as its SSL method. For more information |
| 303 |
on the differences between these two methods, see |
| 304 |
\&\fBTHREAD ASSISTED MODE\fR. |
| 305 |
.IP \(bu 4 |
| 306 |
A server application wishing to use QUIC must use \fBOSSL_QUIC_server_method\fR\|(3). |
| 307 |
The server can then accept new connections with \fBSSL_accept_connection\fR\|(3). |
| 308 |
.IP \(bu 4 |
| 309 |
Determine how to provide QUIC with network access. Determine which of the below |
| 310 |
apply for your application: |
| 311 |
.RS 4 |
| 312 |
.IP \(bu 4 |
| 313 |
Your application uses \fBBIO_s_socket\fR\|(3) to construct a BIO which is passed to |
| 314 |
the SSL object to provide it with network access. |
| 315 |
.Sp |
| 316 |
Changes needed: Change your application to use \fBBIO_s_datagram\fR\|(3) instead when |
| 317 |
using QUIC. The socket must be configured in nonblocking mode. You may or may |
| 318 |
not need to use \fBSSL_set1_initial_peer_addr\fR\|(3) to set the initial peer |
| 319 |
address; see the \fBQUIC-SPECIFIC APIS\fR section for details. |
| 320 |
.IP \(bu 4 |
| 321 |
Your application uses \fBBIO_new_ssl_connect\fR\|(3) to |
| 322 |
construct a BIO which is passed to the SSL object to provide it with network |
| 323 |
access. |
| 324 |
.Sp |
| 325 |
Changes needed: No changes needed. Use of QUIC is detected automatically and a |
| 326 |
datagram socket is created instead of a normal TCP socket. |
| 327 |
.IP \(bu 4 |
| 328 |
Your application uses any other I/O strategy in this list but combines it with a |
| 329 |
\&\fBBIO_f_buffer\fR\|(3), for example using \fBBIO_push\fR\|(3). |
| 330 |
.Sp |
| 331 |
Changes needed: Disable the usage of \fBBIO_f_buffer\fR\|(3) when using QUIC. Usage |
| 332 |
of such a buffer is incompatible with QUIC as QUIC requires datagram semantics |
| 333 |
in its interaction with the network. |
| 334 |
.IP \(bu 4 |
| 335 |
Your application uses a BIO pair to cause the SSL object to read and write |
| 336 |
network traffic to a memory buffer. Your application manages the transmission |
| 337 |
and reception of buffered data itself in a way unknown to libssl. |
| 338 |
.Sp |
| 339 |
Changes needed: Switch from using a conventional BIO pair to using |
| 340 |
\&\fBBIO_s_dgram_pair\fR\|(3) instead, which has the necessary datagram semantics. You |
| 341 |
will need to modify your application to transmit and receive using a UDP socket |
| 342 |
and to use datagram semantics when interacting with the \fBBIO_s_dgram_pair\fR\|(3) |
| 343 |
instance. |
| 344 |
.IP \(bu 4 |
| 345 |
Your application uses a custom BIO method to provide the SSL object with network |
| 346 |
access. |
| 347 |
.Sp |
| 348 |
Changes needed: The custom BIO must be re-architected to have datagram |
| 349 |
semantics. \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) must be implemented. These |
| 350 |
calls must operate in a nonblocking fashion. Optionally, implement the |
| 351 |
\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3) methods if |
| 352 |
desired. Implementing these methods is required if blocking semantics at the SSL |
| 353 |
API level are desired. |
| 354 |
.RE |
| 355 |
.RS 4 |
| 356 |
.RE |
| 357 |
.IP \(bu 4 |
| 358 |
An application must explicitly configure whether it wishes to use the SSL APIs |
| 359 |
in blocking mode or not. Traditionally, an SSL object has automatically operated |
| 360 |
in blocking or nonblocking mode based on whether the underlying network BIO |
| 361 |
operates in blocking or nonblocking mode. QUIC requires the use of a |
| 362 |
nonblocking network BIO, therefore the blocking mode at the application level |
| 363 |
can be explicitly configured by the application using the new |
| 364 |
\&\fBSSL_set_blocking_mode\fR\|(3) API. The default mode is blocking. If an application |
| 365 |
wishes to use the SSL object APIs at application level in a nonblocking manner, |
| 366 |
it must add a call to \fBSSL_set_blocking_mode\fR\|(3) to disable blocking mode. |
| 367 |
.IP \(bu 4 |
| 368 |
If your client application does not choose to use thread assisted mode, it must |
| 369 |
ensure that it calls an I/O function on the SSL object (for example, |
| 370 |
\&\fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3)), or the new function \fBSSL_handle_events\fR\|(3), |
| 371 |
regularly. If the SSL object is used in blocking mode, an ongoing blocking call |
| 372 |
to an I/O function satisfies this requirement. This is required to ensure that |
| 373 |
timer events required by QUIC are handled in a timely fashion. |
| 374 |
.Sp |
| 375 |
Most applications will service the SSL object by calling \fBSSL_read\fR\|(3) or |
| 376 |
\&\fBSSL_write\fR\|(3) regularly. If an application does not do this, it should ensure |
| 377 |
that \fBSSL_handle_events\fR\|(3) is called regularly. |
| 378 |
.Sp |
| 379 |
\&\fBSSL_get_event_timeout\fR\|(3) can be used to determine when |
| 380 |
\&\fBSSL_handle_events\fR\|(3) must next be called. |
| 381 |
.Sp |
| 382 |
If the SSL object is being used with an underlying network BIO which is pollable |
| 383 |
(such as \fBBIO_s_datagram\fR\|(3)), the application can use |
| 384 |
\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3) to obtain |
| 385 |
resources which can be used to determine when \fBSSL_handle_events\fR\|(3) should be |
| 386 |
called due to network I/O. |
| 387 |
.Sp |
| 388 |
Client applications which use thread assisted mode do not need to be concerned |
| 389 |
with this requirement, as the QUIC implementation ensures timeout events |
| 390 |
are handled in a timely manner. See \fBTHREAD ASSISTED MODE\fR for details. |
| 391 |
.IP \(bu 4 |
| 392 |
Ensure that your usage of \fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and |
| 393 |
\&\fBSSL_want_write\fR\|(3) reflects the API changes described in \fBCHANGES TO EXISTING |
| 394 |
APIS\fR. In particular, you should use these APIs to determine the ability of a |
| 395 |
QUIC stream to receive or provide application data, not to to determine if |
| 396 |
network I/O is required. |
| 397 |
.IP \(bu 4 |
| 398 |
Evaluate your application's use of \fBSSL_shutdown\fR\|(3) in light of the changes |
| 399 |
discussed in \fBCHANGES TO EXISTING APIS\fR. Depending on whether your application |
| 400 |
wishes to prioritise RFC conformance or rapid shutdown, consider using the new |
| 401 |
\&\fBSSL_shutdown_ex\fR\|(3) API instead. See \fBQUIC-SPECIFIC APIS\fR for details. |
| 402 |
.SH "RECOMMENDED USAGE IN NEW APPLICATIONS" |
| 403 |
.IX Header "RECOMMENDED USAGE IN NEW APPLICATIONS" |
| 404 |
The recommended usage in new applications varies depending on three independent |
| 405 |
design decisions: |
| 406 |
.IP \(bu 4 |
| 407 |
Whether the application will use blocking or nonblocking I/O at the application |
| 408 |
level (configured using \fBSSL_set_blocking_mode\fR\|(3)). |
| 409 |
.Sp |
| 410 |
If the application does nonblocking I/O at the application level it can choose |
| 411 |
to manage its own polling and event loop; see \fBAPPLICATION-DRIVEN EVENT LOOPS\fR. |
| 412 |
.IP \(bu 4 |
| 413 |
Whether the application intends to give the QUIC implementation direct access to |
| 414 |
a network socket (e.g. via \fBBIO_s_datagram\fR\|(3)) or whether it intends to buffer |
| 415 |
transmitted and received datagrams via a \fBBIO_s_dgram_pair\fR\|(3) or custom BIO. |
| 416 |
.Sp |
| 417 |
The former is preferred where possible as it reduces latency to the network, |
| 418 |
which enables QUIC to achieve higher performance and more accurate connection |
| 419 |
round trip time (RTT) estimation. |
| 420 |
.IP \(bu 4 |
| 421 |
Whether thread assisted mode will be used (see \fBTHREAD ASSISTED MODE\fR). |
| 422 |
.PP |
| 423 |
Simple demos for QUIC usage under these various scenarios can be found at |
| 424 |
<https://github.com/openssl/openssl/tree/master/doc/designs/ddd>. |
| 425 |
.PP |
| 426 |
Applications which wish to implement QUIC-specific protocols should be aware of |
| 427 |
the APIs listed under \fBQUIC-SPECIFIC APIS\fR which provide access to |
| 428 |
QUIC-specific functionality. For example, \fBSSL_stream_conclude\fR\|(3) can be used |
| 429 |
to indicate the end of the sending part of a stream, and \fBSSL_shutdown_ex\fR\|(3) |
| 430 |
can be used to provide a QUIC application error code when closing a connection. |
| 431 |
.PP |
| 432 |
Regardless of the design decisions chosen above, it is recommended that new |
| 433 |
applications avoid use of the default stream mode and use the multi-stream API |
| 434 |
by calling \fBSSL_set_default_stream_mode\fR\|(3); see the MODES OF OPERATION section |
| 435 |
for details. |
| 436 |
.SH "QUIC-SPECIFIC APIS" |
| 437 |
.IX Header "QUIC-SPECIFIC APIS" |
| 438 |
This section details new APIs which are directly or indirectly related to QUIC. |
| 439 |
For details on the operation of each API, see the referenced man pages. |
| 440 |
.PP |
| 441 |
The following SSL APIs are new but relevant to both QUIC and DTLS: |
| 442 |
.IP \fBSSL_get_event_timeout\fR\|(3) 4 |
| 443 |
.IX Item "SSL_get_event_timeout" |
| 444 |
Determines when the QUIC implementation should next be woken up via a call to |
| 445 |
\&\fBSSL_handle_events\fR\|(3) (or another I/O function such as \fBSSL_read\fR\|(3) or |
| 446 |
\&\fBSSL_write\fR\|(3)), if ever. |
| 447 |
.Sp |
| 448 |
This can also be used with DTLS and supersedes \fBDTLSv1_get_timeout\fR\|(3) for new |
| 449 |
usage. |
| 450 |
.IP \fBSSL_handle_events\fR\|(3) 4 |
| 451 |
.IX Item "SSL_handle_events" |
| 452 |
This is a non-specific I/O operation which makes a best effort attempt to |
| 453 |
perform any pending I/O or timeout processing. It can be used to advance the |
| 454 |
QUIC state machine by processing incoming network traffic, generating outgoing |
| 455 |
network traffic and handling any expired timeout events. Most other I/O |
| 456 |
functions on an SSL object, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), |
| 457 |
implicitly perform event handling on the SSL object, so calling this function is |
| 458 |
only needed if no other I/O function is to be called. |
| 459 |
.Sp |
| 460 |
This can also be used with DTLS and supersedes \fBDTLSv1_handle_timeout\fR\|(3) for |
| 461 |
new usage. |
| 462 |
.PP |
| 463 |
The following SSL APIs are specific to QUIC: |
| 464 |
.IP \fBSSL_new_listener\fR\|(3) 4 |
| 465 |
.IX Item "SSL_new_listener" |
| 466 |
Creates a listener SSL object, which differs from an ordinary SSL object in that |
| 467 |
it is used to provide an abstraction for the acceptance of network connections |
| 468 |
in a protocol-agnostic manner. |
| 469 |
.Sp |
| 470 |
Currently, listener SSL objects are only supported for QUIC server usage or |
| 471 |
client-only usage. The listener interface may expand to support additional |
| 472 |
protocols in the future. |
| 473 |
.IP \fBSSL_new_listener_from\fR\|(3) 4 |
| 474 |
.IX Item "SSL_new_listener_from" |
| 475 |
Creates a listener SSL object which is subordinate to a QUIC domain SSL object |
| 476 |
\&\fIssl\fR. See \fBSSL_new_domain\fR\|(3) and \fBopenssl\-quic\-concurrency\fR\|(7) for details |
| 477 |
on QUIC domain SSL objects. |
| 478 |
.IP \fBSSL_is_listener\fR\|(3) 4 |
| 479 |
.IX Item "SSL_is_listener" |
| 480 |
Returns 1 if and only if an SSL object is a listener SSL object. |
| 481 |
.IP \fBSSL_get0_listener\fR\|(3) 4 |
| 482 |
.IX Item "SSL_get0_listener" |
| 483 |
Returns an SSL object pointer (potentially to the same object on which it is |
| 484 |
called) or NULL. |
| 485 |
.IP \fBSSL_listen\fR\|(3) 4 |
| 486 |
.IX Item "SSL_listen" |
| 487 |
Begin listening after a listener has been created. It is ordinarily not needed |
| 488 |
to call this because it will be called automatically on the first call to |
| 489 |
\&\fBSSL_accept_connection\fR\|(3). |
| 490 |
.IP \fBSSL_accept_connection\fR\|(3) 4 |
| 491 |
.IX Item "SSL_accept_connection" |
| 492 |
Accepts a new incoming connection for a listener SSL object. A new SSL object |
| 493 |
representing the accepted connection is created and returned on success. If no |
| 494 |
incoming connection is available and the listener SSL object is configured in |
| 495 |
nonblocking mode, NULL is returned. |
| 496 |
.IP \fBSSL_get_accept_connection_queue_len\fR\|(3) 4 |
| 497 |
.IX Item "SSL_get_accept_connection_queue_len" |
| 498 |
Returns an informational value listing the number of connections waiting to be |
| 499 |
popped from the queue via calls to \fBSSL_accept_connection()\fR. |
| 500 |
.IP \fBSSL_new_from_listener\fR\|(3) 4 |
| 501 |
.IX Item "SSL_new_from_listener" |
| 502 |
Creates a client connection under a given listener SSL object. For QUIC, it is |
| 503 |
also possible to use \fBSSL_new_from_listener()\fR in conjunction with a listener |
| 504 |
which does accept incoming connections (i.e., which was not created using |
| 505 |
\&\fBSSL_LISTENER_FLAG_NO_ACCEPT\fR), leading to a UDP network endpoint which has |
| 506 |
both incoming and outgoing connections. |
| 507 |
.IP \fBSSL_new_domain\fR\|(3) 4 |
| 508 |
.IX Item "SSL_new_domain" |
| 509 |
Creates a new QUIC event domain, represented as an SSL object. This is known as |
| 510 |
a QUIC domain SSL object. The concept of a QUIC event domain is discussed in |
| 511 |
detail in \fBopenssl\-quic\-concurrency\fR\|(7). |
| 512 |
.IP \fBSSL_is_domain\fR\|(3) 4 |
| 513 |
.IX Item "SSL_is_domain" |
| 514 |
Returns 1 if an SSL object is a QUIC domain SSL object. |
| 515 |
.IP \fBSSL_get0_domain\fR\|(3) 4 |
| 516 |
.IX Item "SSL_get0_domain" |
| 517 |
\&\fBSSL_get0_domain()\fR obtains a pointer to the QUIC domain SSL object in an SSL |
| 518 |
object hierarchy (if any). |
| 519 |
.IP "\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_get_blocking_mode\fR\|(3)" 4 |
| 520 |
.IX Item "SSL_set_blocking_mode, SSL_get_blocking_mode" |
| 521 |
Configures whether blocking semantics are used at the application level. This |
| 522 |
determines whether calls to functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) |
| 523 |
will block. |
| 524 |
.IP "\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)" 4 |
| 525 |
.IX Item "SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor" |
| 526 |
These functions facilitate operation in nonblocking mode. |
| 527 |
.Sp |
| 528 |
When an SSL object is being used with an underlying network read BIO which |
| 529 |
supports polling, \fBSSL_get_rpoll_descriptor\fR\|(3) outputs an OS resource which |
| 530 |
can be used to synchronise on network readability events which should result in |
| 531 |
a call to \fBSSL_handle_events\fR\|(3). \fBSSL_get_wpoll_descriptor\fR\|(3) works in an |
| 532 |
analogous fashion for the underlying network write BIO. |
| 533 |
.Sp |
| 534 |
The poll descriptors provided by these functions should be used only when |
| 535 |
\&\fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) return 1, |
| 536 |
respectively. |
| 537 |
.IP "\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3)" 4 |
| 538 |
.IX Item "SSL_net_read_desired, SSL_net_write_desired" |
| 539 |
These functions facilitate operation in nonblocking mode and are used in |
| 540 |
conjunction with \fBSSL_get_rpoll_descriptor\fR\|(3) and |
| 541 |
\&\fBSSL_get_wpoll_descriptor\fR\|(3) respectively. They determine whether the |
| 542 |
respective poll descriptor is currently relevant for the purposes of polling. |
| 543 |
.IP \fBSSL_set1_initial_peer_addr\fR\|(3) 4 |
| 544 |
.IX Item "SSL_set1_initial_peer_addr" |
| 545 |
This function can be used to set the initial peer address for an outgoing QUIC |
| 546 |
connection. This function must be used in the general case when creating an |
| 547 |
outgoing QUIC connection; however, the correct initial peer address can be |
| 548 |
autodetected in some cases. See \fBSSL_set1_initial_peer_addr\fR\|(3) for details. |
| 549 |
.IP \fBSSL_shutdown_ex\fR\|(3) 4 |
| 550 |
.IX Item "SSL_shutdown_ex" |
| 551 |
This augments \fBSSL_shutdown\fR\|(3) by allowing an application error code to be |
| 552 |
specified. It also allows an application to decide how quickly it wants a |
| 553 |
shutdown to be performed, potentially by trading off strict RFC compliance. |
| 554 |
.IP \fBSSL_stream_conclude\fR\|(3) 4 |
| 555 |
.IX Item "SSL_stream_conclude" |
| 556 |
This allows an application to indicate the normal end of the sending part of a |
| 557 |
QUIC stream. This corresponds to the FIN flag in the QUIC RFC. The receiving |
| 558 |
part of a stream remains usable. |
| 559 |
.IP \fBSSL_stream_reset\fR\|(3) 4 |
| 560 |
.IX Item "SSL_stream_reset" |
| 561 |
This allows an application to indicate the non-normal termination of the sending |
| 562 |
part of a stream. This corresponds to the RESET_STREAM frame in the QUIC RFC. |
| 563 |
.IP "\fBSSL_get_stream_write_state\fR\|(3) and \fBSSL_get_stream_read_state\fR\|(3)" 4 |
| 564 |
.IX Item "SSL_get_stream_write_state and SSL_get_stream_read_state" |
| 565 |
This allows an application to determine the current stream states for the |
| 566 |
sending and receiving parts of a stream respectively. |
| 567 |
.IP "\fBSSL_get_stream_write_error_code\fR\|(3) and \fBSSL_get_stream_read_error_code\fR\|(3)" 4 |
| 568 |
.IX Item "SSL_get_stream_write_error_code and SSL_get_stream_read_error_code" |
| 569 |
This allows an application to determine the application error code which was |
| 570 |
signalled by a peer which has performed a non-normal stream termination of the |
| 571 |
respective sending or receiving part of a stream, if any. |
| 572 |
.IP \fBSSL_get_conn_close_info\fR\|(3) 4 |
| 573 |
.IX Item "SSL_get_conn_close_info" |
| 574 |
This allows an application to determine the error code which was signalled when |
| 575 |
the local or remote endpoint terminated the QUIC connection. |
| 576 |
.IP \fBSSL_get0_connection\fR\|(3) 4 |
| 577 |
.IX Item "SSL_get0_connection" |
| 578 |
Gets the QUIC connection SSL object from a QUIC stream SSL object. |
| 579 |
.IP \fBSSL_is_connection\fR\|(3) 4 |
| 580 |
.IX Item "SSL_is_connection" |
| 581 |
Returns 1 if an SSL object is not a QUIC stream SSL object. |
| 582 |
.IP \fBSSL_get_stream_type\fR\|(3) 4 |
| 583 |
.IX Item "SSL_get_stream_type" |
| 584 |
Provides information on the kind of QUIC stream which is attached |
| 585 |
to the SSL object. |
| 586 |
.IP \fBSSL_get_stream_id\fR\|(3) 4 |
| 587 |
.IX Item "SSL_get_stream_id" |
| 588 |
Returns the QUIC stream ID which the QUIC protocol has associated with a QUIC |
| 589 |
stream. |
| 590 |
.IP \fBSSL_new_stream\fR\|(3) 4 |
| 591 |
.IX Item "SSL_new_stream" |
| 592 |
Creates a new QUIC stream SSL object representing a new, locally-initiated QUIC |
| 593 |
stream. |
| 594 |
.IP \fBSSL_accept_stream\fR\|(3) 4 |
| 595 |
.IX Item "SSL_accept_stream" |
| 596 |
Potentially yields a new QUIC stream SSL object representing a new |
| 597 |
remotely-initiated QUIC stream, blocking until one is available if the |
| 598 |
connection is configured to do so. |
| 599 |
.IP \fBSSL_get_accept_stream_queue_len\fR\|(3) 4 |
| 600 |
.IX Item "SSL_get_accept_stream_queue_len" |
| 601 |
Provides information on the number of pending remotely-initiated streams. |
| 602 |
.IP \fBSSL_set_incoming_stream_policy\fR\|(3) 4 |
| 603 |
.IX Item "SSL_set_incoming_stream_policy" |
| 604 |
Configures how incoming, remotely-initiated streams are handled. The incoming |
| 605 |
stream policy can be used to automatically reject streams created by the peer, |
| 606 |
or allow them to be handled using \fBSSL_accept_stream\fR\|(3). |
| 607 |
.IP \fBSSL_set_default_stream_mode\fR\|(3) 4 |
| 608 |
.IX Item "SSL_set_default_stream_mode" |
| 609 |
Used to configure or disable default stream mode; see the MODES OF OPERATION |
| 610 |
section for details. |
| 611 |
.PP |
| 612 |
The following BIO APIs are not specific to QUIC but have been added to |
| 613 |
facilitate QUIC-specific requirements and are closely associated with its use: |
| 614 |
.IP \fBBIO_s_dgram_pair\fR\|(3) 4 |
| 615 |
.IX Item "BIO_s_dgram_pair" |
| 616 |
This is a new BIO method which is similar to a conventional BIO pair but |
| 617 |
provides datagram semantics. |
| 618 |
.IP "\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3)" 4 |
| 619 |
.IX Item "BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor" |
| 620 |
This is a new BIO API which allows a BIO to expose a poll descriptor. This API |
| 621 |
is used to implement the corresponding SSL APIs \fBSSL_get_rpoll_descriptor\fR\|(3) |
| 622 |
and \fBSSL_get_wpoll_descriptor\fR\|(3). |
| 623 |
.IP "\fBBIO_sendmmsg\fR\|(3), \fBBIO_recvmmsg\fR\|(3)" 4 |
| 624 |
.IX Item "BIO_sendmmsg, BIO_recvmmsg" |
| 625 |
This is a new BIO API which can be implemented by BIOs which implement datagram |
| 626 |
semantics. It is implemented by \fBBIO_s_datagram\fR\|(3) and \fBBIO_s_dgram_pair\fR\|(3). |
| 627 |
It is used by the QUIC implementation to send and receive UDP datagrams. |
| 628 |
.IP "\fBBIO_dgram_set_no_trunc\fR\|(3), \fBBIO_dgram_get_no_trunc\fR\|(3)" 4 |
| 629 |
.IX Item "BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc" |
| 630 |
By default, \fBBIO_s_dgram_pair\fR\|(3) has semantics comparable to those of Berkeley |
| 631 |
sockets being used with datagram semantics. This allows an alternative mode |
| 632 |
to be enabled in which datagrams will not be silently truncated if they are |
| 633 |
too large. |
| 634 |
.IP "\fBBIO_dgram_set_caps\fR\|(3), \fBBIO_dgram_get_caps\fR\|(3)" 4 |
| 635 |
.IX Item "BIO_dgram_set_caps, BIO_dgram_get_caps" |
| 636 |
These functions are used to allow the user of one end of a |
| 637 |
\&\fBBIO_s_dgram_pair\fR\|(3) to indicate its capabilities to the other end of a |
| 638 |
\&\fBBIO_s_dgram_pair\fR\|(3). In particular, this allows an application to inform the |
| 639 |
QUIC implementation of whether it is prepared to handle local and/or peer |
| 640 |
addresses in transmitted datagrams and to provide the applicable information in |
| 641 |
received datagrams. |
| 642 |
.IP "\fBBIO_dgram_get_local_addr_cap\fR\|(3), \fBBIO_dgram_set_local_addr_enable\fR\|(3), \fBBIO_dgram_get_local_addr_enable\fR\|(3)" 4 |
| 643 |
.IX Item "BIO_dgram_get_local_addr_cap, BIO_dgram_set_local_addr_enable, BIO_dgram_get_local_addr_enable" |
| 644 |
Local addressing support refers to the ability of a BIO with datagram semantics |
| 645 |
to allow a source address to be specified on transmission and to report the |
| 646 |
destination address on reception. These functions can be used to determine if a |
| 647 |
BIO can support local addressing and to enable local addressing support if it |
| 648 |
can. |
| 649 |
.IP \fBBIO_err_is_non_fatal\fR\|(3) 4 |
| 650 |
.IX Item "BIO_err_is_non_fatal" |
| 651 |
This is used to determine if an error while calling \fBBIO_sendmmsg\fR\|(3) or |
| 652 |
\&\fBBIO_recvmmsg\fR\|(3) is ephemeral in nature, such as "would block" errors. |
| 653 |
.SH "THREAD ASSISTED MODE" |
| 654 |
.IX Header "THREAD ASSISTED MODE" |
| 655 |
The optional thread assisted mode for clients can be used with |
| 656 |
\&\fBOSSL_QUIC_client_thread_method\fR\|(3). In this mode, a background thread is |
| 657 |
created automatically. The OpenSSL QUIC implementation then takes responsibility |
| 658 |
for ensuring that timeout events are handled on a timely basis even if no SSL |
| 659 |
I/O function such as \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called by the |
| 660 |
application for a long time. |
| 661 |
.PP |
| 662 |
All necessary locking is handled automatically internally, but the thread safety |
| 663 |
guarantees for the public SSL API are unchanged. Therefore, an application must |
| 664 |
still do its own locking if it wishes to make concurrent use of the public SSL |
| 665 |
APIs. |
| 666 |
.PP |
| 667 |
Because this method relies on threads, it is not available on platforms where |
| 668 |
threading support is not available or not supported by OpenSSL. However, it |
| 669 |
does provide the simplest mode of usage for an application. |
| 670 |
.PP |
| 671 |
The implementation may or may not use a common thread or thread pool to service |
| 672 |
multiple SSL objects in the same \fBSSL_CTX\fR. |
| 673 |
.SH "APPLICATION-DRIVEN EVENT LOOPS" |
| 674 |
.IX Header "APPLICATION-DRIVEN EVENT LOOPS" |
| 675 |
OpenSSL's QUIC implementation is designed to facilitate applications which wish |
| 676 |
to use the SSL APIs in a blocking fashion, but is also designed to facilitate |
| 677 |
applications which wish to use the SSL APIs in a nonblocking fashion and manage |
| 678 |
their own event loops and polling directly. This is useful when it is desirable |
| 679 |
to host OpenSSL's QUIC implementation on top of an application's existing |
| 680 |
nonblocking I/O infrastructure. |
| 681 |
.PP |
| 682 |
This is supported via the concept of poll descriptors; see |
| 683 |
\&\fBBIO_get_rpoll_descriptor\fR\|(3) for details. Broadly, a \fBBIO_POLL_DESCRIPTOR\fR is |
| 684 |
a structure which expresses some kind of OS resource which can be used to |
| 685 |
synchronise on I/O events. The QUIC implementation provides a |
| 686 |
\&\fBBIO_POLL_DESCRIPTOR\fR based on the poll descriptor provided by the underlying |
| 687 |
network BIO. This is typically an OS socket handle, though custom BIOs could |
| 688 |
choose to implement their own custom poll descriptor format. |
| 689 |
.PP |
| 690 |
Broadly, an application which wishes to manage its own event loop should |
| 691 |
interact with the SSL object as follows: |
| 692 |
.IP \(bu 4 |
| 693 |
It should provide read and write BIOs with nonblocking datagram semantics to |
| 694 |
the SSL object using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). This could be |
| 695 |
a BIO abstracting a network socket such as \fBBIO_s_datagram\fR\|(3), or a BIO |
| 696 |
abstracting some kind of memory buffer such as \fBBIO_s_dgram_pair\fR\|(3). Use of a |
| 697 |
custom BIO is also possible. |
| 698 |
.IP \(bu 4 |
| 699 |
It should configure the SSL object into nonblocking mode by calling |
| 700 |
\&\fBSSL_set_blocking_mode\fR\|(3). |
| 701 |
.IP \(bu 4 |
| 702 |
It should configure the SSL object as desired, set an initial peer as needed |
| 703 |
using \fBSSL_set1_initial_peer_addr\fR\|(3), and trigger the connection process by |
| 704 |
calling \fBSSL_connect\fR\|(3). |
| 705 |
.IP \(bu 4 |
| 706 |
If the network read and write BIOs provided were pollable (for example, |
| 707 |
a \fBBIO_s_datagram\fR\|(3), or a custom BIO which implements |
| 708 |
\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3)), it should |
| 709 |
perform the following steps repeatedly: |
| 710 |
.RS 4 |
| 711 |
.IP \(bu 4 |
| 712 |
The application should call \fBSSL_get_rpoll_descriptor\fR\|(3) and |
| 713 |
\&\fBSSL_get_wpoll_descriptor\fR\|(3) to identify OS resources which can be used for |
| 714 |
synchronisation. |
| 715 |
.IP \(bu 4 |
| 716 |
It should call \fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) to determine |
| 717 |
whether the QUIC implementation is currently interested in readability and |
| 718 |
writability events on the underlying network BIO which was provided, and call |
| 719 |
\&\fBSSL_get_event_timeout\fR\|(3) to determine if any timeout event will become |
| 720 |
applicable in the future. |
| 721 |
.IP \(bu 4 |
| 722 |
It should wait until one of the following events occurs: |
| 723 |
.RS 4 |
| 724 |
.IP \(bu 4 |
| 725 |
The poll descriptor returned by \fBSSL_get_rpoll_descriptor\fR\|(3) becomes readable |
| 726 |
(if \fBSSL_net_read_desired\fR\|(3) returned 1); |
| 727 |
.IP \(bu 4 |
| 728 |
The poll descriptor returned by \fBSSL_get_wpoll_descriptor\fR\|(3) becomes writable |
| 729 |
(if \fBSSL_net_write_desired\fR\|(3) returned 1); |
| 730 |
.IP \(bu 4 |
| 731 |
The timeout returned by \fBSSL_get_event_timeout\fR\|(3) (if any) expires. |
| 732 |
.RE |
| 733 |
.RS 4 |
| 734 |
.Sp |
| 735 |
Once any of these events occurs, \fBSSL_handle_events\fR\|(3) should be called. |
| 736 |
.RE |
| 737 |
.RE |
| 738 |
.RS 4 |
| 739 |
.RE |
| 740 |
.IP \(bu 4 |
| 741 |
If the network read and write BIOs provided were not pollable (for example, in |
| 742 |
the case of \fBBIO_s_dgram_pair\fR\|(3)), the application is responsible for managing |
| 743 |
and synchronising network I/O. It should call \fBSSL_handle_events\fR\|(3) after it |
| 744 |
writes data to a \fBBIO_s_dgram_pair\fR\|(3) or otherwise takes action so that the |
| 745 |
QUIC implementation can read new datagrams via a call to \fBBIO_recvmmsg\fR\|(3) on |
| 746 |
the underlying network BIO. The QUIC implementation may output datagrams via a |
| 747 |
call to \fBBIO_sendmmsg\fR\|(3) and the application is responsible for ensuring these |
| 748 |
are transmitted. |
| 749 |
.Sp |
| 750 |
The application must call \fBSSL_get_event_timeout\fR\|(3) after every call to |
| 751 |
\&\fBSSL_handle_events\fR\|(3) (or another I/O function on the SSL object), and ensure |
| 752 |
that a call to \fBSSL_handle_events\fR\|(3) is performed after the specified timeout |
| 753 |
(if any). |
| 754 |
.SH "WINDOWS APPLICATION NOTES" |
| 755 |
.IX Header "WINDOWS APPLICATION NOTES" |
| 756 |
QUIC protocol uses UDP sockets. The \fBrecvfrom()\fR function on Windows may fail |
| 757 |
with \f(CW\*(C`WSAECONNRESET\*(C'\fR error causing OpenSSL QUIC stack to enter permanent |
| 758 |
error, which prevents further communication over QUIC protocol. Applications |
| 759 |
should disable SIO_UDP_CONNRESET and SIO_UDP_NETRESET error notification |
| 760 |
on UDP sockets they pass to OpenSSL QUIC stack. More details can be found here: |
| 761 |
https://learn.microsoft.com/en\-us/windows/win32/winsock/winsock\-ioctls#sio_udp_connreset\-opcode\-setting\-i\-t3 |
| 762 |
.PP |
| 763 |
OpenSSL attempts to always disable SIO_UDP_CONNRESET and SIO_UDP_NETRESET |
| 764 |
on UDP sockets it receives from application, but no error is reported back |
| 765 |
if the respective \f(CWWSAIoctl()\fR calls fail. Robust application should set those |
| 766 |
options itself so it can handle error notifications from \f(CWWSAIoctl()\fR properly. |
| 767 |
.SH "SEE ALSO" |
| 768 |
.IX Header "SEE ALSO" |
| 769 |
\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3), |
| 770 |
\&\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3), |
| 771 |
\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3), |
| 772 |
\&\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_shutdown_ex\fR\|(3), |
| 773 |
\&\fBSSL_set1_initial_peer_addr\fR\|(3), \fBSSL_stream_conclude\fR\|(3), |
| 774 |
\&\fBSSL_stream_reset\fR\|(3), \fBSSL_get_stream_read_state\fR\|(3), |
| 775 |
\&\fBSSL_get_stream_read_error_code\fR\|(3), \fBSSL_get_conn_close_info\fR\|(3), |
| 776 |
\&\fBSSL_get0_connection\fR\|(3), \fBSSL_get_stream_type\fR\|(3), \fBSSL_get_stream_id\fR\|(3), |
| 777 |
\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3), |
| 778 |
\&\fBSSL_set_incoming_stream_policy\fR\|(3), \fBSSL_set_default_stream_mode\fR\|(3), |
| 779 |
\&\fBSSL_new_listener\fR\|(3), \fBSSL_new_listener_from\fR\|(3), \fBSSL_is_listener\fR\|(3), |
| 780 |
\&\fBSSL_get0_listener\fR\|(3), \fBSSL_listen\fR\|(3), \fBSSL_accept_connection\fR\|(3), |
| 781 |
\&\fBSSL_get_accept_connection_queue_len\fR\|(3), \fBSSL_new_domain\fR\|(3), |
| 782 |
\&\fBSSL_is_domain\fR\|(3), \fBSSL_get0_domain\fR\|(3) |
| 783 |
.SH COPYRIGHT |
| 784 |
.IX Header "COPYRIGHT" |
| 785 |
Copyright 2022\-2026 The OpenSSL Project Authors. All Rights Reserved. |
| 786 |
.PP |
| 787 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 788 |
this file except in compliance with the License. You can obtain a copy |
| 789 |
in the file LICENSE in the source distribution or at |
| 790 |
<https://www.openssl.org/source/license.html>. |