diff options
Diffstat (limited to 'README-QUIC.md')
| -rw-r--r-- | README-QUIC.md | 74 |
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) |