OSSL-GUIDE-QUIC-INTRODUCTION(7ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 ossl-guide-quic-introduction (7ossl)

okay bestie, welcome to the OpenSSL Guide: An Introduction to QUIC in OpenSSL — literally the softest possible landing pad for understanding what QUIC even is and how OpenSSL does it. 🦋

✨ INTRODUCTION ✨

This page gives you an intro to some basic QUIC concepts, the background tea, and how all of it gets used inside OpenSSL. It's gonna assume you already vibe with UDP/IP and sockets at a basic level. It also assumes you're already familiar with some OpenSSL and TLS fundamentals — so go peek at ossl-guide-libraries-introduction(7) and ossl-guide-tls-introduction(7) first if you haven't. no cap, it'll help. 🫶

🌈 WHAT IS QUIC? 🌈

QUIC is a general purpose protocol that lets applications communicate securely over a network. It's defined in RFC9000 (see <https://datatracker.ietf.org/doc/rfc9000/>). QUIC pulls in parts of the TLS protocol for connection establishment, but it protects packets independently. So it gives you similar security guarantees to TLS — confidentiality, integrity and authentication (peep ossl-guide-tls-introduction(7) for that).

QUIC delivers a bunch of advantages, and honestly? it's giving main character energy:

  • Multiple streams — It supports multiple streams of communication (see "QUIC STREAMS" below), so application protocols built on QUIC can create arbitrarily many bytestreams for a client and server to talk over. This lets an application protocol dodge that cursed situation where one packet of data is held up waiting on another packet to be delivered — commonly referred to as "head-of-line blocking". It also means an app can open additional logical streams without needing a round-trip exchange of packets between client and server, which is exactly what you'd have to do when opening an additional TLS/TCP connection. slay. ✨
  • HTTP/3 — Since QUIC is the basis of HTTP/3, having QUIC support also means applications can use HTTP/3 with a suitable third-party library.
  • Fast connection initiation — Future versions of OpenSSL will offer support for 0-RTT connection initiation, letting a connection be initiated to a server and application data be transmitted with zero waiting time. It's similar to TLS 1.3's 0-RTT functionality, but it also avoids the round trip needed to open a TCP socket — so like, it's basically a combination of TLS 1.3 0-RTT and TCP Fast Open. 🔥
  • Connection migration — Future versions of OpenSSL will offer support for connection migration, so connections can seamlessly survive IP address changes.
  • Datagram based use cases — Future versions of OpenSSL will offer support for the QUIC datagram extension, enabling both TLS and DTLS-style use cases on a single connection. 🎀
  • Implemented as application library — Because most QUIC implementations (including OpenSSL's) are implemented as an application library rather than by an operating system, an application can get all the QUIC benefits without waiting for an OS update to be deployed. Future evolutions and enhancements to the QUIC protocol can ship as fast as an application can be updated — no dependency on the OS update cadence. iconic.
  • Multiplexing over a single UDP socket — Because QUIC is UDP-based, you can multiplex a QUIC connection on the same UDP socket as some other UDP-based protocols, like RTP. 💜

⏰ QUIC TIME BASED EVENTS ⏰

okay so this is a key difference between the TLS implementation and the QUIC implementation in OpenSSL: 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. it does not care if you're busy, bestie.

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's 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 doesn't leave the QUIC connection idle and is regularly calling I/O functions doesn't typically need to worry about this. But — and this is the important part — if you're 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. That gives an application a simple way to satisfy the QUIC requirements for time based events without having to implement special logic to make it happen. queen behavior.

🧚 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. iykyk. 🌸

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 don't apply to QUIC at all, and others have altered semantics. You should refer to the documentation pages for each function for info on how it applies to QUIC. Typically, if QUIC isn't mentioned in the manual pages, then the functions apply to both TLS and QUIC. no guessing, just read the docs. 💖

🌊 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, with no loss of data and no 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. multiple streams, one connection. we love efficiency. 🦋

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. versatile icon. 👑

🔌 SOCKETS AND BLOCKING 🔌

TLS assumes "stream" type semantics for its underlying transport layer protocol (usually achieved by using TCP). But 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 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). 💀

⚠️ fr fr do not forget this one: the underlying socket for a QUIC application is always nonblocking, no matter what. the blocking vibes come from the SSL object, not the socket.

📚 FURTHER READING 📚

👀 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 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>.

🎀 and that's the whole page, bestie — this was OpenSSL 3.5.0, dated 2026-09-2, signing off with a lil sparkle. go build something iconic. 💖✨🦋

📦 where this page comes from