Android_verify/third_party/android-libs/share/man/man7/openssl-quic.7ossl

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OPENSSL-QUIC 7ossl"
.TH OPENSSL-QUIC 7ossl "2024-09-03" "3.3.2" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
openssl\-quic \- OpenSSL QUIC
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
OpenSSL 3.2 and later features support for the \s-1QUIC\s0 transport protocol.
Currently, only client connectivity is supported. This man page describes the
usage of \s-1QUIC\s0 client functionality for both existing and new applications.
.PP
\&\s-1QUIC\s0 functionality uses the standard \s-1SSL API. A QUIC\s0 connection is represented
by an \s-1SSL\s0 object in the same way that a \s-1TLS\s0 connection is. Only minimal changes
are needed to existing applications making use of the libssl APIs to make use of
\&\s-1QUIC\s0 client functionality. To make use of \s-1QUIC,\s0 use the \s-1SSL\s0 method
\&\fBOSSL_QUIC_client_method\fR\|(3) or \fBOSSL_QUIC_client_thread_method\fR\|(3) with
\&\fBSSL_CTX_new\fR\|(3).
.PP
When a \s-1QUIC\s0 connection is created, 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 \fBSSL_read\fR\|(3) and
\&\fBSSL_write\fR\|(3) on the \s-1QUIC\s0 connection \s-1SSL\s0 object read and write from that
stream. Whether the stream is client-initiated or server-initiated from a \s-1QUIC\s0
perspective depends on whether \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called
first. See the \s-1MODES OF OPERATION\s0 section for more information.
.PP
The default stream mode is intended for compatibility with existing
applications. New applications using \s-1QUIC\s0 are recommended to disable default
stream mode and use the multi-stream \s-1API\s0; see the \s-1MODES OF OPERATION\s0 section and
the \s-1RECOMMENDATIONS FOR NEW APPLICATIONS\s0 section for more information.
.PP
The remainder of this man page discusses, in order:
.IP "\(bu" 4
Default stream mode versus multi-stream mode;
.IP "\(bu" 4
The changes to existing libssl APIs which are driven by QUIC-related implementation
requirements, which existing applications should bear in mind;
.IP "\(bu" 4
Aspects which must be considered by existing applications when adopting \s-1QUIC,\s0
including potential changes which may be needed.
.IP "\(bu" 4
Recommended usage approaches for new applications.
.IP "\(bu" 4
New, QUIC-specific APIs.
.SH "MODES OF OPERATION"
.IX Header "MODES OF OPERATION"
.SS "Default Stream Mode"
.IX Subsection "Default Stream Mode"
A \s-1QUIC\s0 client connection can be used in either default stream mode or
multi-stream mode. By default, a newly created \s-1QUIC\s0 connection \s-1SSL\s0 object uses
default stream mode.
.PP
In default stream mode, a stream is implicitly created and bound to the \s-1QUIC\s0
connection \s-1SSL\s0 object; \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) calls to the \s-1QUIC\s0
connection \s-1SSL\s0 object work by default and are mapped to that stream.
.PP
When default stream mode is used, any \s-1API\s0 function which can be called on a \s-1QUIC\s0
stream \s-1SSL\s0 object can also be called on a \s-1QUIC\s0 connection \s-1SSL\s0 object, in which
case it affects the default stream bound to the connection.
.PP
The identity of a \s-1QUIC\s0 stream, including its stream \s-1ID,\s0 varies depending on
whether a stream is client-initiated or server-initiated. In default stream
mode, if a client application calls \fBSSL_read\fR\|(3) first before any call to
\&\fBSSL_write\fR\|(3) on the connection, it is assumed that the application protocol
is using a server-initiated stream, and the \fBSSL_read\fR\|(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 \fBSSL_write\fR\|(3) before any call to \fBSSL_read\fR\|(3) on the
connection, it is assumed that a client-initiated stream is to be used
and such a stream is created automatically.
.PP
Default stream mode is intended to aid compatibility with legacy applications.
New applications adopting \s-1QUIC\s0 should use multi-stream mode, described below,
and avoid use of the default stream functionality.
.PP
It is possible to use additional streams in default stream mode using
\&\fBSSL_new_stream\fR\|(3) and \fBSSL_accept_stream\fR\|(3); note that the default incoming
stream policy will need to be changed using \fBSSL_set_incoming_stream_policy\fR\|(3)
in order to use \fBSSL_accept_stream\fR\|(3) in this case. However, applications
using additional streams are strongly recommended to use multi-stream mode
instead.
.PP
Calling \fBSSL_new_stream\fR\|(3) or \fBSSL_accept_stream\fR\|(3) before a default stream
has been associated with the \s-1QUIC\s0 connection \s-1SSL\s0 object will inhibit future
creation of a default stream.
.SS "Multi-Stream Mode"
.IX Subsection "Multi-Stream Mode"
The recommended usage mode for new applications adopting \s-1QUIC\s0 is multi-stream
mode, in which no default stream is attached to the \s-1QUIC\s0 connection \s-1SSL\s0 object
and attempts to call \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3) on the \s-1QUIC\s0 connection
\&\s-1SSL\s0 object fail. Instead, an application calls \fBSSL_new_stream\fR\|(3) or
\&\fBSSL_accept_stream\fR\|(3) to create individual stream \s-1SSL\s0 objects for sending and
receiving application data using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3).
.PP
To use multi-stream mode, call \fBSSL_set_default_stream_mode\fR\|(3) with an
argument of \fB\s-1SSL_DEFAULT_STREAM_MODE_NONE\s0\fR; this function must be called prior
to initiating the connection. The default stream mode cannot be changed after
initiating a connection.
.PP
When multi-stream mode is used, meaning that no default stream is associated
with the connection, calls to \s-1API\s0 functions which are defined as operating on a
\&\s-1QUIC\s0 stream fail if called on the \s-1QUIC\s0 connection \s-1SSL\s0 object. For example, calls
such as \fBSSL_write\fR\|(3) or \fBSSL_get_stream_id\fR\|(3) will fail.
.SH "CHANGES TO EXISTING APIS"
.IX Header "CHANGES TO EXISTING APIS"
Most \s-1SSL\s0 APIs, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), function as they do
for \s-1TLS\s0 connections and do not have changed semantics, with some exceptions. The
changes to the semantics of existing APIs are as follows:
.IP "\(bu" 4
Since \s-1QUIC\s0 uses \s-1UDP,\s0 \fBSSL_set_bio\fR\|(3), \fBSSL_set0_rbio\fR\|(3) and
\&\fBSSL_set0_wbio\fR\|(3) function as before, but must now receive a \s-1BIO\s0 with datagram
semantics. There are broadly four options for applications to use as a network
\&\s-1BIO:\s0
.RS 4
.IP "\(bu" 4
\&\fBBIO_s_datagram\fR\|(3), recommended for most applications, replaces
\&\fBBIO_s_socket\fR\|(3) and provides a \s-1UDP\s0 socket.
.IP "\(bu" 4
\&\fBBIO_s_dgram_pair\fR\|(3) provides \s-1BIO\s0 pair-like functionality but with datagram
semantics, and is recommended for existing applications which use a \s-1BIO\s0 pair or
memory \s-1BIO\s0 to manage libssl's communication with the network.
.IP "\(bu" 4
\&\fBBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO-like interface but with
datagram semantics. Unlike \fBBIO_s_dgram_pair\fR\|(3), it is unidirectional.
.IP "\(bu" 4
An application may also choose to implement a custom \s-1BIO.\s0 The new
\&\fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) APIs must be supported.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\fBSSL_set_fd\fR\|(3), \fBSSL_set_rfd\fR\|(3) and \fBSSL_set_wfd\fR\|(3) traditionally
instantiate a \fBBIO_s_socket\fR\|(3). For \s-1QUIC,\s0 these functions instead instantiate
a \fBBIO_s_datagram\fR\|(3). This is equivalent to instantiating a
\&\fBBIO_s_datagram\fR\|(3) and using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3).
.IP "\(bu" 4
Traditionally, whether the application-level I/O APIs (such as \fBSSL_read\fR\|(3)
and \fBSSL_write\fR\|(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 \fBSSL_set_blocking_mode\fR\|(3). See
\&\fBSSL_set_blocking_mode\fR\|(3) for details.
.IP "\(bu" 4
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 \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3), but the underlying
network \s-1BIO\s0 provided to \s-1QUIC\s0 (such as a \fBBIO_s_datagram\fR\|(3)) must be configured
in nonblocking mode. For application-level blocking functionality, see
\&\fBSSL_set_blocking_mode\fR\|(3).
.IP "\(bu" 4
\&\fBBIO_new_ssl_connect\fR\|(3) has been changed to automatically use a
\&\fBBIO_s_datagram\fR\|(3) when used with \s-1QUIC,\s0 therefore applications which use this
do not need to change the \s-1BIO\s0 they use.
.IP "\(bu" 4
\&\fBBIO_new_buffer_ssl_connect\fR\|(3) cannot be used with \s-1QUIC\s0 and applications must
change to use \fBBIO_new_ssl_connect\fR\|(3) instead.
.IP "\(bu" 4
\&\fBSSL_shutdown\fR\|(3) has significant changes in relation to how \s-1QUIC\s0 connections
must be shut down. In particular, applications should be advised that the full
RFC-conformant \s-1QUIC\s0 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 \s-1QUIC\s0 connection is completed. A rapid shutdown mode
is available for such applications. For details, see \fBSSL_shutdown\fR\|(3).
.IP "\(bu" 4
\&\fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and \fBSSL_want_write\fR\|(3) no longer reflect
the I/O state of the network \s-1BIO\s0 passed to the \s-1QUIC SSL\s0 object, but instead
reflect the flow control state of the \s-1QUIC\s0 stream associated with the \s-1SSL\s0
object.
.Sp
When used in nonblocking mode, \fB\s-1SSL_ERROR_WANT_READ\s0\fR indicates that the
receive part of a \s-1QUIC\s0 stream does not currently have any more data available to
be read, and \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR indicates that the stream's internal buffer
is full.
.Sp
To determine if the \s-1QUIC\s0 implementation currently wishes to be informed of
incoming network datagrams, use the new function \fBSSL_net_read_desired\fR\|(3);
likewise, to determine if the \s-1QUIC\s0 implementation currently wishes to be
informed when it is possible to transmit network datagrams, use the new function
\&\fBSSL_net_write_desired\fR\|(3). Only applications which wish to manage their own event
loops need to use these functions; see \fBAPPLICATION-DRIVEN \s-1EVENT LOOPS\s0\fR for
further discussion.
.IP "\(bu" 4
The use of \s-1ALPN\s0 is mandatory when using \s-1QUIC.\s0 Attempts to connect without
configuring \s-1ALPN\s0 will fail. For information on how to configure \s-1ALPN,\s0 see
\&\fBSSL_set_alpn_protos\fR\|(3).
.IP "\(bu" 4
Whether \s-1QUIC\s0 operates in a client or server mode is determined by the
\&\fB\s-1SSL_METHOD\s0\fR used, rather than by calls to \fBSSL_set_connect_state\fR\|(3) or
\&\fBSSL_set_accept_state\fR\|(3). It is not necessary to call either of
\&\fBSSL_set_connect_state\fR\|(3) or \fBSSL_set_accept_state\fR\|(3) before connecting, but
if either of these are called, the function called must be congruent with the
\&\fB\s-1SSL_METHOD\s0\fR being used. Currently, only client mode is supported.
.IP "\(bu" 4
The \fBSSL_set_min_proto_version\fR\|(3) and \fBSSL_set_max_proto_version\fR\|(3) APIs are
not used and the values passed to them are ignored, as OpenSSL \s-1QUIC\s0 currently
always uses \s-1TLS 1.3.\s0
.IP "\(bu" 4
The following libssl functionality is not available when used with \s-1QUIC.\s0
.RS 4
.IP "\(bu" 4
Async functionality
.IP "\(bu" 4
\&\fB\s-1SSL_MODE_AUTO_RETRY\s0\fR
.IP "\(bu" 4
Record Padding and Fragmentation (\fBSSL_set_block_padding\fR\|(3), etc.)
.IP "\(bu" 4
\&\fBSSL_stateless\fR\|(3) support
.IP "\(bu" 4
\&\s-1SRTP\s0 functionality
.IP "\(bu" 4
TLSv1.3 Early Data
.IP "\(bu" 4
\&\s-1TLS\s0 Next Protocol Negotiation cannot be used and is superseded by \s-1ALPN,\s0 which
must be used instead. The use of \s-1ALPN\s0 is mandatory with \s-1QUIC.\s0
.IP "\(bu" 4
Post-Handshake Client Authentication is not available as \s-1QUIC\s0 prohibits its use.
.IP "\(bu" 4
\&\s-1QUIC\s0 requires the use of TLSv1.3 or later, therefore functionality only relevant
to older \s-1TLS\s0 versions is not available.
.IP "\(bu" 4
Some cipher suites which are generally available for TLSv1.3 are not available
for \s-1QUIC,\s0 such as \fB\s-1TLS_AES_128_CCM_8_SHA256\s0\fR. Your application may need to
adjust the list of acceptable cipher suites it passes to libssl.
.IP "\(bu" 4
\&\s-1CCM\s0 mode is not currently supported.
.RE
.RS 4
.Sp
The following libssl functionality is also not available when used with \s-1QUIC,\s0
but calls to the relevant functions are treated as no-ops:
.IP "\(bu" 4
Readahead (\fBSSL_set_read_ahead\fR\|(3), etc.)
.RE
.RS 4
.RE
.SH "CONSIDERATIONS FOR EXISTING APPLICATIONS"
.IX Header "CONSIDERATIONS FOR EXISTING APPLICATIONS"
Existing applications seeking to adopt \s-1QUIC\s0 should apply the following list to
determine what changes they will need to make:
.IP "\(bu" 4
An application wishing to use \s-1QUIC\s0 must use \fBOSSL_QUIC_client_method\fR\|(3) or
\&\fBOSSL_QUIC_client_thread_method\fR\|(3) as its \s-1SSL\s0 method. For more information
on the differences between these two methods, see \fB\s-1THREAD ASSISTED MODE\s0\fR.
.IP "\(bu" 4
Determine how to provide \s-1QUIC\s0 with network access. Determine which of the below
apply for your application:
.RS 4
.IP "\(bu" 4
Your application uses \fBBIO_s_socket\fR\|(3) to construct a \s-1BIO\s0 which is passed to
the \s-1SSL\s0 object to provide it with network access.
.Sp
Changes needed: Change your application to use \fBBIO_s_datagram\fR\|(3) instead when
using \s-1QUIC.\s0 The socket must be configured in nonblocking mode. You may or may
not need to use \fBSSL_set1_initial_peer_addr\fR\|(3) to set the initial peer
address; see the \fBQUIC-SPECIFIC \s-1APIS\s0\fR section for details.
.IP "\(bu" 4
Your application uses \fBBIO_new_ssl_connect\fR\|(3) to
construct a \s-1BIO\s0 which is passed to the \s-1SSL\s0 object to provide it with network
access.
.Sp
Changes needed: No changes needed. Use of \s-1QUIC\s0 is detected automatically and a
datagram socket is created instead of a normal \s-1TCP\s0 socket.
.IP "\(bu" 4
Your application uses any other I/O strategy in this list but combines it with a
\&\fBBIO_f_buffer\fR\|(3), for example using \fBBIO_push\fR\|(3).
.Sp
Changes needed: Disable the usage of \fBBIO_f_buffer\fR\|(3) when using \s-1QUIC.\s0 Usage
of such a buffer is incompatible with \s-1QUIC\s0 as \s-1QUIC\s0 requires datagram semantics
in its interaction with the network.
.IP "\(bu" 4
Your application uses a \s-1BIO\s0 pair to cause the \s-1SSL\s0 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.
.Sp
Changes needed: Switch from using a conventional \s-1BIO\s0 pair to using
\&\fBBIO_s_dgram_pair\fR\|(3) instead, which has the necessary datagram semantics. You
will need to modify your application to transmit and receive using a \s-1UDP\s0 socket
and to use datagram semantics when interacting with the \fBBIO_s_dgram_pair\fR\|(3)
instance.
.IP "\(bu" 4
Your application uses a custom \s-1BIO\s0 method to provide the \s-1SSL\s0 object with network
access.
.Sp
Changes needed: The custom \s-1BIO\s0 must be re-architected to have datagram
semantics. \fBBIO_sendmmsg\fR\|(3) and \fBBIO_recvmmsg\fR\|(3) must be implemented. These
calls must operate in a nonblocking fashion. Optionally, implement the
\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3) methods if
desired. Implementing these methods is required if blocking semantics at the \s-1SSL
API\s0 level are desired.
.RE
.RS 4
.RE
.IP "\(bu" 4
An application must explicitly configure whether it wishes to use the \s-1SSL\s0 APIs
in blocking mode or not. Traditionally, an \s-1SSL\s0 object has automatically operated
in blocking or nonblocking mode based on whether the underlying network \s-1BIO\s0
operates in blocking or nonblocking mode. \s-1QUIC\s0 requires the use of a
nonblocking network \s-1BIO,\s0 therefore the blocking mode at the application level
must be explicitly configured by the application using the new
\&\fBSSL_set_blocking_mode\fR\|(3) \s-1API.\s0 The default mode is blocking. If an application
wishes to use the \s-1SSL\s0 object APIs at application level in a nonblocking manner,
it must add a call to \fBSSL_set_blocking_mode\fR\|(3) to disable blocking mode.
.IP "\(bu" 4
If your application does not choose to use thread assisted mode, it must ensure
that it calls an I/O function on the \s-1SSL\s0 object (for example, \fBSSL_read\fR\|(3) or
\&\fBSSL_write\fR\|(3)), or the new function \fBSSL_handle_events\fR\|(3), regularly. If the
\&\s-1SSL\s0 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 \s-1QUIC\s0 are handled in a timely fashion.
.Sp
Most applications will service the \s-1SSL\s0 object by calling \fBSSL_read\fR\|(3) or
\&\fBSSL_write\fR\|(3) regularly. If an application does not do this, it should ensure
that \fBSSL_handle_events\fR\|(3) is called regularly.
.Sp
\&\fBSSL_get_event_timeout\fR\|(3) can be used to determine when
\&\fBSSL_handle_events\fR\|(3) must next be called.
.Sp
If the \s-1SSL\s0 object is being used with an underlying network \s-1BIO\s0 which is pollable
(such as \fBBIO_s_datagram\fR\|(3)), the application can use
\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3) to obtain
resources which can be used to determine when \fBSSL_handle_events\fR\|(3) should be
called due to network I/O.
.Sp
Applications which use thread assisted mode do not need to be concerned
with this requirement, as the \s-1QUIC\s0 implementation ensures timeout events
are handled in a timely manner. See \fB\s-1THREAD ASSISTED MODE\s0\fR for details.
.IP "\(bu" 4
Ensure that your usage of \fBSSL_want\fR\|(3), \fBSSL_want_read\fR\|(3) and
\&\fBSSL_want_write\fR\|(3) reflects the \s-1API\s0 changes described in \fB\s-1CHANGES TO EXISTING
APIS\s0\fR. In particular, you should use these APIs to determine the ability of a
\&\s-1QUIC\s0 stream to receive or provide application data, not to to determine if
network I/O is required.
.IP "\(bu" 4
Evaluate your application's use of \fBSSL_shutdown\fR\|(3) in light of the changes
discussed in \fB\s-1CHANGES TO EXISTING APIS\s0\fR. Depending on whether your application
wishes to prioritise \s-1RFC\s0 conformance or rapid shutdown, consider using the new
\&\fBSSL_shutdown_ex\fR\|(3) \s-1API\s0 instead. See \fBQUIC-SPECIFIC \s-1APIS\s0\fR for details.
.SH "RECOMMENDED USAGE IN NEW APPLICATIONS"
.IX Header "RECOMMENDED USAGE IN NEW APPLICATIONS"
The recommended usage in new applications varies depending on three independent
design decisions:
.IP "\(bu" 4
Whether the application will use blocking or nonblocking I/O at the application
level (configured using \fBSSL_set_blocking_mode\fR\|(3)).
.Sp
If the application does nonblocking I/O at the application level it can choose
to manage its own polling and event loop; see \fBAPPLICATION-DRIVEN \s-1EVENT LOOPS\s0\fR.
.IP "\(bu" 4
Whether the application intends to give the \s-1QUIC\s0 implementation direct access to
a network socket (e.g. via \fBBIO_s_datagram\fR\|(3)) or whether it intends to buffer
transmitted and received datagrams via a \fBBIO_s_dgram_pair\fR\|(3) or custom \s-1BIO.\s0
.Sp
The former is preferred where possible as it reduces latency to the network,
which enables \s-1QUIC\s0 to achieve higher performance and more accurate connection
round trip time (\s-1RTT\s0) estimation.
.IP "\(bu" 4
Whether thread assisted mode will be used (see \fB\s-1THREAD ASSISTED MODE\s0\fR).
.PP
Simple demos for \s-1QUIC\s0 usage under these various scenarios can be found at
<https://github.com/openssl/openssl/tree/master/doc/designs/ddd>.
.PP
Applications which wish to implement QUIC-specific protocols should be aware of
the APIs listed under \fBQUIC-SPECIFIC \s-1APIS\s0\fR which provide access to
QUIC-specific functionality. For example, \fBSSL_stream_conclude\fR\|(3) can be used
to indicate the end of the sending part of a stream, and \fBSSL_shutdown_ex\fR\|(3)
can be used to provide a \s-1QUIC\s0 application error code when closing a connection.
.PP
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 \s-1API\s0
by calling \fBSSL_set_default_stream_mode\fR\|(3); see the \s-1MODES OF OPERATION\s0 section
for details.
.SH "QUIC-SPECIFIC APIS"
.IX Header "QUIC-SPECIFIC APIS"
This section details new APIs which are directly or indirectly related to \s-1QUIC.\s0
For details on the operation of each \s-1API,\s0 see the referenced man pages.
.PP
The following \s-1SSL\s0 APIs are new but relevant to both \s-1QUIC\s0 and \s-1DTLS:\s0
.IP "\fBSSL_get_event_timeout\fR\|(3)" 4
.IX Item "SSL_get_event_timeout"
Determines when the \s-1QUIC\s0 implementation should next be woken up via a call to
\&\fBSSL_handle_events\fR\|(3) (or another I/O function such as \fBSSL_read\fR\|(3) or
\&\fBSSL_write\fR\|(3)), if ever.
.Sp
This can also be used with \s-1DTLS\s0 and supersedes \fBDTLSv1_get_timeout\fR\|(3) for new
usage.
.IP "\fBSSL_handle_events\fR\|(3)" 4
.IX Item "SSL_handle_events"
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
\&\s-1QUIC\s0 state machine by processing incoming network traffic, generating outgoing
network traffic and handling any expired timeout events. Most other I/O
functions on an \s-1SSL\s0 object, such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3)
implicitly perform event handling on the \s-1SSL\s0 object, so calling this function is
only needed if no other I/O function is to be called.
.Sp
This can also be used with \s-1DTLS\s0 and supersedes \fBDTLSv1_handle_timeout\fR\|(3) for
new usage.
.PP
The following \s-1SSL\s0 APIs are specific to \s-1QUIC:\s0
.IP "\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_get_blocking_mode\fR\|(3)" 4
.IX Item "SSL_set_blocking_mode, SSL_get_blocking_mode"
Configures whether blocking semantics are used at the application level. This
determines whether calls to functions such as \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3)
will block.
.IP "\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3)" 4
.IX Item "SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor"
These functions facilitate operation in nonblocking mode.
.Sp
When an \s-1SSL\s0 object is being used with an underlying network read \s-1BIO\s0 which
supports polling, \fBSSL_get_rpoll_descriptor\fR\|(3) outputs an \s-1OS\s0 resource which
can be used to synchronise on network readability events which should result in
a call to \fBSSL_handle_events\fR\|(3). \fBSSL_get_wpoll_descriptor\fR\|(3) works in an
analogous fashion for the underlying network write \s-1BIO.\s0
.Sp
The poll descriptors provided by these functions need only be used when
\&\fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) return 1, respectively.
.IP "\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3)" 4
.IX Item "SSL_net_read_desired, SSL_net_write_desired"
These functions facilitate operation in nonblocking mode and are used in
conjunction with \fBSSL_get_rpoll_descriptor\fR\|(3) and
\&\fBSSL_get_wpoll_descriptor\fR\|(3) respectively. They determine whether the
respective poll descriptor is currently relevant for the purposes of polling.
.IP "\fBSSL_set1_initial_peer_addr\fR\|(3)" 4
.IX Item "SSL_set1_initial_peer_addr"
This function can be used to set the initial peer address for an outgoing \s-1QUIC\s0
connection. This function must be used in the general case when creating an
outgoing \s-1QUIC\s0 connection; however, the correct initial peer address can be
autodetected in some cases. See \fBSSL_set1_initial_peer_addr\fR\|(3) for details.
.IP "\fBSSL_shutdown_ex\fR\|(3)" 4
.IX Item "SSL_shutdown_ex"
This augments \fBSSL_shutdown\fR\|(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 \s-1RFC\s0 compliance.
.IP "\fBSSL_stream_conclude\fR\|(3)" 4
.IX Item "SSL_stream_conclude"
This allows an application to indicate the normal end of the sending part of a
\&\s-1QUIC\s0 stream. This corresponds to the \s-1FIN\s0 flag in the \s-1QUIC RFC.\s0 The receiving
part of a stream remains usable.
.IP "\fBSSL_stream_reset\fR\|(3)" 4
.IX Item "SSL_stream_reset"
This allows an application to indicate the non-normal termination of the sending
part of a stream. This corresponds to the \s-1RESET_STREAM\s0 frame in the \s-1QUIC RFC.\s0
.IP "\fBSSL_get_stream_write_state\fR\|(3) and \fBSSL_get_stream_read_state\fR\|(3)" 4
.IX Item "SSL_get_stream_write_state and SSL_get_stream_read_state"
This allows an application to determine the current stream states for the
sending and receiving parts of a stream respectively.
.IP "\fBSSL_get_stream_write_error_code\fR\|(3) and \fBSSL_get_stream_read_error_code\fR\|(3)" 4
.IX Item "SSL_get_stream_write_error_code and SSL_get_stream_read_error_code"
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.
.IP "\fBSSL_get_conn_close_info\fR\|(3)" 4
.IX Item "SSL_get_conn_close_info"
This allows an application to determine the error code which was signalled when
the local or remote endpoint terminated the \s-1QUIC\s0 connection.
.IP "\fBSSL_get0_connection\fR\|(3)" 4
.IX Item "SSL_get0_connection"
Gets the \s-1QUIC\s0 connection \s-1SSL\s0 object from a \s-1QUIC\s0 stream \s-1SSL\s0 object.
.IP "\fBSSL_is_connection\fR\|(3)" 4
.IX Item "SSL_is_connection"
Returns 1 if a \s-1SSL\s0 object is not a \s-1QUIC\s0 stream \s-1SSL\s0 object.
.IP "\fBSSL_get_stream_type\fR\|(3)" 4
.IX Item "SSL_get_stream_type"
Provides information on the kind of \s-1QUIC\s0 stream which is attached
to the \s-1SSL\s0 object.
.IP "\fBSSL_get_stream_id\fR\|(3)" 4
.IX Item "SSL_get_stream_id"
Returns the \s-1QUIC\s0 stream \s-1ID\s0 which the \s-1QUIC\s0 protocol has associated with a \s-1QUIC\s0
stream.
.IP "\fBSSL_new_stream\fR\|(3)" 4
.IX Item "SSL_new_stream"
Creates a new \s-1QUIC\s0 stream \s-1SSL\s0 object representing a new, locally-initiated \s-1QUIC\s0
stream.
.IP "\fBSSL_accept_stream\fR\|(3)" 4
.IX Item "SSL_accept_stream"
Potentially yields a new \s-1QUIC\s0 stream \s-1SSL\s0 object representing a new
remotely-initiated \s-1QUIC\s0 stream, blocking until one is available if the
connection is configured to do so.
.IP "\fBSSL_get_accept_stream_queue_len\fR\|(3)" 4
.IX Item "SSL_get_accept_stream_queue_len"
Provides information on the number of pending remotely-initiated streams.
.IP "\fBSSL_set_incoming_stream_policy\fR\|(3)" 4
.IX Item "SSL_set_incoming_stream_policy"
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 \fBSSL_accept_stream\fR\|(3).
.IP "\fBSSL_set_default_stream_mode\fR\|(3)" 4
.IX Item "SSL_set_default_stream_mode"
Used to configure or disable default stream mode; see the \s-1MODES OF OPERATION\s0
section for details.
.PP
The following \s-1BIO\s0 APIs are not specific to \s-1QUIC\s0 but have been added to
facilitate QUIC-specific requirements and are closely associated with its use:
.IP "\fBBIO_s_dgram_pair\fR\|(3)" 4
.IX Item "BIO_s_dgram_pair"
This is a new \s-1BIO\s0 method which is similar to a conventional \s-1BIO\s0 pair but
provides datagram semantics.
.IP "\fBBIO_get_rpoll_descriptor\fR\|(3), \fBBIO_get_wpoll_descriptor\fR\|(3)" 4
.IX Item "BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor"
This is a new \s-1BIO API\s0 which allows a \s-1BIO\s0 to expose a poll descriptor. This \s-1API\s0
is used to implement the corresponding \s-1SSL\s0 APIs \fBSSL_get_rpoll_descriptor\fR\|(3)
and \fBSSL_get_wpoll_descriptor\fR\|(3).
.IP "\fBBIO_sendmmsg\fR\|(3), \fBBIO_recvmmsg\fR\|(3)" 4
.IX Item "BIO_sendmmsg, BIO_recvmmsg"
This is a new \s-1BIO API\s0 which can be implemented by BIOs which implement datagram
semantics. It is implemented by \fBBIO_s_datagram\fR\|(3) and \fBBIO_s_dgram_pair\fR\|(3).
It is used by the \s-1QUIC\s0 implementation to send and receive \s-1UDP\s0 datagrams.
.IP "\fBBIO_dgram_set_no_trunc\fR\|(3), \fBBIO_dgram_get_no_trunc\fR\|(3)" 4
.IX Item "BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc"
By default, \fBBIO_s_dgram_pair\fR\|(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.
.IP "\fBBIO_dgram_set_caps\fR\|(3), \fBBIO_dgram_get_caps\fR\|(3)" 4
.IX Item "BIO_dgram_set_caps, BIO_dgram_get_caps"
These functions are used to allow the user of one end of a
\&\fBBIO_s_dgram_pair\fR\|(3) to indicate its capabilities to the other end of a
\&\fBBIO_s_dgram_pair\fR\|(3). In particular, this allows an application to inform the
\&\s-1QUIC\s0 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.
.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
.IX Item "BIO_dgram_get_local_addr_cap, BIO_dgram_set_local_addr_enable, BIO_dgram_get_local_addr_enable"
Local addressing support refers to the ability of a \s-1BIO\s0 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
\&\s-1BIO\s0 can support local addressing and to enable local addressing support if it
can.
.IP "\fBBIO_err_is_non_fatal\fR\|(3)" 4
.IX Item "BIO_err_is_non_fatal"
This is used to determine if an error while calling \fBBIO_sendmmsg\fR\|(3) or
\&\fBBIO_recvmmsg\fR\|(3) is ephemeral in nature, such as \*(L"would block\*(R" errors.
.SH "THREAD ASSISTED MODE"
.IX Header "THREAD ASSISTED MODE"
The optional thread assisted mode can be used with
\&\fBOSSL_QUIC_client_thread_method\fR\|(3). In this mode, a background thread is
created automatically. The OpenSSL \s-1QUIC\s0 implementation then takes responsibility
for ensuring that timeout events are handled on a timely basis even if no \s-1SSL
I/O\s0 function such as \fBSSL_read\fR\|(3) or \fBSSL_write\fR\|(3) is called by the
application for a long time.
.PP
All necessary locking is handled automatically internally, but the thread safety
guarantees for the public \s-1SSL API\s0 are unchanged. Therefore, an application must
still do its own locking if it wishes to make concurrent use of the public \s-1SSL\s0
APIs.
.PP
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.
.PP
The implementation may or may not use a common thread or thread pool to service
multiple \s-1SSL\s0 objects in the same \fB\s-1SSL_CTX\s0\fR.
.SH "APPLICATION-DRIVEN EVENT LOOPS"
.IX Header "APPLICATION-DRIVEN EVENT LOOPS"
OpenSSL's \s-1QUIC\s0 implementation is designed to facilitate applications which wish
to use the \s-1SSL\s0 APIs in a blocking fashion, but is also designed to facilitate
applications which wish to use the \s-1SSL\s0 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 \s-1QUIC\s0 implementation on top of an application's existing
nonblocking I/O infrastructure.
.PP
This is supported via the concept of poll descriptors; see
\&\fBBIO_get_rpoll_descriptor\fR\|(3) for details. Broadly, a \fB\s-1BIO_POLL_DESCRIPTOR\s0\fR is
a structure which expresses some kind of \s-1OS\s0 resource which can be used to
synchronise on I/O events. The \s-1QUIC\s0 implementation provides a
\&\fB\s-1BIO_POLL_DESCRIPTOR\s0\fR based on the poll descriptor provided by the underlying
network \s-1BIO.\s0 This is typically an \s-1OS\s0 socket handle, though custom BIOs could
choose to implement their own custom poll descriptor format.
.PP
Broadly, an application which wishes to manage its own event loop should
interact with the \s-1SSL\s0 object as follows:
.IP "\(bu" 4
It should provide read and write BIOs with nonblocking datagram semantics to
the \s-1SSL\s0 object using \fBSSL_set0_rbio\fR\|(3) and \fBSSL_set0_wbio\fR\|(3). This could be
a \s-1BIO\s0 abstracting a network socket such as \fBBIO_s_datagram\fR\|(3), or a \s-1BIO\s0
abstracting some kind of memory buffer such as \fBBIO_s_dgram_pair\fR\|(3). Use of a
custom \s-1BIO\s0 is also possible.
.IP "\(bu" 4
It should configure the \s-1SSL\s0 object into nonblocking mode by calling
\&\fBSSL_set_blocking_mode\fR\|(3).
.IP "\(bu" 4
It should configure the \s-1SSL\s0 object as desired, set an initial peer as needed
using \fBSSL_set1_initial_peer_addr\fR\|(3), and trigger the connection process by
calling \fBSSL_connect\fR\|(3).
.IP "\(bu" 4
If the network read and write BIOs provided were pollable (for example,
a \fBBIO_s_datagram\fR\|(3), or a custom \s-1BIO\s0 which implements
\&\fBBIO_get_rpoll_descriptor\fR\|(3) and \fBBIO_get_wpoll_descriptor\fR\|(3)), it should
perform the following steps repeatedly:
.RS 4
.IP "\(bu" 4
The application should call \fBSSL_get_rpoll_descriptor\fR\|(3) and
\&\fBSSL_get_wpoll_descriptor\fR\|(3) to identify \s-1OS\s0 resources which can be used for
synchronisation.
.IP "\(bu" 4
It should call \fBSSL_net_read_desired\fR\|(3) and \fBSSL_net_write_desired\fR\|(3) to determine
whether the \s-1QUIC\s0 implementation is currently interested in readability and
writability events on the underlying network \s-1BIO\s0 which was provided, and call
\&\fBSSL_get_event_timeout\fR\|(3) to determine if any timeout event will become
applicable in the future.
.IP "\(bu" 4
It should wait until one of the following events occurs:
.RS 4
.IP "\(bu" 4
The poll descriptor returned by \fBSSL_get_rpoll_descriptor\fR\|(3) becomes readable
(if \fBSSL_net_read_desired\fR\|(3) returned 1);
.IP "\(bu" 4
The poll descriptor returned by \fBSSL_get_wpoll_descriptor\fR\|(3) becomes writable
(if \fBSSL_net_write_desired\fR\|(3) returned 1);
.IP "\(bu" 4
The timeout returned by \fBSSL_get_event_timeout\fR\|(3) (if any) expires.
.RE
.RS 4
.Sp
Once any of these events occurs, \fBSSL_handle_events\fR\|(3) should be called.
.RE
.RE
.RS 4
.RE
.IP "\(bu" 4
If the network read and write BIOs provided were not pollable (for example, in
the case of \fBBIO_s_dgram_pair\fR\|(3)), the application is responsible for managing
and synchronising network I/O. It should call \fBSSL_handle_events\fR\|(3) after it
writes data to a \fBBIO_s_dgram_pair\fR\|(3) or otherwise takes action so that the
\&\s-1QUIC\s0 implementation can read new datagrams via a call to \fBBIO_recvmmsg\fR\|(3) on
the underlying network \s-1BIO.\s0 The \s-1QUIC\s0 implementation may output datagrams via a
call to \fBBIO_sendmmsg\fR\|(3) and the application is responsible for ensuring these
are transmitted.
.Sp
The application must call \fBSSL_get_event_timeout\fR\|(3) after every call to
\&\fBSSL_handle_events\fR\|(3) (or another I/O function on the \s-1SSL\s0 object), and ensure
that a call to \fBSSL_handle_events\fR\|(3) is performed after the specified timeout
(if any).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3),
\&\fBSSL_net_read_desired\fR\|(3), \fBSSL_net_write_desired\fR\|(3),
\&\fBSSL_get_rpoll_descriptor\fR\|(3), \fBSSL_get_wpoll_descriptor\fR\|(3),
\&\fBSSL_set_blocking_mode\fR\|(3), \fBSSL_shutdown_ex\fR\|(3),
\&\fBSSL_set1_initial_peer_addr\fR\|(3), \fBSSL_stream_conclude\fR\|(3),
\&\fBSSL_stream_reset\fR\|(3), \fBSSL_get_stream_read_state\fR\|(3),
\&\fBSSL_get_stream_read_error_code\fR\|(3), \fBSSL_get_conn_close_info\fR\|(3),
\&\fBSSL_get0_connection\fR\|(3), \fBSSL_get_stream_type\fR\|(3), \fBSSL_get_stream_id\fR\|(3),
\&\fBSSL_new_stream\fR\|(3), \fBSSL_accept_stream\fR\|(3),
\&\fBSSL_set_incoming_stream_policy\fR\|(3), \fBSSL_set_default_stream_mode\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.