Android_verify/third_party/android-libs/share/man/man7/ossl-guide-quic-introduction.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 "OSSL-GUIDE-QUIC-INTRODUCTION 7ossl"
.TH OSSL-GUIDE-QUIC-INTRODUCTION 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"
ossl\-guide\-quic\-introduction
\&\- OpenSSL Guide: An introduction to QUIC in OpenSSL
.SH "INTRODUCTION"
.IX Header "INTRODUCTION"
This page will provide an introduction to some basic \s-1QUIC\s0 concepts and
background and how it is used within OpenSSL. It assumes that you have a basic
understanding of \s-1UDP/IP\s0 and sockets. It also assumes that you are familiar with
some OpenSSL and \s-1TLS\s0 fundamentals (see \fBossl\-guide\-libraries\-introduction\fR\|(7)
and \fBossl\-guide\-tls\-introduction\fR\|(7)).
.SH "WHAT IS QUIC?"
.IX Header "WHAT IS QUIC?"
\&\s-1QUIC\s0 is a general purpose protocol for enabling applications to securely
communicate over a network. It is defined in \s-1RFC9000\s0 (see
<https://datatracker.ietf.org/doc/rfc9000/>). \s-1QUIC\s0 integrates parts of the
\&\s-1TLS\s0 protocol for connection establishment but independently protects packets.
It provides similar security guarantees to \s-1TLS\s0 such as confidentiality,
integrity and authentication (see \fBossl\-guide\-tls\-introduction\fR\|(7)).
.PP
\&\s-1QUIC\s0 delivers a number of advantages:
.IP "Multiple streams" 4
.IX Item "Multiple streams"
It supports multiple streams of communication (see \*(L"\s-1QUIC STREAMS\*(R"\s0 below),
allowing application protocols built on \s-1QUIC\s0 to create arbitrarily many
bytestreams for communication between a client and server. This allows an
application protocol to avoid problems where one packet of data is held up
waiting on another packet being delivered (commonly referred to as
\&\*(L"head-of-line blocking\*(R"). It also enables an application to open additional
logical streams without requiring a round-trip exchange of packets between the
client and server as is required when opening an additional \s-1TLS/TCP\s0
connection.
.IP "\s-1HTTP/3\s0" 4
.IX Item "HTTP/3"
Since \s-1QUIC\s0 is the basis of \s-1HTTP/3,\s0 support for \s-1QUIC\s0 also enables applications
to use \s-1HTTP/3\s0 using a suitable third-party library.
.IP "Fast connection initiation" 4
.IX Item "Fast connection initiation"
Future versions of OpenSSL will offer support for 0\-RTT connection initiation,
allowing a connection to be initiated to a server and application data to be
transmitted without any waiting time. This is similar to \s-1TLS 1.3\s0's 0\-RTT
functionality but also avoids the round trip needed to open a \s-1TCP\s0 socket; thus,
it is similar to a combination of \s-1TLS 1.3 0\-RTT\s0 and \s-1TCP\s0 Fast Open.
.IP "Connection migration" 4
.IX Item "Connection migration"
Future versions of OpenSSL will offer support for connection migration, allowing
connections to seamlessly survive \s-1IP\s0 address changes.
.IP "Datagram based use cases" 4
.IX Item "Datagram based use cases"
Future versions of OpenSSL will offer support for the \s-1QUIC\s0 datagram extension,
allowing support for both \s-1TLS\s0 and DTLS-style use cases on a single connection.
.IP "Implemented as application library" 4
.IX Item "Implemented as application library"
Because most \s-1QUIC\s0 implementations, including OpenSSL's implementation, are
implemented as an application library rather than by an operating system, an
application can gain the benefit of \s-1QUIC\s0 without needing to wait for an \s-1OS\s0
update to be deployed. Future evolutions and enhancements to the \s-1QUIC\s0 protocol
can be delivered as quickly as an application can be updated without dependency
on an \s-1OS\s0 update cadence.
.IP "Multiplexing over a single \s-1UDP\s0 socket" 4
.IX Item "Multiplexing over a single UDP socket"
Because \s-1QUIC\s0 is UDP-based, it is possible to multiplex a \s-1QUIC\s0 connection on the
same \s-1UDP\s0 socket as some other UDP-based protocols, such as \s-1RTP.\s0
.SH "QUIC TIME BASED EVENTS"
.IX Header "QUIC TIME BASED EVENTS"
A key difference between the \s-1TLS\s0 implementation and the \s-1QUIC\s0 implementation in
OpenSSL is how time is handled. The \s-1QUIC\s0 protocol requires various actions to be
performed on a regular basis regardless of whether application data is being
transmitted or received.
.PP
OpenSSL introduces a new function \fBSSL_handle_events\fR\|(3) that will
automatically process any outstanding time based events that must be handled.
Alternatively calling any I/O function such as \fBSSL_read_ex\fR\|(3) or
\&\fBSSL_write_ex\fR\|(3) will also process these events. There is also
\&\fBSSL_get_event_timeout\fR\|(3) which tells an application the amount of time that
remains until \fBSSL_handle_events\fR\|(3) (or any I/O function) must be called.
.PP
Fortunately a blocking application that does not leave the \s-1QUIC\s0 connection idle,
and is regularly calling I/O functions does not typically need to worry about
this. However if you are developing a nonblocking application or one that may
leave the \s-1QUIC\s0 connection idle for a period of time then you will need to
arrange to call these functions.
.PP
OpenSSL provides an optional \*(L"thread assisted mode\*(R" that will automatically
create a background thread and will regularly call \fBSSL_handle_events\fR\|(3) in a
thread safe manner. This provides a simple way for an application to satisfy the
\&\s-1QUIC\s0 requirements for time based events without having to implement special
logic to accomplish it.
.SH "QUIC AND TLS"
.IX Header "QUIC AND TLS"
\&\s-1QUIC\s0 reuses parts of the \s-1TLS\s0 protocol in its implementation. Specifically the
\&\s-1TLS\s0 handshake also exists in \s-1QUIC.\s0 The \s-1TLS\s0 handshake messages are wrapped up in
\&\s-1QUIC\s0 protocol messages in order to send them to the peer. Once the \s-1TLS\s0 handshake
is complete all application data is sent entirely using \s-1QUIC\s0 protocol messages
without using \s-1TLS\s0 \- although some \s-1TLS\s0 handshake messages may still be sent in
some circumstances.
.PP
This relationship between \s-1QUIC\s0 and \s-1TLS\s0 means that many of the \s-1API\s0 functions in
OpenSSL that apply to \s-1TLS\s0 connections also apply to \s-1QUIC\s0 connections and
applications can use them in exactly the same way. Some functions do not apply
to \s-1QUIC\s0 at all, and others have altered semantics. You should refer to the
documentation pages for each function for information on how it applies to \s-1QUIC.\s0
Typically if \s-1QUIC\s0 is not mentioned in the manual pages then the functions apply
to both \s-1TLS\s0 and \s-1QUIC.\s0
.SH "QUIC STREAMS"
.IX Header "QUIC STREAMS"
\&\s-1QUIC\s0 introduces the concept of \*(L"streams\*(R". A stream provides a reliable
mechanism for sending and receiving application data between the endpoints. The
bytes transmitted are guaranteed to be received in the same order they were sent
without any loss of data or reordering of the bytes. A \s-1TLS\s0 application
effectively has one bi-directional stream available to it per \s-1TLS\s0 connection. A
\&\s-1QUIC\s0 application can have multiple uni-directional or bi-directional streams
available to it for each connection.
.PP
In OpenSSL an \fB\s-1SSL\s0\fR object is used to represent both connections and streams.
A \s-1QUIC\s0 application creates an initial \fB\s-1SSL\s0\fR object to represent the connection
(known as the connection \fB\s-1SSL\s0\fR object). Once the connection is complete
additional \fB\s-1SSL\s0\fR objects can be created to represent streams (known as stream
\&\fB\s-1SSL\s0\fR objects). Unless configured otherwise, a \*(L"default\*(R" stream is also
associated with the connection \fB\s-1SSL\s0\fR object so you can still write data and
read data to/from it. Some OpenSSL \s-1API\s0 functions can only be used with
connection \fB\s-1SSL\s0\fR objects, and some can only be used with stream \fB\s-1SSL\s0\fR objects.
Check the documentation for each function to confirm what type of \fB\s-1SSL\s0\fR object
can be used in any particular context. A connection \fB\s-1SSL\s0\fR object that has a
default stream attached to it can be used in contexts that require a connection
\&\fB\s-1SSL\s0\fR object or in contexts that require a stream \fB\s-1SSL\s0\fR object.
.SH "SOCKETS AND BLOCKING"
.IX Header "SOCKETS AND BLOCKING"
\&\s-1TLS\s0 assumes \*(L"stream\*(R" type semantics for its underlying transport layer protocol
(usually achieved by using \s-1TCP\s0). However \s-1QUIC\s0 assumes \*(L"datagram\*(R" type semantics
by using \s-1UDP.\s0 An OpenSSL application using \s-1QUIC\s0 is responsible for creating a
\&\s-1BIO\s0 to represent the underlying transport layer. This \s-1BIO\s0 must support datagrams
and is typically \fBBIO_s_datagram\fR\|(3), but other \fB\s-1BIO\s0\fR choices are available.
See \fBbio\fR\|(7) for an introduction to OpenSSL's \fB\s-1BIO\s0\fR concept.
.PP
A significant difference between OpenSSL \s-1TLS\s0 applications and OpenSSL \s-1QUIC\s0
applications is the way that blocking is implemented. In \s-1TLS\s0 if your application
expects blocking behaviour then you configure the underlying socket for
blocking. Conversely if your application wants nonblocking behaviour then the
underlying socket is configured to be nonblocking.
.PP
With an OpenSSL \s-1QUIC\s0 application the underlying socket must always be configured
to be nonblocking. Howevever the \fB\s-1SSL\s0\fR object will, by default, still operate
in blocking mode. So, from an application's perspective, calls to functions such
as \fBSSL_read_ex\fR\|(3), \fBSSL_write_ex\fR\|(3) and other I/O functions will still
block. OpenSSL itself provides that blocking capability for \s-1QUIC\s0 instead of the
socket. If nonblocking behaviour is desired then the application must call
\&\fBSSL_set_blocking_mode\fR\|(3).
.SH "FURTHER READING"
.IX Header "FURTHER READING"
See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see an example of applying these
concepts in order to write a simple blocking \s-1QUIC\s0 client.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7),
\&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7),
\&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7), \fBbio\fR\|(7)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 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>.