mirror of https://github.com/openssl/openssl
Add a separate README for the guide demos
Point users at the actual guide, and also explain about LD_LIBRARY_PATH 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:
parent
f666599f8d
commit
ada33e98f5
|
@ -7,11 +7,10 @@ client.
|
||||||
Users interested in using the new QUIC functionality are encouraged to look at
|
Users interested in using the new QUIC functionality are encouraged to look at
|
||||||
some of the following resources:
|
some of the following resources:
|
||||||
|
|
||||||
- The new [OpenSSL Guide], which provides introductory guides
|
- The new [OpenSSL Guide], which provides introductory guides on the use of TLS,
|
||||||
on the use of TLS, QUIC, and other OpenSSL functionality. See the
|
QUIC, and other OpenSSL functionality.
|
||||||
[ossl-guide-introduction(7) manual page] for the index.
|
|
||||||
- The [OpenSSL Guide] incorporates various code samples. The complete source
|
- The [OpenSSL Guide] incorporates various code samples. The complete source
|
||||||
for these can be [found in the source tree under `demos\guide`](./demos/guide/).
|
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
|
- 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
|
of QUIC functionality and how use of QUIC differs from use of TLS with regard
|
||||||
to our API.
|
to our API.
|
||||||
|
@ -33,9 +32,9 @@ QUIC delivers a number of advantages such as support for multiple streams of
|
||||||
communication; it is the basis for HTTP/3 [RFC 9114]; fast connection
|
communication; it is the basis for HTTP/3 [RFC 9114]; fast connection
|
||||||
initiation; and connection migration (enabling a connection to survive IP
|
initiation; and connection migration (enabling a connection to survive IP
|
||||||
address changes). For a more complete description of what QUIC is and its
|
address changes). For a more complete description of what QUIC is and its
|
||||||
advantages see the [QUIC Introduction] in the OpenSSL Guide.
|
advantages see the [QUIC Introduction] in the [OpenSSL Guide].
|
||||||
|
|
||||||
For a more comprehensive overview of OpenSSL's QUIC implementation, see the
|
For a comprehensive overview of OpenSSL's QUIC implementation, see the
|
||||||
[openssl-quic(7) manual page].
|
[openssl-quic(7) manual page].
|
||||||
|
|
||||||
### How can I use HTTP/3 with OpenSSL?
|
### How can I use HTTP/3 with OpenSSL?
|
||||||
|
@ -63,7 +62,7 @@ $ openssl s_client -quic -alpn myalpn -connect host:port
|
||||||
In the above example replace `host` with the hostname of the server (e.g.
|
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
|
`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
|
`myalpn` with the Application Layer Protocol to use (e.g.`h3` represents
|
||||||
HTTP/3). IANA matains a standard list of [ALPN ids] that can be used.
|
HTTP/3). IANA maintains a standard list of [ALPN ids] that can be used.
|
||||||
|
|
||||||
This example connects to a QUIC server and opens a single bidirectional stream.
|
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
|
Data can be passed via stdin/stdout as usual. This allows test usage of QUIC
|
||||||
|
@ -72,11 +71,10 @@ 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.
|
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-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
|
[OpenSSL Guide]: https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html
|
||||||
[DDD]: https://github.com/openssl/openssl/tree/master/doc/designs/ddd
|
[DDD]: https://github.com/openssl/openssl/tree/master/doc/designs/ddd
|
||||||
[found in the source tree under `doc/designs/ddd`]: ./doc/designs/ddd/
|
[found in the source tree under `doc/designs/ddd`]: ./doc/designs/ddd/
|
||||||
[demo found in `demos/http3`]: ./demos/http3/
|
[demo found in `demos/http3`]: ./demos/http3/
|
||||||
[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
|
||||||
[QUIC Introduction](https://www.openssl.org/docs/manmaster/man7/ossl-guide-quic-introduction.html)
|
|
||||||
[RFC 9114]: https://tools.ietf.org/html/rfc9114
|
[RFC 9114]: https://tools.ietf.org/html/rfc9114
|
||||||
[ALPN ids]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
|
[ALPN ids]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
|
||||||
|
|
|
@ -7,7 +7,8 @@ Welcome to the OpenSSL Project
|
||||||
[![appveyor badge]][appveyor jobs]
|
[![appveyor badge]][appveyor jobs]
|
||||||
|
|
||||||
OpenSSL is a robust, commercial-grade, full-featured Open Source Toolkit
|
OpenSSL is a robust, commercial-grade, full-featured Open Source Toolkit
|
||||||
for the TLS (formerly SSL), DTLS and QUIC (client side only) protocols.
|
for the TLS (formerly SSL), DTLS and QUIC (currently client side only)
|
||||||
|
protocols.
|
||||||
|
|
||||||
The protocol implementations are based on a full-strength general purpose
|
The protocol implementations are based on a full-strength general purpose
|
||||||
cryptographic library, which can also be used stand-alone. Also included is a
|
cryptographic library, which can also be used stand-alone. Also included is a
|
||||||
|
@ -38,7 +39,7 @@ The OpenSSL toolkit includes:
|
||||||
- **libssl**
|
- **libssl**
|
||||||
an implementation of all TLS protocol versions up to TLSv1.3 ([RFC 8446]),
|
an implementation of all TLS protocol versions up to TLSv1.3 ([RFC 8446]),
|
||||||
DTLS protocol versions up to DTLSv1.2 ([RFC 6347]) and
|
DTLS protocol versions up to DTLSv1.2 ([RFC 6347]) and
|
||||||
the QUIC (client side only) version 1 protocol ([RFC 9000]).
|
the QUIC (currently client side only) version 1 protocol ([RFC 9000]).
|
||||||
|
|
||||||
- **libcrypto**
|
- **libcrypto**
|
||||||
a full-strength general purpose cryptographic library. It constitutes the
|
a full-strength general purpose cryptographic library. It constitutes the
|
||||||
|
@ -239,11 +240,11 @@ All rights reserved.
|
||||||
<https://tools.ietf.org/html/rfc9000>
|
<https://tools.ietf.org/html/rfc9000>
|
||||||
|
|
||||||
[Binaries]:
|
[Binaries]:
|
||||||
https://wiki.openssl.org/index.php/Binaries
|
<https://wiki.openssl.org/index.php/Binaries>
|
||||||
"List of third party OpenSSL binaries"
|
"List of third party OpenSSL binaries"
|
||||||
|
|
||||||
[OpenSSL Guide]:
|
[OpenSSL Guide]:
|
||||||
https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html
|
<https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html>
|
||||||
"An introduction to OpenSSL"
|
"An introduction to OpenSSL"
|
||||||
|
|
||||||
<!-- Logos and Badges -->
|
<!-- Logos and Badges -->
|
||||||
|
|
|
@ -0,0 +1,15 @@
|
||||||
|
The OpenSSL Guide Demos
|
||||||
|
=======================
|
||||||
|
|
||||||
|
The demos in this directory are the complete source code for the applications
|
||||||
|
developed in the OpenSSL Guide tutorials. Refer to the various tutorial pages in
|
||||||
|
the [guide] for an extensive discussion on the demos available here.
|
||||||
|
|
||||||
|
To run the demos when linked with a shared library (default) ensure that
|
||||||
|
libcrypto and libssl are on the library path. For example, assuming you have
|
||||||
|
already built OpenSSL from this source and in the default location then to run
|
||||||
|
the tls-client-block demo do this:
|
||||||
|
|
||||||
|
LD_LIBRARY_PATH=../.. ./tls-client-block
|
||||||
|
|
||||||
|
[guide]: https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html
|
Loading…
Reference in New Issue