Debian Codegraph @

upstream/debian-unstable/man7/openssl-quic.7ssl

raw
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>.