Update README-QUIC.md

We move some of the "why QUIC" content into the guide and just provide a
summary in README-QUIC.md.

We also clarify how to use s_client with QUIC.

Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22505)

1 files changed, 28 insertions, 46 deletions

diff --git a/README-QUIC.md b/README-QUIC.md
index 02708eda2c..11cf8fafdc 100644
--- a/README-QUIC.md
+++ b/README-QUIC.md
@@ -7,12 +7,14 @@ 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.
+  [ossl-guide-introduction(7) manual page] for the index.
+- The [OpenSSL Guide] incorporates various code samples. The complete source
+  for these can be [found in the source tree under `demos\guide`](./demos/guide/).
+- 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 [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`].
@@ -25,43 +27,15 @@ 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
+serve many of the use cases of SSL/TLS as well as those of DTLS.
+
+QUIC delivers a number of advantages such as support for multiple streams of
+communication; it is the basis for HTTP/3; fast connection initiation; and
+connection migration (enabling a connection to survive IP address changes).
+For a more complete description of what QUIC is and its advantages see the
+[QUIC Introduction] in the OpenSSL Guide.
+
+For a more comprehensive overview of OpenSSL's QUIC implementation, see the
 [openssl-quic(7) manual page].
 
 ### How can I use HTTP/3 with OpenSSL?
@@ -83,16 +57,24 @@ an existing application.
 There is basic support for single-stream QUIC using `openssl s_client`:
 
 ```shell
-$ openssl s_client -quic -alpn ossltest -connect www.example.com:12345
+$ openssl s_client -quic -alpn myalpn -connect host:port
 ```
 
-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.
+In the above example replace `host` with the hostname of the server (e.g.
+`www.example.com`) and `port` with the port for the server (e.g. `443`). Replace
+`myalpn` with the Application Layer Protocol to use (e.g.`h3` represents
+HTTP/3).
+
+This example connects to a QUIC server 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. Note that OpenSSL has no direct support for
+HTTP/3 so connecting to an HTTP/3 server should be possible but sending an
+HTTP/3 request or receiving any response data is not.
 
 [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
+[openssl-quic(7) manual page]: https://www.openssl.org/docs/manmaster/man7/openssl-quic.html
+[QUIC Introduction](https://www.openssl.org/docs/manmaster/man7/ossl-guide-quic-introduction.html)