305 lines
14 KiB
Plaintext
305 lines
14 KiB
Plaintext
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
|
|
.\"
|
|
.\" 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-10-22" "3.4.0" "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>.
|