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