]>
Commit | Line | Data |
---|---|---|
514430c3 HL |
1 | Using OpenSSL with QUIC |
2 | ======================= | |
3 | ||
4 | From OpenSSL 3.2, OpenSSL features support for making QUIC connections as a | |
5 | client. | |
6 | ||
7 | Users interested in using the new QUIC functionality are encouraged to look at | |
8 | some of the following resources: | |
9 | ||
ada33e98 MC |
10 | - The new [OpenSSL Guide], which provides introductory guides on the use of TLS, |
11 | QUIC, and other OpenSSL functionality. | |
355fd1f4 | 12 | - The [OpenSSL Guide] incorporates various code samples. The complete source |
ada33e98 | 13 | for these can be [found in the source tree under `demos/guide`](./demos/guide/). |
355fd1f4 MC |
14 | - The [openssl-quic(7) manual page], which provides a basic reference overview |
15 | of QUIC functionality and how use of QUIC differs from use of TLS with regard | |
16 | to our API. | |
514430c3 HL |
17 | - The [Demo-Driven Design (DDD)][DDD] demos, which demonstrate the use of QUIC |
18 | using simple examples. These can be [found in the source tree under | |
19 | `doc/designs/ddd`]. | |
20 | - The [demo found in `demos/http3`], which provides an HTTP/3 client example | |
21 | using the nghttp3 HTTP/3 library. | |
22 | ||
23 | FAQ | |
24 | --- | |
25 | ||
26 | ### Why would I want to use QUIC, and what functionality does QUIC offer relative to TLS or DTLS? | |
27 | ||
28 | QUIC is a state-of-the-art secure transport protocol carried over UDP. It can | |
355fd1f4 MC |
29 | serve many of the use cases of SSL/TLS as well as those of DTLS. |
30 | ||
31 | QUIC delivers a number of advantages such as support for multiple streams of | |
f666599f MC |
32 | communication; it is the basis for HTTP/3 [RFC 9114]; fast connection |
33 | initiation; and connection migration (enabling a connection to survive IP | |
34 | address changes). For a more complete description of what QUIC is and its | |
ada33e98 | 35 | advantages see the [QUIC Introduction] in the [OpenSSL Guide]. |
355fd1f4 | 36 | |
ada33e98 | 37 | For a comprehensive overview of OpenSSL's QUIC implementation, see the |
514430c3 HL |
38 | [openssl-quic(7) manual page]. |
39 | ||
40 | ### How can I use HTTP/3 with OpenSSL? | |
41 | ||
42 | There are many HTTP/3 implementations in C available. The use of one such HTTP/3 | |
43 | library with OpenSSL QUIC is demonstrated via the [demo found in `demos/http3`]. | |
44 | ||
45 | ### How can I use OpenSSL QUIC in my own application for a different protocol? | |
46 | ||
47 | The [OpenSSL Guide] provides introductory examples for how to make use of | |
48 | OpenSSL QUIC. | |
49 | ||
50 | The [openssl-quic(7) manual page] and the [Demo-Driven Design (DDD)][DDD] demos | |
51 | may also be helpful to illustrate the changes needed if you are trying to adapt | |
52 | an existing application. | |
53 | ||
54 | ### How can I test QUIC using `openssl s_client`? | |
55 | ||
56 | There is basic support for single-stream QUIC using `openssl s_client`: | |
57 | ||
58 | ```shell | |
355fd1f4 | 59 | $ openssl s_client -quic -alpn myalpn -connect host:port |
514430c3 HL |
60 | ``` |
61 | ||
355fd1f4 MC |
62 | In the above example replace `host` with the hostname of the server (e.g. |
63 | `www.example.com`) and `port` with the port for the server (e.g. `443`). Replace | |
64 | `myalpn` with the Application Layer Protocol to use (e.g.`h3` represents | |
ada33e98 | 65 | HTTP/3). IANA maintains a standard list of [ALPN ids] that can be used. |
355fd1f4 MC |
66 | |
67 | This example connects to a QUIC server and opens a single bidirectional stream. | |
68 | Data can be passed via stdin/stdout as usual. This allows test usage of QUIC | |
69 | using simple TCP/TLS-like usage. Note that OpenSSL has no direct support for | |
70 | HTTP/3 so connecting to an HTTP/3 server should be possible but sending an | |
71 | HTTP/3 request or receiving any response data is not. | |
514430c3 HL |
72 | |
73 | [openssl-quic(7) manual page]: https://www.openssl.org/docs/manmaster/man7/openssl-quic.html | |
ada33e98 | 74 | [OpenSSL Guide]: https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html |
514430c3 HL |
75 | [DDD]: https://github.com/openssl/openssl/tree/master/doc/designs/ddd |
76 | [found in the source tree under `doc/designs/ddd`]: ./doc/designs/ddd/ | |
77 | [demo found in `demos/http3`]: ./demos/http3/ | |
ada33e98 | 78 | [QUIC Introduction]: https://www.openssl.org/docs/manmaster/man7/ossl-guide-quic-introduction.html |
f666599f | 79 | [RFC 9114]: https://tools.ietf.org/html/rfc9114 |
ada33e98 | 80 | [ALPN ids]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids |