mirror of
https://github.com/openssl/openssl.git
synced 2025-01-18 13:44:20 +08:00
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)
This commit is contained in:
Matt Caswell
Hugo Landau
parent
0181a1a49c
commit
355fd1f45b
@ -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:
|
||||
serve many of the use cases of SSL/TLS as well as those of DTLS.
|
||||
|
||||
- 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.
|
||||
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.
|
||||
|
||||
- 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
|
||||
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)
|
||||
|
||||
@ -20,9 +20,62 @@ communicate over a network. It is defined in RFC9000 (see
|
||||
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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user