README-QUIC.md

   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
  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
  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
  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
  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
  35 advantages see the [QUIC Introduction] in the [OpenSSL Guide].
  36
  37 For 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
  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
  59 $ openssl s_client -quic -alpn myalpn -connect host:port
  60 ```
  61
  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
  65 HTTP/3). IANA maintains a standard list of [ALPN ids] that can be used.
  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.
  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