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`].
### 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?
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)
L<https://datatracker.ietf.org/doc/rfc9000/>). QUIC integrates parts of the
TLS protocol for connection establishment but independently protects packets.
It provides similar security guarantees to TLS such as confidentiality,
-integrity and authentication (see L<ossl-guide-tls-introduction(7)>). It
-additionally provides multiplexing capabilities through the use of "streams"
-(see L</QUIC STREAMS> below).
+integrity and authentication (see L<ossl-guide-tls-introduction(7)>).
+
+QUIC delivers a number of advantages:
+
+=over 4
+
+=item Multiple streams
+
+It supports multiple streams of communication (see L</QUIC STREAMS> below),
+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 problems where one packet of data is held up
+waiting on another packet being delivered (commonly referred to as
+"head-of-line blocking"). It also enables an application to open additional
+logical streams without requiring a round-trip exchange of packets between the
+client and server as is required when opening an additional TLS/TCP
+connection.
+
+=item HTTP/3
+
+Since QUIC is the basis of HTTP/3, support for QUIC also enables applications
+to use HTTP/3 using a suitable third-party library.
+
+=item Fast connection initiation
+
+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.
+
+=item Connection migration
+
+Future versions of OpenSSL will offer support for connection migration, allowing
+connections to seamlessly survive IP address changes.
+
+=item Datagram based use cases
+
+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.
+
+=item Implemented as application library
+
+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.
+
+=item Multiplexing over a single UDP socket
+
+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.
+
+=back
=head1 QUIC TIME BASED EVENTS
projects / openssl.git / commitdiff