Debian Codegraph @

upstream/debian-unstable/man7/ossl-guide-quic-introduction.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL-GUIDE-QUIC-INTRODUCTION 7SSL"
58 .TH OSSL-GUIDE-QUIC-INTRODUCTION 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ossl\-guide\-quic\-introduction
65 \&\- OpenSSL Guide: An introduction to QUIC in OpenSSL
66 .SH INTRODUCTION
67 .IX Header "INTRODUCTION"
68 This page will provide an introduction to some basic QUIC concepts and
69 background and how it is used within OpenSSL. It assumes that you have a basic
70 understanding of UDP/IP and sockets. It also assumes that you are familiar with
71 some OpenSSL and TLS fundamentals (see \fBossl\-guide\-libraries\-introduction\fR\|(7)
72 and \fBossl\-guide\-tls\-introduction\fR\|(7)).
73 .SH "WHAT IS QUIC?"
74 .IX Header "WHAT IS QUIC?"
75 QUIC is a general purpose protocol for enabling applications to securely
76 communicate over a network. It is defined in RFC9000 (see
77 <https://datatracker.ietf.org/doc/rfc9000/>). QUIC integrates parts of the
78 TLS protocol for connection establishment but independently protects packets.
79 It provides similar security guarantees to TLS such as confidentiality,
80 integrity and authentication (see \fBossl\-guide\-tls\-introduction\fR\|(7)).
81 .PP
82 QUIC delivers a number of advantages:
83 .IP "Multiple streams" 4
84 .IX Item "Multiple streams"
85 It supports multiple streams of communication (see "QUIC STREAMS" below),
86 allowing application protocols built on QUIC to create arbitrarily many
87 bytestreams for communication between a client and server. This allows an
88 application protocol to avoid problems where one packet of data is held up
89 waiting on another packet being delivered (commonly referred to as
90 "head-of-line blocking"). It also enables an application to open additional
91 logical streams without requiring a round-trip exchange of packets between the
92 client and server as is required when opening an additional TLS/TCP
93 connection.
94 .IP HTTP/3 4
95 .IX Item "HTTP/3"
96 Since QUIC is the basis of HTTP/3, support for QUIC also enables applications
97 to use HTTP/3 using a suitable third-party library.
98 .IP "Fast connection initiation" 4
99 .IX Item "Fast connection initiation"
100 Future versions of OpenSSL will offer support for 0\-RTT connection initiation,
101 allowing a connection to be initiated to a server and application data to be
102 transmitted without any waiting time. This is similar to TLS 1.3's 0\-RTT
103 functionality but also avoids the round trip needed to open a TCP socket; thus,
104 it is similar to a combination of TLS 1.3 0\-RTT and TCP Fast Open.
105 .IP "Connection migration" 4
106 .IX Item "Connection migration"
107 Future versions of OpenSSL will offer support for connection migration, allowing
108 connections to seamlessly survive IP address changes.
109 .IP "Datagram based use cases" 4
110 .IX Item "Datagram based use cases"
111 Future versions of OpenSSL will offer support for the QUIC datagram extension,
112 allowing support for both TLS and DTLS-style use cases on a single connection.
113 .IP "Implemented as application library" 4
114 .IX Item "Implemented as application library"
115 Because most QUIC implementations, including OpenSSL's implementation, are
116 implemented as an application library rather than by an operating system, an
117 application can gain the benefit of QUIC without needing to wait for an OS
118 update to be deployed. Future evolutions and enhancements to the QUIC protocol
119 can be delivered as quickly as an application can be updated without dependency
120 on an OS update cadence.
121 .IP "Multiplexing over a single UDP socket" 4
122 .IX Item "Multiplexing over a single UDP socket"
123 Because QUIC is UDP-based, it is possible to multiplex a QUIC connection on the
124 same UDP socket as some other UDP-based protocols, such as RTP.
125 .SH "QUIC TIME BASED EVENTS"
126 .IX Header "QUIC TIME BASED EVENTS"
127 A key difference between the TLS implementation and the QUIC implementation in
128 OpenSSL is how time is handled. The QUIC protocol requires various actions to be
129 performed on a regular basis regardless of whether application data is being
130 transmitted or received.
131 .PP
132 OpenSSL introduces a new function \fBSSL_handle_events\fR\|(3) that will
133 automatically process any outstanding time based events that must be handled.
134 Alternatively calling any I/O function such as \fBSSL_read_ex\fR\|(3) or
135 \&\fBSSL_write_ex\fR\|(3) will also process these events. There is also
136 \&\fBSSL_get_event_timeout\fR\|(3) which tells an application the amount of time that
137 remains until \fBSSL_handle_events\fR\|(3) (or any I/O function) must be called.
138 .PP
139 Fortunately a blocking application that does not leave the QUIC connection idle,
140 and is regularly calling I/O functions does not typically need to worry about
141 this. However if you are developing a nonblocking application or one that may
142 leave the QUIC connection idle for a period of time then you will need to
143 arrange to call these functions.
144 .PP
145 OpenSSL provides an optional "thread assisted mode" that will automatically
146 create a background thread and will regularly call \fBSSL_handle_events\fR\|(3) in a
147 thread safe manner. This provides a simple way for an application to satisfy the
148 QUIC requirements for time based events without having to implement special
149 logic to accomplish it.
150 .SH "QUIC AND TLS"
151 .IX Header "QUIC AND TLS"
152 QUIC reuses parts of the TLS protocol in its implementation. Specifically the
153 TLS handshake also exists in QUIC. The TLS handshake messages are wrapped up in
154 QUIC protocol messages in order to send them to the peer. Once the TLS handshake
155 is complete all application data is sent entirely using QUIC protocol messages
156 without using TLS \- although some TLS handshake messages may still be sent in
157 some circumstances.
158 .PP
159 This relationship between QUIC and TLS means that many of the API functions in
160 OpenSSL that apply to TLS connections also apply to QUIC connections and
161 applications can use them in exactly the same way. Some functions do not apply
162 to QUIC at all, and others have altered semantics. You should refer to the
163 documentation pages for each function for information on how it applies to QUIC.
164 Typically if QUIC is not mentioned in the manual pages then the functions apply
165 to both TLS and QUIC.
166 .SH "QUIC STREAMS"
167 .IX Header "QUIC STREAMS"
168 QUIC introduces the concept of "streams". A stream provides a reliable
169 mechanism for sending and receiving application data between the endpoints. The
170 bytes transmitted are guaranteed to be received in the same order they were sent
171 without any loss of data or reordering of the bytes. A TLS application
172 effectively has one bi-directional stream available to it per TLS connection. A
173 QUIC application can have multiple uni-directional or bi-directional streams
174 available to it for each connection.
175 .PP
176 In OpenSSL an \fBSSL\fR object is used to represent both connections and streams.
177 A QUIC application creates an initial \fBSSL\fR object to represent the connection
178 (known as the connection \fBSSL\fR object). Once the connection is complete
179 additional \fBSSL\fR objects can be created to represent streams (known as stream
180 \&\fBSSL\fR objects). Unless configured otherwise, a "default" stream is also
181 associated with the connection \fBSSL\fR object so you can still write data and
182 read data to/from it. Some OpenSSL API functions can only be used with
183 connection \fBSSL\fR objects, and some can only be used with stream \fBSSL\fR objects.
184 Check the documentation for each function to confirm what type of \fBSSL\fR object
185 can be used in any particular context. A connection \fBSSL\fR object that has a
186 default stream attached to it can be used in contexts that require a connection
187 \&\fBSSL\fR object or in contexts that require a stream \fBSSL\fR object.
188 .SH "SOCKETS AND BLOCKING"
189 .IX Header "SOCKETS AND BLOCKING"
190 TLS assumes "stream" type semantics for its underlying transport layer protocol
191 (usually achieved by using TCP). However QUIC assumes "datagram" type semantics
192 by using UDP. An OpenSSL application using QUIC is responsible for creating a
193 BIO to represent the underlying transport layer. This BIO must support datagrams
194 and is typically \fBBIO_s_datagram\fR\|(3), but other \fBBIO\fR choices are available.
195 See \fBbio\fR\|(7) for an introduction to OpenSSL's \fBBIO\fR concept.
196 .PP
197 A significant difference between OpenSSL TLS applications and OpenSSL QUIC
198 applications is the way that blocking is implemented. In TLS if your application
199 expects blocking behaviour then you configure the underlying socket for
200 blocking. Conversely if your application wants nonblocking behaviour then the
201 underlying socket is configured to be nonblocking.
202 .PP
203 With an OpenSSL QUIC application the underlying socket must always be configured
204 to be nonblocking. Howevever the \fBSSL\fR object will, by default, still operate
205 in blocking mode. So, from an application's perspective, calls to functions such
206 as \fBSSL_read_ex\fR\|(3), \fBSSL_write_ex\fR\|(3) and other I/O functions will still
207 block. OpenSSL itself provides that blocking capability for QUIC instead of the
208 socket. If nonblocking behaviour is desired then the application must call
209 \&\fBSSL_set_blocking_mode\fR\|(3).
210 .SH "FURTHER READING"
211 .IX Header "FURTHER READING"
212 See \fBossl\-guide\-quic\-client\-block\fR\|(7) to see an example of applying these
213 concepts in order to write a simple blocking QUIC client.
214 .PP
215 See \fBossl\-guide\-quic\-server\-block\fR\|(7) to see an example of applying these
216 concepts in order to write a simple blocking QUIC server.
217 .SH "SEE ALSO"
218 .IX Header "SEE ALSO"
219 \&\fBossl\-guide\-introduction\fR\|(7), \fBossl\-guide\-libraries\-introduction\fR\|(7),
220 \&\fBossl\-guide\-libssl\-introduction\fR\|(7), \fBossl\-guide\-tls\-introduction\fR\|(7),
221 \&\fBossl\-guide\-tls\-client\-block\fR\|(7), \fBossl\-guide\-quic\-client\-block\fR\|(7),
222 \&\fBossl\-guide\-quic\-client\-non\-block\fR\|(7), \fBossl\-guide\-quic\-multi\-stream\fR\|(7),
223 \&\fBossl\-guide\-quic\-server\-block\fR\|(7), \fBossl\-guide\-quic\-server\-non\-block\fR\|(7),
224 \&\fBbio\fR\|(7),
225 .SH COPYRIGHT
226 .IX Header "COPYRIGHT"
227 Copyright 2023\-2025 The OpenSSL Project Authors. All Rights Reserved.
228 .PP
229 Licensed under the Apache License 2.0 (the "License"). You may not use
230 this file except in compliance with the License. You can obtain a copy
231 in the file LICENSE in the source distribution or at
232 <https://www.openssl.org/source/license.html>.