792 lines
40 KiB
Plaintext
792 lines
40 KiB
Plaintext
|
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
|
||
|
|
.\"
|
||
|
|
.\" 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 turned on, 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-01-30" "3.2.1" "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
|
||
|
|
\&\fIOSSL_QUIC_client_method\fR\|(3) or \fIOSSL_QUIC_client_thread_method\fR\|(3) with
|
||
|
|
\&\fISSL_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 \fISSL_read\fR\|(3) and
|
||
|
|
\&\fISSL_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 \fISSL_read\fR\|(3) or \fISSL_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; \fISSL_read\fR\|(3) and \fISSL_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 \fISSL_read\fR\|(3) first before any call to
|
||
|
|
\&\fISSL_write\fR\|(3) on the connection, it is assumed that the application protocol
|
||
|
|
is using a server-initiated stream, and the \fISSL_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 \fISSL_write\fR\|(3) before any call to \fISSL_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
|
||
|
|
\&\fISSL_new_stream\fR\|(3) and \fISSL_accept_stream\fR\|(3); note that the default incoming
|
||
|
|
stream policy will need to be changed using \fISSL_set_incoming_stream_policy\fR\|(3)
|
||
|
|
in order to use \fISSL_accept_stream\fR\|(3) in this case. However, applications
|
||
|
|
using additional streams are strongly recommended to use multi-stream mode
|
||
|
|
instead.
|
||
|
|
.PP
|
||
|
|
Calling \fISSL_new_stream\fR\|(3) or \fISSL_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 \fISSL_read\fR\|(3) and \fISSL_write\fR\|(3) on the \s-1QUIC\s0 connection
|
||
|
|
\&\s-1SSL\s0 object fail. Instead, an application calls \fISSL_new_stream\fR\|(3) or
|
||
|
|
\&\fISSL_accept_stream\fR\|(3) to create individual stream \s-1SSL\s0 objects for sending and
|
||
|
|
receiving application data using \fISSL_read\fR\|(3) and \fISSL_write\fR\|(3).
|
||
|
|
.PP
|
||
|
|
To use multi-stream mode, call \fISSL_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 \fISSL_write\fR\|(3) or \fISSL_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 \fISSL_read\fR\|(3) and \fISSL_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\fISSL_set_bio\fR\|(3), \fISSL_set0_rbio\fR\|(3) and
|
||
|
|
\&\fISSL_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
|
||
|
|
\&\fIBIO_s_datagram\fR\|(3), recommended for most applications, replaces
|
||
|
|
\&\fIBIO_s_socket\fR\|(3) and provides a \s-1UDP\s0 socket.
|
||
|
|
.IP "\(bu" 4
|
||
|
|
\&\fIBIO_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
|
||
|
|
\&\fIBIO_s_dgram_mem\fR\|(3) provides a simple memory BIO-like interface but with
|
||
|
|
datagram semantics. Unlike \fIBIO_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
|
||
|
|
\&\fIBIO_sendmmsg\fR\|(3) and \fIBIO_recvmmsg\fR\|(3) APIs must be supported.
|
||
|
|
.RE
|
||
|
|
.RS 4
|
||
|
|
.RE
|
||
|
|
.IP "\(bu" 4
|
||
|
|
\&\fISSL_set_fd\fR\|(3), \fISSL_set_rfd\fR\|(3) and \fISSL_set_wfd\fR\|(3) traditionally
|
||
|
|
instantiate a \fIBIO_s_socket\fR\|(3). For \s-1QUIC,\s0 these functions instead instantiate
|
||
|
|
a \fIBIO_s_datagram\fR\|(3). This is equivalent to instantiating a
|
||
|
|
\&\fIBIO_s_datagram\fR\|(3) and using \fISSL_set0_rbio\fR\|(3) and \fISSL_set0_wbio\fR\|(3).
|
||
|
|
.IP "\(bu" 4
|
||
|
|
Traditionally, whether the application-level I/O APIs (such as \fISSL_read\fR\|(3)
|
||
|
|
and \fISSL_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 \fISSL_set_blocking_mode\fR\|(3). See
|
||
|
|
\&\fISSL_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 \fISSL_read\fR\|(3) and \fISSL_write\fR\|(3), but the underlying
|
||
|
|
network \s-1BIO\s0 provided to \s-1QUIC \s0(such as a \fIBIO_s_datagram\fR\|(3)) must be configured
|
||
|
|
in nonblocking mode. For application-level blocking functionality, see
|
||
|
|
\&\fISSL_set_blocking_mode\fR\|(3).
|
||
|
|
.IP "\(bu" 4
|
||
|
|
\&\fIBIO_new_ssl_connect\fR\|(3) has been changed to automatically use a
|
||
|
|
\&\fIBIO_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
|
||
|
|
\&\fIBIO_new_buffer_ssl_connect\fR\|(3) cannot be used with \s-1QUIC\s0 and applications must
|
||
|
|
change to use \fIBIO_new_ssl_connect\fR\|(3) instead.
|
||
|
|
.IP "\(bu" 4
|
||
|
|
\&\fISSL_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 \fISSL_shutdown\fR\|(3).
|
||
|
|
.IP "\(bu" 4
|
||
|
|
\&\fISSL_want\fR\|(3), \fISSL_want_read\fR\|(3) and \fISSL_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 \fISSL_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
|
||
|
|
\&\fISSL_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
|
||
|
|
\&\fISSL_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 \fISSL_set_connect_state\fR\|(3) or
|
||
|
|
\&\fISSL_set_accept_state\fR\|(3). It is not necessary to call either of
|
||
|
|
\&\fISSL_set_connect_state\fR\|(3) or \fISSL_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 \fISSL_set_min_proto_version\fR\|(3) and \fISSL_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 (\fISSL_set_block_padding\fR\|(3), etc.)
|
||
|
|
.IP "\(bu" 4
|
||
|
|
\&\fISSL_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 (\fISSL_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 \fIOSSL_QUIC_client_method\fR\|(3) or
|
||
|
|
\&\fIOSSL_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 \fIBIO_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 \fIBIO_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 \fISSL_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 \fIBIO_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
|
||
|
|
\&\fIBIO_f_buffer\fR\|(3), for example using \fIBIO_push\fR\|(3).
|
||
|
|
.Sp
|
||
|
|
Changes needed: Disable the usage of \fIBIO_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
|
||
|
|
\&\fIBIO_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 \fIBIO_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. \fIBIO_sendmmsg\fR\|(3) and \fIBIO_recvmmsg\fR\|(3) must be implemented. These
|
||
|
|
calls must operate in a nonblocking fashion. Optionally, implement the
|
||
|
|
\&\fIBIO_get_rpoll_descriptor\fR\|(3) and \fIBIO_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
|
||
|
|
\&\fISSL_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 \fISSL_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, \fISSL_read\fR\|(3) or
|
||
|
|
\&\fISSL_write\fR\|(3)), or the new function \fISSL_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 \fISSL_read\fR\|(3) or
|
||
|
|
\&\fISSL_write\fR\|(3) regularly. If an application does not do this, it should ensure
|
||
|
|
that \fISSL_handle_events\fR\|(3) is called regularly.
|
||
|
|
.Sp
|
||
|
|
\&\fISSL_get_event_timeout\fR\|(3) can be used to determine when
|
||
|
|
\&\fISSL_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 \fIBIO_s_datagram\fR\|(3)), the application can use
|
||
|
|
\&\fISSL_get_rpoll_descriptor\fR\|(3), \fISSL_get_wpoll_descriptor\fR\|(3) to obtain
|
||
|
|
resources which can be used to determine when \fISSL_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 \fISSL_want\fR\|(3), \fISSL_want_read\fR\|(3) and
|
||
|
|
\&\fISSL_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 \fISSL_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
|
||
|
|
\&\fISSL_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 \fISSL_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 \fIBIO_s_datagram\fR\|(3)) or whether it intends to buffer
|
||
|
|
transmitted and received datagrams via a \fIBIO_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, \fISSL_stream_conclude\fR\|(3) can be used
|
||
|
|
to indicate the end of the sending part of a stream, and \fISSL_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 \fISSL_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 "\fISSL_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
|
||
|
|
\&\fISSL_handle_events\fR\|(3) (or another I/O function such as \fISSL_read\fR\|(3) or
|
||
|
|
\&\fISSL_write\fR\|(3)), if ever.
|
||
|
|
.Sp
|
||
|
|
This can also be used with \s-1DTLS\s0 and supersedes \fIDTLSv1_get_timeout\fR\|(3) for new
|
||
|
|
usage.
|
||
|
|
.IP "\fISSL_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 \fISSL_read\fR\|(3) and \fISSL_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 \fIDTLSv1_handle_timeout\fR\|(3) for
|
||
|
|
new usage.
|
||
|
|
.PP
|
||
|
|
The following \s-1SSL\s0 APIs are specific to \s-1QUIC:\s0
|
||
|
|
.IP "\fISSL_set_blocking_mode\fR\|(3), \fISSL_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 \fISSL_read\fR\|(3) and \fISSL_write\fR\|(3)
|
||
|
|
will block.
|
||
|
|
.IP "\fISSL_get_rpoll_descriptor\fR\|(3), \fISSL_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, \fISSL_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 \fISSL_handle_events\fR\|(3). \fISSL_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
|
||
|
|
\&\fISSL_net_read_desired\fR\|(3) and \fISSL_net_write_desired\fR\|(3) return 1, respectively.
|
||
|
|
.IP "\fISSL_net_read_desired\fR\|(3), \fISSL_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 \fISSL_get_rpoll_descriptor\fR\|(3) and
|
||
|
|
\&\fISSL_get_wpoll_descriptor\fR\|(3) respectively. They determine whether the
|
||
|
|
respective poll descriptor is currently relevant for the purposes of polling.
|
||
|
|
.IP "\fISSL_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 \fISSL_set1_initial_peer_addr\fR\|(3) for details.
|
||
|
|
.IP "\fISSL_shutdown_ex\fR\|(3)" 4
|
||
|
|
.IX Item "SSL_shutdown_ex"
|
||
|
|
This augments \fISSL_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 "\fISSL_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 "\fISSL_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 "\fISSL_get_stream_write_state\fR\|(3) and \fISSL_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 "\fISSL_get_stream_write_error_code\fR\|(3) and \fISSL_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 "\fISSL_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 "\fISSL_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 "\fISSL_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 "\fISSL_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 "\fISSL_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 "\fISSL_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 "\fISSL_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 "\fISSL_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 "\fISSL_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 \fISSL_accept_stream\fR\|(3).
|
||
|
|
.IP "\fISSL_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 "\fIBIO_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 "\fIBIO_get_rpoll_descriptor\fR\|(3), \fIBIO_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 \fISSL_get_rpoll_descriptor\fR\|(3)
|
||
|
|
and \fISSL_get_wpoll_descriptor\fR\|(3).
|
||
|
|
.IP "\fIBIO_sendmmsg\fR\|(3), \fIBIO_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 \fIBIO_s_datagram\fR\|(3) and \fIBIO_s_dgram_pair\fR\|(3).
|
||
|
|
It is used by the \s-1QUIC\s0 implementation to send and receive \s-1UDP\s0 datagrams.
|
||
|
|
.IP "\fIBIO_dgram_set_no_trunc\fR\|(3), \fIBIO_dgram_get_no_trunc\fR\|(3)" 4
|
||
|
|
.IX Item "BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc"
|
||
|
|
By default, \fIBIO_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 "\fIBIO_dgram_set_caps\fR\|(3), \fIBIO_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
|
||
|
|
\&\fIBIO_s_dgram_pair\fR\|(3) to indicate its capabilities to the other end of a
|
||
|
|
\&\fIBIO_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 "\fIBIO_dgram_get_local_addr_cap\fR\|(3), \fIBIO_dgram_set_local_addr_enable\fR\|(3), \fIBIO_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 "\fIBIO_err_is_non_fatal\fR\|(3)" 4
|
||
|
|
.IX Item "BIO_err_is_non_fatal"
|
||
|
|
This is used to determine if an error while calling \fIBIO_sendmmsg\fR\|(3) or
|
||
|
|
\&\fIBIO_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
|
||
|
|
\&\fIOSSL_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 \fISSL_read\fR\|(3) or \fISSL_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
|
||
|
|
\&\fIBIO_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 \fISSL_set0_rbio\fR\|(3) and \fISSL_set0_wbio\fR\|(3). This could be
|
||
|
|
a \s-1BIO\s0 abstracting a network socket such as \fIBIO_s_datagram\fR\|(3), or a \s-1BIO\s0
|
||
|
|
abstracting some kind of memory buffer such as \fIBIO_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
|
||
|
|
\&\fISSL_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 \fISSL_set1_initial_peer_addr\fR\|(3), and trigger the connection process by
|
||
|
|
calling \fISSL_connect\fR\|(3).
|
||
|
|
.IP "\(bu" 4
|
||
|
|
If the network read and write BIOs provided were pollable (for example,
|
||
|
|
a \fIBIO_s_datagram\fR\|(3), or a custom \s-1BIO\s0 which implements
|
||
|
|
\&\fIBIO_get_rpoll_descriptor\fR\|(3) and \fIBIO_get_wpoll_descriptor\fR\|(3)), it should
|
||
|
|
perform the following steps repeatedly:
|
||
|
|
.RS 4
|
||
|
|
.IP "\(bu" 4
|
||
|
|
The application should call \fISSL_get_rpoll_descriptor\fR\|(3) and
|
||
|
|
\&\fISSL_get_wpoll_descriptor\fR\|(3) to identify \s-1OS\s0 resources which can be used for
|
||
|
|
synchronisation.
|
||
|
|
.IP "\(bu" 4
|
||
|
|
It should call \fISSL_net_read_desired\fR\|(3) and \fISSL_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
|
||
|
|
\&\fISSL_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 \fISSL_get_rpoll_descriptor\fR\|(3) becomes readable
|
||
|
|
(if \fISSL_net_read_desired\fR\|(3) returned 1);
|
||
|
|
.IP "\(bu" 4
|
||
|
|
The poll descriptor returned by \fISSL_get_wpoll_descriptor\fR\|(3) becomes writable
|
||
|
|
(if \fISSL_net_write_desired\fR\|(3) returned 1);
|
||
|
|
.IP "\(bu" 4
|
||
|
|
The timeout returned by \fISSL_get_event_timeout\fR\|(3) (if any) expires.
|
||
|
|
.RE
|
||
|
|
.RS 4
|
||
|
|
.Sp
|
||
|
|
Once any of these events occurs, \fISSL_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 \fIBIO_s_dgram_pair\fR\|(3)), the application is responsible for managing
|
||
|
|
and synchronising network I/O. It should call \fISSL_handle_events\fR\|(3) after it
|
||
|
|
writes data to a \fIBIO_s_dgram_pair\fR\|(3) or otherwise takes action so that the
|
||
|
|
\&\s-1QUIC\s0 implementation can read new datagrams via a call to \fIBIO_recvmmsg\fR\|(3) on
|
||
|
|
the underlying network \s-1BIO.\s0 The \s-1QUIC\s0 implementation may output datagrams via a
|
||
|
|
call to \fIBIO_sendmmsg\fR\|(3) and the application is responsible for ensuring these
|
||
|
|
are transmitted.
|
||
|
|
.Sp
|
||
|
|
The application must call \fISSL_get_event_timeout\fR\|(3) after every call to
|
||
|
|
\&\fISSL_handle_events\fR\|(3) (or another I/O function on the \s-1SSL\s0 object), and ensure
|
||
|
|
that a call to \fISSL_handle_events\fR\|(3) is performed after the specified timeout
|
||
|
|
(if any).
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IX Header "SEE ALSO"
|
||
|
|
\&\fISSL_handle_events\fR\|(3), \fISSL_get_event_timeout\fR\|(3),
|
||
|
|
\&\fISSL_net_read_desired\fR\|(3), \fISSL_net_write_desired\fR\|(3),
|
||
|
|
\&\fISSL_get_rpoll_descriptor\fR\|(3), \fISSL_get_wpoll_descriptor\fR\|(3),
|
||
|
|
\&\fISSL_set_blocking_mode\fR\|(3), \fISSL_shutdown_ex\fR\|(3),
|
||
|
|
\&\fISSL_set1_initial_peer_addr\fR\|(3), \fISSL_stream_conclude\fR\|(3),
|
||
|
|
\&\fISSL_stream_reset\fR\|(3), \fISSL_get_stream_read_state\fR\|(3),
|
||
|
|
\&\fISSL_get_stream_read_error_code\fR\|(3), \fISSL_get_conn_close_info\fR\|(3),
|
||
|
|
\&\fISSL_get0_connection\fR\|(3), \fISSL_get_stream_type\fR\|(3), \fISSL_get_stream_id\fR\|(3),
|
||
|
|
\&\fISSL_new_stream\fR\|(3), \fISSL_accept_stream\fR\|(3),
|
||
|
|
\&\fISSL_set_incoming_stream_policy\fR\|(3), \fISSL_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>.
|