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