Add QUIC README file

1 files changed, 98 insertions, 0 deletions

diff --git a/README-QUIC.md b/README-QUIC.md
new file mode 100644
index 0000000000..02708eda2c
--- /dev/null
+++ b/README-QUIC.md
@@ -0,0 +1,98 @@
+Using OpenSSL with QUIC
+=======================
+
+From OpenSSL 3.2, OpenSSL features support for making QUIC connections as a
+client.
+
+Users interested in using the new QUIC functionality are encouraged to look at
+some of the following resources:
+
+- The [openssl-quic(7) manual page], which provides a basic reference overview
+  of QUIC functionality and how use of QUIC differs from use of TLS with regard
+  to our API;
+- The new [OpenSSL Guide], which provides introductory guides
+  on the use of TLS, QUIC, and other OpenSSL functionality. See the
+  [ossl-guide-introduction(7) manual page][OpenSSL Guide] for the index.
+- The [Demo-Driven Design (DDD)][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 TLS as well as those of DTLS. QUIC delivers
+a number of advantages:
+
+- It supports multiple streams of communication, allowing application protocols
+  built on QUIC to create arbitrarily many bytestreams for communication between
+  a client and server. This allows an application protocol to avoid head-of-line
+  blocking and allows an application to open additional logical streams without
+  any round trip penalty, unlike opening an additional TCP connection.
+
+- Since QUIC is the basis of HTTP/3, support for QUIC also enables applications
+  to use HTTP/3 using a suitable third-party library.
+
+- Future versions of OpenSSL will offer support for 0-RTT connection
+  initiation, allowing a connection to be initiated to a server and application
+  data to be transmitted without any waiting time. This is similar to TLS 1.3's
+  0-RTT functionality but also avoids the round trip needed to open a TCP
+  socket; thus, it is similar to a combination of TLS 1.3 0-RTT and TCP Fast
+  Open.
+
+- Future versions of OpenSSL will offer support for connection
+  migration, allowing connections to seamlessly survive IP address changes.
+
+- Future versions of OpenSSL will offer support for the QUIC
+  datagram extension, allowing support for both TLS and DTLS-style use cases on
+  a single connection.
+
+- Because most QUIC implementations, including OpenSSL's implementation, are
+  implemented as an application library rather than by an operating system, an
+  application can gain the benefit of QUIC without needing to wait for an OS
+  update to be deployed. Future evolutions and enhancements to the QUIC protocol
+  can be delivered as quickly as an application can be updated without
+  dependency on an OS update cadence.
+
+- Because QUIC is UDP-based, it is possible to multiplex a QUIC connection
+  on the same UDP socket as some other UDP-based protocols, such as RTP.
+
+For more background information on 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)][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`:
+
+```shell
+$ openssl s_client -quic -alpn ossltest -connect www.example.com:12345
+```
+
+This connects to a QUIC server using the specified ALPN protocol name 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.
+
+[openssl-quic(7) manual page]: https://www.openssl.org/docs/manmaster/man7/openssl-quic.html
+[OpenSSL guide]: https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html
+[DDD]: https://github.com/openssl/openssl/tree/master/doc/designs/ddd
+[found in the source tree under `doc/designs/ddd`]: ./doc/designs/ddd/
+[demo found in `demos/http3`]: ./demos/http3/
+[openssl-quic-background(7) manual page]: https://www.openssl.org/docs/manmaster/man7/openssl-quic-background.html