OPENSSL-QUIC(7ossl) OpenSSL OPENSSL-QUIC(7ossl)
NAME
openssl-quic - OpenSSL QUIC
DESCRIPTION
OpenSSL 3.2 and later features support for the QUIC transport protocol.
You can use OpenSSL's QUIC capabilities for both client and server
applications. This man page describes how to let applications use the
QUIC protocol using the libssl API.
The QUIC protocol maps to the standard SSL API. A QUIC connection is
represented by an SSL object in the same way that a TLS connection is.
Only minimal changes are needed to existing applications which use libssl
API to bring QUIC protocol support in. QUIC clients can use
OSSL_QUIC_client_method(3) or OSSL_QUIC_client_thread_method(3) with
SSL_CTX_new(3). See below for more details about the difference between
the two. For servers, there is only one option: SSL method
OSSL_QUIC_server_method(3) with SSL_CTX_new(3).
The remainder of this man page discusses, in order:
o Default stream mode versus multi-stream mode for clients;
o The changes to existing libssl APIs which are driven by QUIC-related
implementation requirements, which existing applications should bear
in mind;
o Aspects which must be considered by existing applications when
adopting QUIC, including potential changes which may be needed.
o Recommended usage approaches for new applications.
o New, QUIC-specific APIs.
CLIENT MODES OF OPERATION
When a client creates a QUIC connection, by default, it operates in
default stream mode, which is intended to provide compatibility with
existing non-QUIC application usage patterns. In this mode, the
connection has a single stream associated with it. Calls to SSL_read(3)
and SSL_write(3) on the QUIC connection SSL object read and write from
that stream. Whether the stream is client-initiated or server-initiated
from a QUIC perspective depends on whether SSL_read(3) or SSL_write(3) is
called first.
Default stream mode is primarily for compatibility with existing
applications. For new applications utilizing QUIC, it's recommended to
disable this mode and instead adopt the multi-stream API. See the
RECOMMENDATIONS FOR NEW APPLICATIONS section for more details.
Default Stream Mode
A QUIC client connection can be used in either default stream mode or
multi-stream mode. By default, a newly created QUIC connection SSL object
uses default stream mode.
In default stream mode, a stream is implicitly created and bound to the
QUIC connection SSL object; SSL_read(3) and SSL_write(3) calls to the
QUIC connection SSL object work by default and are mapped to that stream.
When default stream mode is used, any API function which can be called on
a QUIC stream SSL object can also be called on a QUIC connection SSL
object, in which case it affects the default stream bound to the
connection.
The identity of a QUIC stream, including its stream ID, varies depending
on whether a stream is client-initiated or server-initiated. In default
stream mode, if a client application calls SSL_read(3) first before any
call to SSL_write(3) on the connection, it is assumed that the
application protocol is using a server-initiated stream, and the
SSL_read(3) call will not complete (either blocking, or failing
appropriately if nonblocking mode is configured) until the server
initiates a stream. Conversely, if the client application calls
SSL_write(3) before any call to SSL_read(3) on the connection, it is
assumed that a client-initiated stream is to be used and such a stream is
created automatically.
Default stream mode is intended to aid compatibility with legacy
applications. New applications adopting QUIC should use multi-stream
mode, described below, and avoid use of the default stream functionality.
It is possible to use additional streams in default stream mode using
SSL_new_stream(3) and SSL_accept_stream(3); note that the default
incoming stream policy will need to be changed using
SSL_set_incoming_stream_policy(3) in order to use SSL_accept_stream(3) in
this case. However, applications using additional streams are strongly
recommended to use multi-stream mode instead.
Calling SSL_new_stream(3) or SSL_accept_stream(3) before a default stream
has been associated with the QUIC connection SSL object will inhibit
future creation of a default stream.
Multi-Stream Mode
The recommended usage mode for new applications adopting QUIC is multi-
stream mode, in which no default stream is attached to the QUIC
connection SSL object and attempts to call SSL_read(3) and SSL_write(3)
on the QUIC connection SSL object fail. Instead, an application calls
SSL_new_stream(3) or SSL_accept_stream(3) to create individual stream SSL
objects for sending and receiving application data using SSL_read(3) and
SSL_write(3).
To use multi-stream mode, call SSL_set_default_stream_mode(3) with an
argument of SSL_DEFAULT_STREAM_MODE_NONE; this function must be called
prior to initiating the connection. The default stream mode cannot be
changed after initiating a connection.
When multi-stream mode is used, meaning that no default stream is
associated with the connection, calls to API functions which are defined
as operating on a QUIC stream fail if called on the QUIC connection SSL
object. For example, calls such as SSL_write(3) or SSL_get_stream_id(3)
will fail.
CHANGES TO EXISTING APIS
Most SSL APIs, such as SSL_read(3) and SSL_write(3), function as they do
for TLS connections and do not have changed semantics, with some
exceptions. The changes to the semantics of existing APIs are as follows:
o Since QUIC uses UDP, SSL_set_bio(3), SSL_set0_rbio(3) and
SSL_set0_wbio(3) function as before, but must now receive a BIO with
datagram semantics. There are broadly four options for applications
to use as a network BIO:
o BIO_s_datagram(3), recommended for most applications, replaces
BIO_s_socket(3) and provides a UDP socket.
o BIO_s_dgram_pair(3) provides BIO pair-like functionality but with
datagram semantics, and is recommended for existing applications
which use a BIO pair or memory BIO to manage libssl's
communication with the network.
o BIO_s_dgram_mem(3) provides a simple memory BIO-like interface
but with datagram semantics. Unlike BIO_s_dgram_pair(3), it is
unidirectional.
o An application may also choose to implement a custom BIO. The new
BIO_sendmmsg(3) and BIO_recvmmsg(3) APIs must be supported.
o SSL_set_fd(3), SSL_set_rfd(3) and SSL_set_wfd(3) traditionally
instantiate a BIO_s_socket(3). For QUIC, these functions instead
instantiate a BIO_s_datagram(3). This is equivalent to instantiating
a BIO_s_datagram(3) and using SSL_set0_rbio(3) and SSL_set0_wbio(3).
o Traditionally, whether the application-level I/O APIs (such as
SSL_read(3) and SSL_write(3) operated in a blocking fashion was
directly correlated with whether the underlying network socket was
configured in a blocking fashion. This is no longer the case;
applications must explicitly configure the desired application-level
blocking mode using SSL_set_blocking_mode(3). See
SSL_set_blocking_mode(3) for details.
o Network-level I/O must always be performed in a nonblocking manner.
The application can still enjoy blocking semantics for calls to
application-level I/O functions such as SSL_read(3) and SSL_write(3),
but the underlying network BIO provided to QUIC (such as a
BIO_s_datagram(3)) must be configured in nonblocking mode. For
application-level blocking functionality, see
SSL_set_blocking_mode(3).
o BIO_new_ssl_connect(3) has been changed to automatically use a
BIO_s_datagram(3) when used with QUIC, therefore applications which
use this do not need to change the BIO they use.
o BIO_new_buffer_ssl_connect(3) cannot be used with QUIC and
applications must change to use BIO_new_ssl_connect(3) instead.
o SSL_shutdown(3) has significant changes in relation to how QUIC
connections must be shut down. In particular, applications should be
advised that the full RFC-conformant QUIC shutdown process may take
an extended amount of time. This may not be suitable for short-lived
processes which should exit immediately after their usage of a QUIC
connection is completed. A rapid shutdown mode is available for such
applications. For details, see SSL_shutdown(3).
o SSL_want(3), SSL_want_read(3) and SSL_want_write(3) no longer reflect
the I/O state of the network BIO passed to the QUIC SSL object, but
instead reflect the flow control state of the QUIC stream associated
with the SSL object.
When used in nonblocking mode, SSL_ERROR_WANT_READ indicates that the
receive part of a QUIC stream does not currently have any more data
available to be read, and SSL_ERROR_WANT_WRITE indicates that the
stream's internal buffer is full.
To determine if the QUIC implementation currently wishes to be
informed of incoming network datagrams, use the new function
SSL_net_read_desired(3); likewise, to determine if the QUIC
implementation currently wishes to be informed when it is possible to
transmit network datagrams, use the new function
SSL_net_write_desired(3). Only applications which wish to manage
their own event loops need to use these functions; see APPLICATION-
DRIVEN EVENT LOOPS for further discussion.
o The use of ALPN is mandatory when using QUIC. Attempts to connect
without configuring ALPN will fail. For information on how to
configure ALPN, see SSL_set_alpn_protos(3).
o Whether QUIC operates in a client or server mode is determined by the
SSL_METHOD used, rather than by calls to SSL_set_connect_state(3) or
SSL_set_accept_state(3). It is not necessary to call either of
SSL_set_connect_state(3) or SSL_set_accept_state(3) before
connecting, but if either of these are called, the function called
must be congruent with the SSL_METHOD being used.
o The SSL_set_min_proto_version(3) and SSL_set_max_proto_version(3)
APIs are not used and the values passed to them are ignored, as
OpenSSL QUIC currently always uses TLS 1.3.
o The following libssl functionality is not available when used with
QUIC.
o Async functionality
o SSL_MODE_AUTO_RETRY
o Record Padding and Fragmentation (SSL_set_block_padding(3), etc.)
o SSL_stateless(3) support
o SRTP functionality
o TLSv1.3 Early Data
o TLS Next Protocol Negotiation cannot be used and is superseded by
ALPN, which must be used instead. The use of ALPN is mandatory
with QUIC.
o Post-Handshake Client Authentication is not available as QUIC
prohibits its use.
o QUIC requires the use of TLSv1.3 or later, therefore
functionality only relevant to older TLS versions is not
available.
o Some cipher suites which are generally available for TLSv1.3 are
not available for QUIC, such as TLS_AES_128_CCM_8_SHA256. Your
application may need to adjust the list of acceptable cipher
suites it passes to libssl.
o CCM mode is not currently supported.
The following libssl functionality is also not available when used
with QUIC, but calls to the relevant functions are treated as no-ops:
o Readahead (SSL_set_read_ahead(3), etc.)
CONSIDERATIONS FOR EXISTING APPLICATIONS
Existing applications seeking to adopt QUIC should apply the following
list to determine what changes they will need to make:
o A client application wishing to use QUIC must use
OSSL_QUIC_client_method(3) or OSSL_QUIC_client_thread_method(3) as
its SSL method. For more information on the differences between these
two methods, see THREAD ASSISTED MODE.
o A server application wishing to use QUIC must use
OSSL_QUIC_server_method(3). The server can then accept new
connections with SSL_accept_connection(3).
o Determine how to provide QUIC with network access. Determine which of
the below apply for your application:
o Your application uses BIO_s_socket(3) to construct a BIO which is
passed to the SSL object to provide it with network access.
Changes needed: Change your application to use BIO_s_datagram(3)
instead when using QUIC. The socket must be configured in
nonblocking mode. You may or may not need to use
SSL_set1_initial_peer_addr(3) to set the initial peer address;
see the QUIC-SPECIFIC APIS section for details.
o Your application uses BIO_new_ssl_connect(3) to construct a BIO
which is passed to the SSL object to provide it with network
access.
Changes needed: No changes needed. Use of QUIC is detected
automatically and a datagram socket is created instead of a
normal TCP socket.
o Your application uses any other I/O strategy in this list but
combines it with a BIO_f_buffer(3), for example using
BIO_push(3).
Changes needed: Disable the usage of BIO_f_buffer(3) when using
QUIC. Usage of such a buffer is incompatible with QUIC as QUIC
requires datagram semantics in its interaction with the network.
o Your application uses a BIO pair to cause the SSL object to read
and write network traffic to a memory buffer. Your application
manages the transmission and reception of buffered data itself in
a way unknown to libssl.
Changes needed: Switch from using a conventional BIO pair to
using BIO_s_dgram_pair(3) instead, which has the necessary
datagram semantics. You will need to modify your application to
transmit and receive using a UDP socket and to use datagram
semantics when interacting with the BIO_s_dgram_pair(3) instance.
o Your application uses a custom BIO method to provide the SSL
object with network access.
Changes needed: The custom BIO must be re-architected to have
datagram semantics. BIO_sendmmsg(3) and BIO_recvmmsg(3) must be
implemented. These calls must operate in a nonblocking fashion.
Optionally, implement the BIO_get_rpoll_descriptor(3) and
BIO_get_wpoll_descriptor(3) methods if desired. Implementing
these methods is required if blocking semantics at the SSL API
level are desired.
o An application must explicitly configure whether it wishes to use the
SSL APIs in blocking mode or not. Traditionally, an SSL object has
automatically operated in blocking or nonblocking mode based on
whether the underlying network BIO operates in blocking or
nonblocking mode. QUIC requires the use of a nonblocking network BIO,
therefore the blocking mode at the application level can be
explicitly configured by the application using the new
SSL_set_blocking_mode(3) API. The default mode is blocking. If an
application wishes to use the SSL object APIs at application level in
a nonblocking manner, it must add a call to SSL_set_blocking_mode(3)
to disable blocking mode.
o If your client application does not choose to use thread assisted
mode, it must ensure that it calls an I/O function on the SSL object
(for example, SSL_read(3) or SSL_write(3)), or the new function
SSL_handle_events(3), regularly. If the SSL object is used in
blocking mode, an ongoing blocking call to an I/O function satisfies
this requirement. This is required to ensure that timer events
required by QUIC are handled in a timely fashion.
Most applications will service the SSL object by calling SSL_read(3)
or SSL_write(3) regularly. If an application does not do this, it
should ensure that SSL_handle_events(3) is called regularly.
SSL_get_event_timeout(3) can be used to determine when
SSL_handle_events(3) must next be called.
If the SSL object is being used with an underlying network BIO which
is pollable (such as BIO_s_datagram(3)), the application can use
SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3) to obtain
resources which can be used to determine when SSL_handle_events(3)
should be called due to network I/O.
Client applications which use thread assisted mode do not need to be
concerned with this requirement, as the QUIC implementation ensures
timeout events are handled in a timely manner. See THREAD ASSISTED
MODE for details.
o Ensure that your usage of SSL_want(3), SSL_want_read(3) and
SSL_want_write(3) reflects the API changes described in CHANGES TO
EXISTING APIS. In particular, you should use these APIs to determine
the ability of a QUIC stream to receive or provide application data,
not to determine if network I/O is required.
o Evaluate your application's use of SSL_shutdown(3) in light of the
changes discussed in CHANGES TO EXISTING APIS. Depending on whether
your application wishes to prioritise RFC conformance or rapid
shutdown, consider using the new SSL_shutdown_ex(3) API instead. See
QUIC-SPECIFIC APIS for details.
RECOMMENDED USAGE IN NEW APPLICATIONS
The recommended usage in new applications varies depending on three
independent design decisions:
o Whether the application will use blocking or nonblocking I/O at the
application level (configured using SSL_set_blocking_mode(3)).
If the application does nonblocking I/O at the application level it
can choose to manage its own polling and event loop; see APPLICATION-
DRIVEN EVENT LOOPS.
o Whether the application intends to give the QUIC implementation
direct access to a network socket (e.g. via BIO_s_datagram(3)) or
whether it intends to buffer transmitted and received datagrams via a
BIO_s_dgram_pair(3) or custom BIO.
The former is preferred where possible as it reduces latency to the
network, which enables QUIC to achieve higher performance and more
accurate connection round trip time (RTT) estimation.
o Whether thread assisted mode will be used (see THREAD ASSISTED MODE).
Simple demos for QUIC usage under these various scenarios can be found at
<https://github.com/openssl/openssl/tree/master/doc/designs/ddd>.
Applications which wish to implement QUIC-specific protocols should be
aware of the APIs listed under QUIC-SPECIFIC APIS which provide access to
QUIC-specific functionality. For example, SSL_stream_conclude(3) can be
used to indicate the end of the sending part of a stream, and
SSL_shutdown_ex(3) can be used to provide a QUIC application error code
when closing a connection.
Regardless of the design decisions chosen above, it is recommended that
new applications avoid use of the default stream mode and use the multi-
stream API by calling SSL_set_default_stream_mode(3); see the MODES OF
OPERATION section for details.
QUIC-SPECIFIC APIS
This section details new APIs which are directly or indirectly related to
QUIC. For details on the operation of each API, see the referenced man
pages.
The following SSL APIs are new but relevant to both QUIC and DTLS:
SSL_get_event_timeout(3)
Determines when the QUIC implementation should next be woken up via a
call to SSL_handle_events(3) (or another I/O function such as
SSL_read(3) or SSL_write(3)), if ever.
This can also be used with DTLS and supersedes DTLSv1_get_timeout(3)
for new usage.
SSL_handle_events(3)
This is a non-specific I/O operation which makes a best effort
attempt to perform any pending I/O or timeout processing. It can be
used to advance the QUIC state machine by processing incoming network
traffic, generating outgoing network traffic and handling any expired
timeout events. Most other I/O functions on an SSL object, such as
SSL_read(3) and SSL_write(3), implicitly perform event handling on
the SSL object, so calling this function is only needed if no other
I/O function is to be called.
This can also be used with DTLS and supersedes
DTLSv1_handle_timeout(3) for new usage.
The following SSL APIs are specific to QUIC:
SSL_new_listener(3)
Creates a listener SSL object, which differs from an ordinary SSL
object in that it is used to provide an abstraction for the
acceptance of network connections in a protocol-agnostic manner.
Currently, listener SSL objects are only supported for QUIC server
usage or client-only usage. The listener interface may expand to
support additional protocols in the future.
SSL_new_listener_from(3)
Creates a listener SSL object which is subordinate to a QUIC domain
SSL object ssl. See SSL_new_domain(3) and openssl-quic-concurrency(7)
for details on QUIC domain SSL objects.
SSL_is_listener(3)
Returns 1 if and only if an SSL object is a listener SSL object.
SSL_get0_listener(3)
Returns an SSL object pointer (potentially to the same object on
which it is called) or NULL.
SSL_listen(3)
Begin listening after a listener has been created. It is ordinarily
not needed to call this because it will be called automatically on
the first call to SSL_accept_connection(3).
SSL_accept_connection(3)
Accepts a new incoming connection for a listener SSL object. A new
SSL object representing the accepted connection is created and
returned on success. If no incoming connection is available and the
listener SSL object is configured in nonblocking mode, NULL is
returned.
SSL_get_accept_connection_queue_len(3)
Returns an informational value listing the number of connections
waiting to be popped from the queue via calls to
SSL_accept_connection().
SSL_new_from_listener(3)
Creates a client connection under a given listener SSL object. For
QUIC, it is also possible to use SSL_new_from_listener() in
conjunction with a listener which does accept incoming connections
(i.e., which was not created using SSL_LISTENER_FLAG_NO_ACCEPT),
leading to a UDP network endpoint which has both incoming and
outgoing connections.
SSL_new_domain(3)
Creates a new QUIC event domain, represented as an SSL object. This
is known as a QUIC domain SSL object. The concept of a QUIC event
domain is discussed in detail in openssl-quic-concurrency(7).
SSL_is_domain(3)
Returns 1 if an SSL object is a QUIC domain SSL object.
SSL_get0_domain(3)
SSL_get0_domain() obtains a pointer to the QUIC domain SSL object in
an SSL object hierarchy (if any).
SSL_set_blocking_mode(3), SSL_get_blocking_mode(3)
Configures whether blocking semantics are used at the application
level. This determines whether calls to functions such as SSL_read(3)
and SSL_write(3) will block.
SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3)
These functions facilitate operation in nonblocking mode.
When an SSL object is being used with an underlying network read BIO
which supports polling, SSL_get_rpoll_descriptor(3) outputs an OS
resource which can be used to synchronise on network readability
events which should result in a call to SSL_handle_events(3).
SSL_get_wpoll_descriptor(3) works in an analogous fashion for the
underlying network write BIO.
The poll descriptors provided by these functions should be used only
when SSL_net_read_desired(3) and SSL_net_write_desired(3) return 1,
respectively.
SSL_net_read_desired(3), SSL_net_write_desired(3)
These functions facilitate operation in nonblocking mode and are used
in conjunction with SSL_get_rpoll_descriptor(3) and
SSL_get_wpoll_descriptor(3) respectively. They determine whether the
respective poll descriptor is currently relevant for the purposes of
polling.
SSL_set1_initial_peer_addr(3)
This function can be used to set the initial peer address for an
outgoing QUIC connection. This function must be used in the general
case when creating an outgoing QUIC connection; however, the correct
initial peer address can be autodetected in some cases. See
SSL_set1_initial_peer_addr(3) for details.
SSL_shutdown_ex(3)
This augments SSL_shutdown(3) by allowing an application error code
to be specified. It also allows an application to decide how quickly
it wants a shutdown to be performed, potentially by trading off
strict RFC compliance.
SSL_stream_conclude(3)
This allows an application to indicate the normal end of the sending
part of a QUIC stream. This corresponds to the FIN flag in the QUIC
RFC. The receiving part of a stream remains usable.
SSL_stream_reset(3)
This allows an application to indicate the non-normal termination of
the sending part of a stream. This corresponds to the RESET_STREAM
frame in the QUIC RFC.
SSL_get_stream_write_state(3) and SSL_get_stream_read_state(3)
This allows an application to determine the current stream states for
the sending and receiving parts of a stream respectively.
SSL_get_stream_write_error_code(3) and SSL_get_stream_read_error_code(3)
This allows an application to determine the application error code
which was signalled by a peer which has performed a non-normal stream
termination of the respective sending or receiving part of a stream,
if any.
SSL_get_conn_close_info(3)
This allows an application to determine the error code which was
signalled when the local or remote endpoint terminated the QUIC
connection.
SSL_get0_connection(3)
Gets the QUIC connection SSL object from a QUIC stream SSL object.
SSL_is_connection(3)
Returns 1 if an SSL object is not a QUIC stream SSL object.
SSL_get_stream_type(3)
Provides information on the kind of QUIC stream which is attached to
the SSL object.
SSL_get_stream_id(3)
Returns the QUIC stream ID which the QUIC protocol has associated
with a QUIC stream.
SSL_new_stream(3)
Creates a new QUIC stream SSL object representing a new, locally-
initiated QUIC stream.
SSL_accept_stream(3)
Potentially yields a new QUIC stream SSL object representing a new
remotely-initiated QUIC stream, blocking until one is available if
the connection is configured to do so.
SSL_get_accept_stream_queue_len(3)
Provides information on the number of pending remotely-initiated
streams.
SSL_set_incoming_stream_policy(3)
Configures how incoming, remotely-initiated streams are handled. The
incoming stream policy can be used to automatically reject streams
created by the peer, or allow them to be handled using
SSL_accept_stream(3).
SSL_set_default_stream_mode(3)
Used to configure or disable default stream mode; see the MODES OF
OPERATION section for details.
The following BIO APIs are not specific to QUIC but have been added to
facilitate QUIC-specific requirements and are closely associated with its
use:
BIO_s_dgram_pair(3)
This is a new BIO method which is similar to a conventional BIO pair
but provides datagram semantics.
BIO_get_rpoll_descriptor(3), BIO_get_wpoll_descriptor(3)
This is a new BIO API which allows a BIO to expose a poll descriptor.
This API is used to implement the corresponding SSL APIs
SSL_get_rpoll_descriptor(3) and SSL_get_wpoll_descriptor(3).
BIO_sendmmsg(3), BIO_recvmmsg(3)
This is a new BIO API which can be implemented by BIOs which
implement datagram semantics. It is implemented by BIO_s_datagram(3)
and BIO_s_dgram_pair(3). It is used by the QUIC implementation to
send and receive UDP datagrams.
BIO_dgram_set_no_trunc(3), BIO_dgram_get_no_trunc(3)
By default, BIO_s_dgram_pair(3) has semantics comparable to those of
Berkeley sockets being used with datagram semantics. This allows an
alternative mode to be enabled in which datagrams will not be
silently truncated if they are too large.
BIO_dgram_set_caps(3), BIO_dgram_get_caps(3)
These functions are used to allow the user of one end of a
BIO_s_dgram_pair(3) to indicate its capabilities to the other end of
a BIO_s_dgram_pair(3). In particular, this allows an application to
inform the QUIC implementation of whether it is prepared to handle
local and/or peer addresses in transmitted datagrams and to provide
the applicable information in received datagrams.
BIO_dgram_get_local_addr_cap(3), BIO_dgram_set_local_addr_enable(3),
BIO_dgram_get_local_addr_enable(3)
Local addressing support refers to the ability of a BIO with datagram
semantics to allow a source address to be specified on transmission
and to report the destination address on reception. These functions
can be used to determine if a BIO can support local addressing and to
enable local addressing support if it can.
BIO_err_is_non_fatal(3)
This is used to determine if an error while calling BIO_sendmmsg(3)
or BIO_recvmmsg(3) is ephemeral in nature, such as "would block"
errors.
THREAD ASSISTED MODE
The optional thread assisted mode for clients can be used with
OSSL_QUIC_client_thread_method(3). In this mode, a background thread is
created automatically. The OpenSSL QUIC implementation then takes
responsibility for ensuring that timeout events are handled on a timely
basis even if no SSL I/O function such as SSL_read(3) or SSL_write(3) is
called by the application for a long time.
All necessary locking is handled automatically internally, but the thread
safety guarantees for the public SSL API are unchanged. Therefore, an
application must still do its own locking if it wishes to make concurrent
use of the public SSL APIs.
Because this method relies on threads, it is not available on platforms
where threading support is not available or not supported by OpenSSL.
However, it does provide the simplest mode of usage for an application.
The implementation may or may not use a common thread or thread pool to
service multiple SSL objects in the same SSL_CTX.
APPLICATION-DRIVEN EVENT LOOPS
OpenSSL's QUIC implementation is designed to facilitate applications
which wish to use the SSL APIs in a blocking fashion, but is also
designed to facilitate applications which wish to use the SSL APIs in a
nonblocking fashion and manage their own event loops and polling
directly. This is useful when it is desirable to host OpenSSL's QUIC
implementation on top of an application's existing nonblocking I/O
infrastructure.
This is supported via the concept of poll descriptors; see
BIO_get_rpoll_descriptor(3) for details. Broadly, a BIO_POLL_DESCRIPTOR
is a structure which expresses some kind of OS resource which can be used
to synchronise on I/O events. The QUIC implementation provides a
BIO_POLL_DESCRIPTOR based on the poll descriptor provided by the
underlying network BIO. This is typically an OS socket handle, though
custom BIOs could choose to implement their own custom poll descriptor
format.
Broadly, an application which wishes to manage its own event loop should
interact with the SSL object as follows:
o It should provide read and write BIOs with nonblocking datagram
semantics to the SSL object using SSL_set0_rbio(3) and
SSL_set0_wbio(3). This could be a BIO abstracting a network socket
such as BIO_s_datagram(3), or a BIO abstracting some kind of memory
buffer such as BIO_s_dgram_pair(3). Use of a custom BIO is also
possible.
o It should configure the SSL object into nonblocking mode by calling
SSL_set_blocking_mode(3).
o It should configure the SSL object as desired, set an initial peer as
needed using SSL_set1_initial_peer_addr(3), and trigger the
connection process by calling SSL_connect(3).
o If the network read and write BIOs provided were pollable (for
example, a BIO_s_datagram(3), or a custom BIO which implements
BIO_get_rpoll_descriptor(3) and BIO_get_wpoll_descriptor(3)), it
should perform the following steps repeatedly:
o The application should call SSL_get_rpoll_descriptor(3) and
SSL_get_wpoll_descriptor(3) to identify OS resources which can be
used for synchronisation.
o It should call SSL_net_read_desired(3) and
SSL_net_write_desired(3) to determine whether the QUIC
implementation is currently interested in readability and
writability events on the underlying network BIO which was
provided, and call SSL_get_event_timeout(3) to determine if any
timeout event will become applicable in the future.
o It should wait until one of the following events occurs:
o The poll descriptor returned by SSL_get_rpoll_descriptor(3)
becomes readable (if SSL_net_read_desired(3) returned 1);
o The poll descriptor returned by SSL_get_wpoll_descriptor(3)
becomes writable (if SSL_net_write_desired(3) returned 1);
o The timeout returned by SSL_get_event_timeout(3) (if any)
expires.
Once any of these events occurs, SSL_handle_events(3) should be
called.
o If the network read and write BIOs provided were not pollable (for
example, in the case of BIO_s_dgram_pair(3)), the application is
responsible for managing and synchronising network I/O. It should
call SSL_handle_events(3) after it writes data to a
BIO_s_dgram_pair(3) or otherwise takes action so that the QUIC
implementation can read new datagrams via a call to BIO_recvmmsg(3)
on the underlying network BIO. The QUIC implementation may output
datagrams via a call to BIO_sendmmsg(3) and the application is
responsible for ensuring these are transmitted.
The application must call SSL_get_event_timeout(3) after every call
to SSL_handle_events(3) (or another I/O function on the SSL object),
and ensure that a call to SSL_handle_events(3) is performed after the
specified timeout (if any).
WINDOWS APPLICATION NOTES
QUIC protocol uses UDP sockets. The recvfrom() function on Windows may
fail with "WSAECONNRESET" error causing OpenSSL QUIC stack to enter
permanent error, which prevents further communication over QUIC protocol.
Applications should disable SIO_UDP_CONNRESET and SIO_UDP_NETRESET error
notification on UDP sockets they pass to OpenSSL QUIC stack. More details
can be found here:
https://learn.microsoft.com/en-us/windows/win32/winsock/winsock-ioctls#sio_udp_connreset-opcode-setting-i-t3
OpenSSL attempts to always disable SIO_UDP_CONNRESET and SIO_UDP_NETRESET
on UDP sockets it receives from application, but no error is reported
back if the respective "WSAIoctl()" calls fail. Robust application should
set those options itself so it can handle error notifications from
"WSAIoctl()" properly.
SEE ALSO
SSL_handle_events(3), SSL_get_event_timeout(3), SSL_net_read_desired(3),
SSL_net_write_desired(3), SSL_get_rpoll_descriptor(3),
SSL_get_wpoll_descriptor(3), SSL_set_blocking_mode(3),
SSL_shutdown_ex(3), SSL_set1_initial_peer_addr(3),
SSL_stream_conclude(3), SSL_stream_reset(3),
SSL_get_stream_read_state(3), SSL_get_stream_read_error_code(3),
SSL_get_conn_close_info(3), SSL_get0_connection(3),
SSL_get_stream_type(3), SSL_get_stream_id(3), SSL_new_stream(3),
SSL_accept_stream(3), SSL_set_incoming_stream_policy(3),
SSL_set_default_stream_mode(3), SSL_new_listener(3),
SSL_new_listener_from(3), SSL_is_listener(3), SSL_get0_listener(3),
SSL_listen(3), SSL_accept_connection(3),
SSL_get_accept_connection_queue_len(3), SSL_new_domain(3),
SSL_is_domain(3), SSL_get0_domain(3)
COPYRIGHT
Copyright 2022-2026 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
3.6.5 2026-09-29 OPENSSL-QUIC(7ossl)
openssl 3.6.5 - Generated Sat Oct 3 11:42:58 CDT 2026