openssl/README-QUIC.md

Using OpenSSL with QUIC

From OpenSSL 3.2, OpenSSL features support for making QUIC connections as a client. Starting with OpenSSL 3.5, server-side QUIC support has also been added.

Users interested in using the new QUIC functionality are encouraged to look at some of the following resources:

• The new OpenSSL Guide, which provides introductory guides on the use of TLS, QUIC, and other OpenSSL functionality.
• The OpenSSL Guide incorporates various code samples. The complete source for these can be found in the source tree under demos/guide.
• The openssl-quic(7) manual page, which provides a basic reference overview of QUIC functionality and how the use of QUIC differs from the use of TLS with regard to our API.
• The Demo-Driven Design (DDD) demos, which demonstrate the use of QUIC using simple examples. These can be found in the source tree under doc/designs/ddd.
• The demo found in demos/http3, which provides an HTTP/3 client example using the nghttp3 HTTP/3 library.

FAQ

Why would I want to use QUIC, and what functionality does QUIC offer relative to TLS or DTLS?

QUIC is a state-of-the-art secure transport protocol carried over UDP. It can serve many of the use cases of SSL/TLS as well as those of DTLS.

QUIC delivers a number of advantages such as support for multiple streams of communication; it is the basis for HTTP/3 RFC 9114; fast connection initiation; and connection migration (enabling a connection to survive IP address changes). For a more complete description of what QUIC is and its advantages see the QUIC Introduction in the OpenSSL Guide.

For a comprehensive overview of OpenSSL's QUIC implementation, see the openssl-quic(7) manual page.

How can I use HTTP/3 with OpenSSL?

There are many HTTP/3 implementations in C available. The use of one such HTTP/3 library with OpenSSL QUIC is demonstrated via the demo found in demos/http3.

How can I use OpenSSL QUIC in my own application for a different protocol?

The OpenSSL Guide provides introductory examples for how to make use of OpenSSL QUIC.

The openssl-quic(7) manual page and the Demo-Driven Design (DDD) demos may also be helpful to illustrate the changes needed if you are trying to adapt an existing application.

How can I test QUIC using openssl s_client?

There is basic support for single-stream QUIC using openssl s_client:

$ openssl s_client -quic -alpn myalpn -connect host:port

In the above example replace host with the hostname of the server (e.g. www.example.com) and port with the port for the server (e.g. 443). Replace myalpn with the Application Layer Protocol to use (e.g. h3 represents HTTP/3). IANA maintains a standard list of ALPN ids that can be used.

This example connects to a QUIC server and opens a single bidirectional stream. Data can be passed via stdin/stdout as usual. This allows test usage of QUIC using simple TCP/TLS-like usage. Note that OpenSSL has no direct support for HTTP/3 so connecting to an HTTP/3 server should be possible but sending an HTTP/3 request or receiving any response data is not.

How can I create a QUIC server with OpenSSL?

Starting with OpenSSL 3.5, you can create a QUIC server. OpenSSL provides a server implementation example that you can use as a reference:

The example QUIC server implementation can be found in the source tree under demos/quic/server. This demonstrates how to implement a basic QUIC server using the OpenSSL API.

To run the example QUIC server:

$ ./demos/quic/server/server <port-number> <certificate-file> <key-file>

For example:

$ ./demos/quic/server/server 4433 server.pem server.key

Replace server.pem and server.key with your certificate and private key files. Note that the standard openssl s_server command does NOT support QUIC - you must use this dedicated server example instead.

For more information about implementing QUIC servers with OpenSSL, refer to the OpenSSL Guide and the openssl-quic(7) manual page.