OSSL-GUIDE-QUIC-INTRODUCTION(7SSL) OpenSSL OSSL-GUIDE-QUIC-INTRODUCTION(7SSL)
NAME
ossl-guide-quic-introduction - OpenSSL Guide: An introduction to QUIC in
OpenSSL
INTRODUCTION
This page will provide an introduction to some basic QUIC concepts and
background and how it is used within OpenSSL. It assumes that you have a
basic understanding of UDP/IP and sockets. It also assumes that you are
familiar with some OpenSSL and TLS fundamentals (see
ossl-guide-libraries-introduction(7) and
ossl-guide-tls-introduction(7)).
WHAT IS QUIC?
QUIC is a general purpose protocol for enabling applications to securely
communicate over a network. It is defined in RFC9000 (see
<https://datatracker.ietf.org/doc/rfc9000/>). QUIC integrates parts of
the TLS protocol for connection establishment but independently protects
packets. It provides similar security guarantees to TLS such as
confidentiality, integrity and authentication (see
ossl-guide-tls-introduction(7)).
QUIC delivers a number of advantages:
Multiple streams
It supports multiple streams of communication (see "QUIC STREAMS"
below), allowing application protocols built on QUIC 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 "head-of-line blocking"). 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 TLS/TCP connection.
HTTP/3
Since QUIC is the basis of HTTP/3, support for QUIC also enables
applications to use HTTP/3 using a suitable third-party library.
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 TLS 1.3's 0-RTT functionality but also avoids the round
trip needed to open a TCP socket; thus, it is similar to a
combination of TLS 1.3 0-RTT and TCP Fast Open.
Connection migration
Future versions of OpenSSL will offer support for connection
migration, allowing connections to seamlessly survive IP address
changes.
Datagram based use cases
Future versions of OpenSSL will offer support for the QUIC datagram
extension, allowing support for both TLS and DTLS-style use cases on
a single connection.
Implemented as application library
Because most QUIC implementations, including OpenSSL's
implementation, are implemented as an application library rather
than by an operating system, an application can gain the benefit of
QUIC without needing to wait for an OS update to be deployed. Future
evolutions and enhancements to the QUIC protocol can be delivered as
quickly as an application can be updated without dependency on an OS
update cadence.
Multiplexing over a single UDP socket
Because QUIC is UDP-based, it is possible to multiplex a QUIC
connection on the same UDP socket as some other UDP-based protocols,
such as RTP.
QUIC TIME BASED EVENTS
A key difference between the TLS implementation and the QUIC
implementation in OpenSSL is how time is handled. The QUIC protocol
requires various actions to be performed on a regular basis regardless
of whether application data is being transmitted or received.
OpenSSL introduces a new function SSL_handle_events(3) that will
automatically process any outstanding time based events that must be
handled. Alternatively calling any I/O function such as SSL_read_ex(3)
or SSL_write_ex(3) will also process these events. There is also
SSL_get_event_timeout(3) which tells an application the amount of time
that remains until SSL_handle_events(3) (or any I/O function) must be
called.
Fortunately a blocking application that does not leave the QUIC
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 QUIC connection idle
for a period of time then you will need to arrange to call these
functions.
OpenSSL provides an optional "thread assisted mode" that will
automatically create a background thread and will regularly call
SSL_handle_events(3) in a thread safe manner. This provides a simple way
for an application to satisfy the QUIC requirements for time based
events without having to implement special logic to accomplish it.
QUIC AND TLS
QUIC reuses parts of the TLS protocol in its implementation.
Specifically the TLS handshake also exists in QUIC. The TLS handshake
messages are wrapped up in QUIC protocol messages in order to send them
to the peer. Once the TLS handshake is complete all application data is
sent entirely using QUIC protocol messages without using TLS - although
some TLS handshake messages may still be sent in some circumstances.
This relationship between QUIC and TLS means that many of the API
functions in OpenSSL that apply to TLS connections also apply to QUIC
connections and applications can use them in exactly the same way. Some
functions do not apply to QUIC at all, and others have altered
semantics. You should refer to the documentation pages for each function
for information on how it applies to QUIC. Typically if QUIC is not
mentioned in the manual pages then the functions apply to both TLS and
QUIC.
QUIC STREAMS
QUIC introduces the concept of "streams". 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 TLS application effectively has one bi-directional stream
available to it per TLS connection. A QUIC application can have multiple
uni-directional or bi-directional streams available to it for each
connection.
In OpenSSL an SSL object is used to represent both connections and
streams. A QUIC application creates an initial SSL object to represent
the connection (known as the connection SSL object). Once the connection
is complete additional SSL objects can be created to represent streams
(known as stream SSL objects). Unless configured otherwise, a "default"
stream is also associated with the connection SSL object so you can
still write data and read data to/from it. Some OpenSSL API functions
can only be used with connection SSL objects, and some can only be used
with stream SSL objects. Check the documentation for each function to
confirm what type of SSL object can be used in any particular context. A
connection SSL object that has a default stream attached to it can be
used in contexts that require a connection SSL object or in contexts
that require a stream SSL object.
SOCKETS AND BLOCKING
TLS assumes "stream" type semantics for its underlying transport layer
protocol (usually achieved by using TCP). However QUIC assumes
"datagram" type semantics by using UDP. An OpenSSL application using
QUIC is responsible for creating a BIO to represent the underlying
transport layer. This BIO must support datagrams and is typically
BIO_s_datagram(3), but other BIO choices are available. See bio(7) for
an introduction to OpenSSL's BIO concept.
A significant difference between OpenSSL TLS applications and OpenSSL
QUIC applications is the way that blocking is implemented. In TLS 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.
With an OpenSSL QUIC application the underlying socket must always be
configured to be nonblocking. Howevever the SSL object will, by default,
still operate in blocking mode. So, from an application's perspective,
calls to functions such as SSL_read_ex(3), SSL_write_ex(3) and other I/O
functions will still block. OpenSSL itself provides that blocking
capability for QUIC instead of the socket. If nonblocking behaviour is
desired then the application must call SSL_set_blocking_mode(3).
FURTHER READING
See ossl-guide-quic-client-block(7) to see an example of applying these
concepts in order to write a simple blocking QUIC client.
See ossl-guide-quic-server-block(7) to see an example of applying these
concepts in order to write a simple blocking QUIC server.
SEE ALSO
ossl-guide-introduction(7), ossl-guide-libraries-introduction(7),
ossl-guide-libssl-introduction(7), ossl-guide-tls-introduction(7),
ossl-guide-tls-client-block(7), ossl-guide-quic-client-block(7),
ossl-guide-quic-client-non-block(7), ossl-guide-quic-multi-stream(7),
ossl-guide-quic-server-block(7), ossl-guide-quic-server-non-block(7),
bio(7),
COPYRIGHT
Copyright 2023-2025 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.
3.5.4 2025-09-30OSSL-GUIDE-QUIC-INTRODUCTION(7SSL)
Generated by dwww version 1.16 on Tue Dec 16 05:08:02 CET 2025.