path: root/doc/man7/openssl-quic.pod

=pod

=head1 NAME

openssl-quic - OpenSSL QUIC

=head1 DESCRIPTION

OpenSSL 3.2 and later features support for the QUIC transport protocol.
Currently, only client connectivity and a single stream is supported.
This man page describes the usage of QUIC client functionality for both existing
and new applications.

QUIC functionality uses 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 making use of the libssl APIs to make use of
QUIC client functionality. To make use of QUIC, use the SSL method
L<OSSL_QUIC_client_method(3)> or L<OSSL_QUIC_client_thread_method(3)> with
L<SSL_CTX_new(3)>.

When a QUIC connection is created, it has a single bidirectional stream
associated with it. Calls to L<SSL_read(3)> and L<SSL_write(3)> on the QUIC
connection SSL object read and write from that stream.

The remainder of this man page discusses, in order:

=over 4

=item

The changes to existing libssl APIs which are driven by QUIC-related implementation
requirements, which existing applications should bear in mind;

=item

Aspects which must be considered by existing applications when adopting QUIC,
including potential changes which may be needed.

=item

Recommended usage approaches for new applications.

=item

New, QUIC-specific APIs.

=back

=head1 CHANGES TO EXISTING APIS

Most SSL APIs, such as L<SSL_read(3)> and L<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:

=over 4

=item

Since QUIC uses UDP, L<SSL_set_bio(3)>, L<SSL_set0_rbio(3)> and
L<SSL_set0_wbio(3)> function as before, but must now receive a BIO with datagram
semantics. There are broadly three options for applications to use as a network
BIO:

=over 4

=item

L<BIO_s_datagram(3)>, recommended for most applications, replaces
L<BIO_s_socket(3)> and provides a UDP socket.

=item

L<BIO_s_dgram_pair(3)> provides BIO pair-like function 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.

=item

An application may also choose to implement a custom BIO. The new
L<BIO_sendmmsg(3)> and L<BIO_recvmmsg(3)> APIs must be supported.

=back

=item

L<SSL_set_fd(3)>, L<SSL_set_rfd(3)> and L<SSL_set_wfd(3)> traditionally
instantiate a L<BIO_s_socket(3)>. For QUIC, these functions instead instantiate
a L<BIO_s_datagram(3)>. This is equivalent to instantiating a
L<BIO_s_datagram(3)> and using L<SSL_set0_rbio(3)> and L<SSL_set0_wbio(3)>.

=item

L<BIO_new_ssl_connect(3)> has been changed to automatically use a
L<BIO_s_datagram(3)> when used with QUIC, therefore applications which use this
do not need to change the BIO they use.

=item

L<BIO_new_buffer_ssl_connect(3)> cannot be used with QUIC and applications must
change to use L<BIO_new_ssl_connect(3)> instead.

=item

L<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 L<SSL_shutdown(3)>.

=item

L<SSL_want(3)>, L<SSL_want_read(3)> and L<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, B<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 B<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 L<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
L<SSL_net_write_desired(3)>. Only applications which wish to manage their own event
loops need to use these functions; see B<APPLICATION-DRIVEN EVENT LOOPS> for
further discussion.

=item

The use of ALPN is mandatory when using QUIC. For information on how to
configure ALPN, see L<SSL_set_alpn_protos(3)>.

=item

The following libssl functionality is not available when used with QUIC.

=over 4

=item

Async functionality

=item

B<SSL_MODE_AUTO_RETRY>

=item

Record Padding and Fragmentation (L<SSL_set_block_padding(3)>, etc.)

=item

L<SSL_stateless(3)> support

=item

SRTP functionality

=item

TLSv1.3 Early Data

=item

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.

=item

Post-Handshake Client Authentication is not available as QUIC prohibits its use.

=item

QUIC requires the use of TLSv1.3 or later, therefore functionality only relevant
to older TLS versions is not available.

=item

Some cipher suites which are generally available for TLSv1.3 are not available
for QUIC, such as B<TLS_AES_128_CCM_8_SHA256>. Your application may need to
adjust the list of acceptable cipher suites it passes to libssl.

=item

CCM mode is not currently supported.

=back

The following libssl functionality is also not available when used with QUIC,
but calls to the relevant functions are treated as no-ops:

=over 4

=item

Readahead (L<SSL_set_read_ahead(3)>, etc.)

=back

=back

=head1 CONSIDERATIONS FOR EXISTING APPLICATIONS

Existing applications seeking to adopt QUIC should apply the following list to
determine what changes they will need to make:

=over 4

=item

An application wishing to use QUIC must use L<OSSL_QUIC_client_method(3)> or
L<OSSL_QUIC_client_thread_method(3)> as its SSL method. For more information
on the differences between these two methods, see B<THREAD ASSISTED MODE>.

=item

Determine how to provide QUIC with network access. Determine which of the below
apply for your application:

=over 4

=item

Your application uses L<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 L<BIO_s_datagram(3)> instead when
using QUIC. You may or may not need to use L<SSL_set_initial_peer_addr(3)> to
set the initial peer address; see the B<QUIC-SPECIFIC APIS> section for details.

=item

Your application uses L<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.

=item

Your application uses any other I/O strategy in this list but combines it with a
L<BIO_f_buffer(3)>, for example using L<BIO_push(3)>.

Changes needed: Disable the usage of L<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.

=item

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
L<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 L<BIO_s_dgram_pair(3)>
instance.

=item

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. L<BIO_sendmmsg(3)> and L<BIO_recvmmsg(3)> must be implemented. These
calls must operate in a nonblocking fashion. Optionally, implement the
L<BIO_get_rpoll_descriptor(3)> and L<BIO_get_wpoll_descriptor(3)> methods if
desired. Implementing these methods is required if blocking semantics at the SSL
API level are desired.

=back

=item

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
must be explicitly configured by the application using the new
L<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 L<SSL_set_blocking_mode(3)> to disable blocking mode.

=item

If your 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, L<SSL_read(3)> or
L<SSL_write(3)>), or the new function L<SSL_tick(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 L<SSL_read(3)> or
L<SSL_write(3)> regularly. If an application does not do this, it should ensure
that L<SSL_tick(3)> is called regularly.

L<SSL_get_tick_timeout(3)> can be used to determine when L<SSL_tick(3)> must
next be called.

If the SSL object is being used with an underlying network BIO which is pollable
(such as L<BIO_s_datagram(3)>), the application can use
L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)> to obtain
resources which can be used to determine when L<SSL_tick(3)> should be called
due to network I/O.

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 B<THREAD ASSISTED MODE> for details.

=item

Ensure that your usage of L<SSL_want(3)>, L<SSL_want_read(3)> and
L<SSL_want_write(3)> reflects the API changes described in B<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 to determine if
network I/O is required.

=item

Evaluate your application's use of L<SSL_shutdown(3)> in light of the changes
discussed in B<CHANGES TO EXISTING APIS>. Depending on whether your application
wishes to prioritise RFC conformance or rapid shutdown, consider using the new
L<SSL_shutdown_ex(3)> API instead. See B<QUIC-SPECIFIC APIS> for details.

=back

=head1 RECOMMENDED USAGE IN NEW APPLICATIONS

The recommended usage in new applications varies depending on three independent
design decisions:

=over 4

=item

Whether the application will use blocking or nonblocking I/O at the application
level (configured using L<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 B<APPLICATION-DRIVEN EVENT LOOPS>.

=item

Whether the application intends to give the QUIC implementation direct access to
a network socket (e.g. via L<BIO_s_datagram(3)>) or whether it intends to buffer
transmitted and received datagrams via a L<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.

=item

Whether thread assisted mode will be used (see B<THREAD ASSISTED MODE>).

=back

Simple demos for QUIC usage under these various scenarios can be found at
L<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 B<QUIC-SPECIFIC APIS> which provide access to
QUIC-specific functionality. For example, L<SSL_stream_conclude(3)> can be used
to indicate the end of the sending part of a stream, and L<SSL_shutdown_ex(3)>
can be used to provide a QUIC application error code when closing a connection.

=head1 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:

=over 4

=item L<SSL_get_tick_timeout(3)>

Determines when the QUIC implementation should next be woken up via a call to
L<SSL_tick(3)> (or another I/O function such as L<SSL_read(3)> or
L<SSL_write(3)>), if ever.

This can also be used with DTLS and supersedes L<DTLSv1_get_timeout(3)> for new
usage.

=item L<SSL_tick(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 L<SSL_read(3)> and L<SSL_write(3)>
implicitly perform ticking of 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 L<DTLSv1_handle_timeout(3)> for
new usage.

=back

The following SSL APIs are specific to QUIC:

=over 4

=item L<SSL_set_blocking_mode(3)>, L<SSL_get_blocking_mode(3)>

Configures whether blocking semantics are used at the application level. This
determines whether calls to functions such as L<SSL_read(3)> and L<SSL_write(3)>
will block.

=item L<SSL_get_rpoll_descriptor(3)>, L<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, L<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 L<SSL_tick(3)>. L<SSL_get_wpoll_descriptor(3)> works in an analogous
fashion for the underlying network write BIO.

The poll descriptors provided by these functions need only be used when
L<SSL_net_read_desired(3)> and L<SSL_net_write_desired(3)> return 1, respectively.

=item L<SSL_net_read_desired(3)>, L<SSL_net_write_desired(3)>

These functions facilitate operation in nonblocking mode and are used in
conjunction with L<SSL_get_rpoll_descriptor(3)> and
L<SSL_get_wpoll_descriptor(3)> respectively. They determine whether the
respective poll descriptor is currently relevant for the purposes of polling.

=item L<SSL_set_initial_peer_addr(3)>

This functions 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 L<SSL_set_initial_peer_addr(3)> for details.

=item L<SSL_shutdown_ex(3)>

This augments L<SSL_shutdown(3)> by allowing an application error code to be
specified. It also allows a client to decide how quickly it wants a shutdown to
be performed, potentially by trading off strict RFC compliance.

=item L<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.

=item L<SSL_stream_reset(3)>

This allows an application to indicate the non-normal termination of a stream,
including both its sending and receiving parts. This corresponds to the
RESET_STREAM frame in the QUIC RFC.

=item L<SSL_get_stream_state(3)>

This allows an application to determine the current stream state.

=item L<SSL_get_stream_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, if any.

=item L<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.

=back

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:

=over 4

=item L<BIO_s_dgram_pair(3)>

This is a new BIO method which is similar to a conventional BIO pair but
provides datagram semantics.

=item L<BIO_get_rpoll_descriptor(3)>, L<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 L<SSL_get_rpoll_descriptor(3)>
and L<SSL_get_wpoll_descriptor(3)>.

=item L<BIO_sendmmsg(3)>, L<BIO_recvmmsg(3)>

This is a new BIO API which can be implemented by BIOs which implement datagram
semantics. It is implemented by L<BIO_s_datagram(3)> and L<BIO_s_dgram_pair(3)>.
It is used by the QUIC implementation to send and receive UDP datagrams.

=item L<BIO_dgram_set_no_trunc(3)>, L<BIO_dgram_get_no_trunc(3)>

By default, L<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.

=item L<BIO_dgram_set_caps(3)>, L<BIO_dgram_get_caps(3)>

These functions are used to allow the user of one end of a
L<BIO_s_dgram_pair(3)> to indicate its capabilities to the other end of a
L<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.

=item L<BIO_dgram_get_local_addr_cap(3)>, L<BIO_dgram_set_local_addr_enable(3)>,
L<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.

=item L<BIO_err_is_non_fatal(3)>

This is used to determine if an error while calling L<BIO_sendmmsg(3)> or
L<BIO_recvmmsg(3)> is ephemeral in nature, such as "would block" errors.

=back

=head1 THREAD ASSISTED MODE

The optional thread assisted mode can be used with
L<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 L<SSL_read(3)> or L<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 B<SSL_CTX>.

=begin comment

TODO(QUIC): Amend this man page once thread assisted mode is supported.

=end comment

=head1 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
L<BIO_get_rpoll_descriptor(3)> for details. Broadly, a B<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
B<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:

=over 4

=item

It should provide read and write BIOs with nonblocking datagram semantics to
the SSL object using L<SSL_set0_rbio(3)> and L<SSL_set0_wbio(3)>. This could be
a BIO abstracting a network socket such as L<BIO_s_datagram(3)>, or a BIO
abstracting some kind of memory buffer such as L<BIO_s_dgram_pair(3)>. Use of a
custom BIO is also possible.

=item

It should configure the SSL object into nonblocking mode by calling
L<SSL_set_blocking_mode(3)>.

=item

It should configure the SSL object as desired, set an initial peer as needed
using L<SSL_set_initial_peer_addr(3)>, and trigger the connection process by
calling L<SSL_connect(3)>.

=item

If the network read and write BIOs provided were pollable (for example,
a L<BIO_s_datagram(3)>, or a custom BIO which implements
L<BIO_get_rpoll_descriptor(3)> and L<BIO_get_wpoll_descriptor(3)>), it should
perform the following steps repeatedly:

=over 4

=item

The application should call L<SSL_get_rpoll_descriptor(3)> and
L<SSL_get_wpoll_descriptor(3)> to identify OS resources which can be used for
synchronisation.

=item

It should call L<SSL_net_read_desired(3)> and L<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
L<SSL_get_tick_timeout(3)> to determine if any timeout event will become
applicable in the future.

=item

It should wait until one of the following events occurs:

=over 4

=item

The poll descriptor returned by L<SSL_get_rpoll_descriptor(3)> becomes readable
(if L<SSL_net_read_desired(3)> returned 1);

=item

The poll descriptor returned by L<SSL_get_wpoll_descriptor(3)> becomes writable
(if L<SSL_net_write_desired(3)> returned 1);

=item

The timeout returned by L<SSL_get_tick_timeout(3)> (if any) expires.

=back

Once any of these events occurs, L<SSL_tick(3)> should be called.

=back

=item

If the network read and write BIOs provided were not pollable (for example, in
the case of L<BIO_s_dgram_pair(3)>), the application is responsible for managing
and synchronising network I/O. It should call L<SSL_tick(3)> after it writes
data to a L<BIO_s_dgram_pair(3)> or otherwise takes action so that the QUIC
implementation can read new datagrams via a call to L<BIO_read(3)> on the
underlying network BIO. The QUIC implementation may output datagrams via a call
to L<BIO_write(3)> and the application is responsible for ensuring these are
transmitted.

The application must call L<SSL_get_tick_timeout(3)> after every call to
L<SSL_tick(3)> (or another I/O function on the SSL object), and ensure that a
call to L<SSL_tick(3)> is performed after the specified timeout (if any).

=back

=head1 SEE ALSO

L<SSL_tick(3)>, L<SSL_get_tick_timeout(3)>, L<SSL_net_read_desired(3)>,
L<SSL_net_write_desired(3)>, L<SSL_get_rpoll_descriptor(3)>,
L<SSL_get_wpoll_descriptor(3)>, L<SSL_set_blocking_mode(3)>,
L<SSL_shutdown_ex(3)>, L<SSL_set_initial_peer_addr(3)>

=head1 COPYRIGHT

Copyright 2022 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
L<https://www.openssl.org/source/license.html>.

=cut