README.md
1The OpenSSL Guide Demos
2=======================
3
4The demos in this directory are the complete source code for the applications
5developed in the OpenSSL Guide tutorials. Refer to the various tutorial pages in
6the [guide] for an extensive discussion on the demos available here.
7
8They must be built before they can be run. An example UNIX style Makefile is
9supplied. Just type "make" from this directory on a Linux/UNIX system.
10
11Running the TLS Demos
12---------------------
13
14To run the demos when linked with a shared library (default) ensure that
15libcrypto and libssl are on the library path. For example, assuming you have
16already built OpenSSL from this source and in the default location then to run
17the tls-client-block demo do this:
18
19LD_LIBRARY_PATH=../.. ./tls-client-block hostname port
20
21In the above replace "hostname" and "port" with the hostname and the port number
22of the server you are connecting to.
23
24The above assumes that your default trusted certificate store containing trusted
25CA certificates has been properly setup and configured as described on the
26[TLS Introduction] page.
27
28You can run a test server to try out these demos using the "openssl s_server"
29command line utility and using the test server certificate and key provided in
30this directory. For example:
31
32LD_LIBRARY_PATH=../.. ../../apps/openssl s_server -www -accept localhost:4443 -cert servercert.pem -key serverkey.pem
33
34The test server certificate in this directory will use a CA that will not be in
35your default trusted certificate store. The CA certificate to use is also
36available in this directory. To use it you can override the default trusted
37certificate store like this:
38
39SSL_CERT_FILE=rootcert.pem LD_LIBRARY_PATH=../.. ./tls-client-block localhost 4443
40
41If the above command is successful it will connect to the test "s_server" and
42send a simple HTTP request to it. The server will respond with a page of
43information giving details about the TLS connection that was used.
44
45Note that the test server certificate used here is only suitable for use on
46"localhost".
47
48The tls-client-non-block demo can be run in exactly the same way. Just replace
49"tls-client-block" in the above example commands with "tls-client-non-block".
50
51Running the QUIC Demos
52----------------------
53
54The QUIC demos can be run in a very similar way to the TLS demos. However, a
55different server implementation will need to be used.
56
57The OpenSSL source distribution includes a test QUIC server implementation for
58use with the demos. Note that, although this server does get built when building
59OpenSSL from source, it does not get installed via "make install". After
60building OpenSSL from source you will find the "quicserver" utility in the
61"util" sub-directory of the top of the build tree. This server utility is not
62suitable for production use and exists for test purposes only. It will be
63removed from a future version of OpenSSL.
64
65While in the demos directory the quic server can be run like this:
66
67./../util/quicserver localhost 4443 servercert.pem serverkey.pem
68
69The QUIC demos can then be run in the same was as the TLS demos. For example
70to run the quic-client-block demo:
71
72SSL_CERT_FILE=rootcert.pem LD_LIBRARY_PATH=../.. ./quic-client-block localhost 4443
73
74Notes on the quic-hq-interop demo
75---------------------------------
76
77The quic-hq-interop demo is effectively the same as the quic-client-nonblock
78demo, but is specifically constructed to use the hq-interop alpn for the
79purposes of interacting with other demonstration containers found in the
80QUIC working group [interop runner](https://github.com/quic-interop/quic-interop-runner)
81It is run as follows:
82
83SSL_CERT_FILE=ca.pem LD_LIBRARY_PATH=../../ ./quic-hq-interop host port file
84
85The demo will then do the following:
86
871. Connect to the server at host/port
882. Negotiates the hq-interop alpn
893. Issues an HTTP 1.0 GET request of the form "GET /$FILE"
903. Reads any response from the server and write it verbatim to stdout
91
92This demo can be used for any hq-interop negotiating server, but its use can
93most easily be seen in action in our quic interop container, buildable from
94./test/quic_interop_openssl in this source tree.
95
96<!-- Links -->
97
98[guide]: https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html
99[TLS Introduction]: https://www.openssl.org/docs/manmaster/man7/ossl-guide-tls-introduction.html
100
