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)

diff --git a/README-QUIC.md b/README-QUIC.md
index 3c5720e90bbe868a38b9bd2ab34315327dd69838..554fe9bc2b8a3eaca38c17e84f9c452b8d266602 100644 (file)
--- a/README-QUIC.md
+++ b/README-QUIC.md
@@ -7,11 +7,10 @@ client.
 Users interested in using the new QUIC functionality are encouraged to look at
 some of the following resources:
 
-- 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] for the index.
+- The new [OpenSSL Guide], which provides introductory guides on the use of TLS,
+  QUIC, and other OpenSSL functionality.
 - 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
   of QUIC functionality and how use of QUIC differs from use of TLS with regard
   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
 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.
+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].
 
 ### 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.
 `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). 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.
 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.
 
 [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
 [found in the source tree under `doc/designs/ddd`]: ./doc/designs/ddd/
 [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
-[ALPN ids]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
\ No newline at end of file
+[ALPN ids]: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

diff --git a/README.md b/README.md
index 8780935dc45345fa9a4727ce25138eb6b6833983..aa1a233ab112c540576deb95304e1641785703fd 100644 (file)
--- a/README.md
+++ b/README.md
@@ -7,7 +7,8 @@ Welcome to the OpenSSL Project
 [![appveyor badge]][appveyor jobs]
 
 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
 cryptographic library, which can also be used stand-alone. Also included is a
@@ -38,7 +39,7 @@ The OpenSSL toolkit includes:
 - **libssl**
   an implementation of all TLS protocol versions up to TLSv1.3 ([RFC 8446]),
   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**
   a full-strength general purpose cryptographic library. It constitutes the
@@ -239,11 +240,11 @@ All rights reserved.
      <https://tools.ietf.org/html/rfc9000>
 
 [Binaries]:
-    https://wiki.openssl.org/index.php/Binaries
+    <https://wiki.openssl.org/index.php/Binaries>
     "List of third party OpenSSL binaries"
 
 [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"
 
 <!-- Logos and Badges -->

diff --git a/demos/guide/README.md b/demos/guide/README.md
new file mode 100644 (file)
index 0000000..f1cbf1e
--- /dev/null
+++ b/demos/guide/README.md
@@ -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