From a6de97b3a42389f7c052870b0730bb196cd72b58 Mon Sep 17 00:00:00 2001 From: Robert Lubos Date: Tue, 25 Sep 2018 11:46:58 +0200 Subject: [PATCH] samples: net: sockets: Update docs with TLS information Update documentation of socket samples that support TLS with information on how to enable it. Signed-off-by: Robert Lubos --- .../net/sockets/big_http_download/README.rst | 28 +++++++++++++++++ samples/net/sockets/echo_client/README.rst | 30 +++++++++++++++++-- samples/net/sockets/echo_server/README.rst | 29 ++++++++++++++++-- samples/net/sockets/http_get/README.rst | 25 ++++++++++++++++ 4 files changed, 108 insertions(+), 4 deletions(-) diff --git a/samples/net/sockets/big_http_download/README.rst b/samples/net/sockets/big_http_download/README.rst index 57dcaf3f9a5..29536edab66 100644 --- a/samples/net/sockets/big_http_download/README.rst +++ b/samples/net/sockets/big_http_download/README.rst @@ -67,6 +67,34 @@ setup is needed). on the Internet. Using files on archive.ubuntu.com is not recommended for large-scale testing. +Enabling TLS support +================================= + +Enable TLS support in the sample by building the project with the +``overlay-tls.conf`` overlay file enabled, for example, using these commands: + +.. zephyr-app-commands:: + :zephyr-app: samples/net/sockets/big_http_download + :board: qemu_x86 + :conf: "prj.conf overlay-tls.conf" + :goals: build + :compact: + +An alternative way is to specify ``-DOVERLAY_CONFIG=overlay-tls.conf`` when +running cmake. + +The TLS version of this sample downloads a file from +https://www.7-zip.org/a/7z1805.exe (1.1MB). The certificate +used by the sample is in the sample's ``src`` directory and is configured +to access the default website configured in the sample for TLS +communication (https://www.7-zip.org). To access a different +web page over TLS, you'll need to provide a different certificate +to authenticate to that server. + +Note, that TLS support in the sample depends on non-posix, TLS socket +functionality. Therefore, it is only posibly to run TLS in this sample +on Zephyr. + Running application on POSIX Host ================================= diff --git a/samples/net/sockets/echo_client/README.rst b/samples/net/sockets/echo_client/README.rst index e260afad2a7..7ca1beccaed 100644 --- a/samples/net/sockets/echo_client/README.rst +++ b/samples/net/sockets/echo_client/README.rst @@ -1,7 +1,7 @@ .. _sockets-echo-client-sample: -Echo Client -########### +Socket Echo Client +################## Overview ******** @@ -42,6 +42,28 @@ will need to consult its documentation for application deployment instructions. You can read about Zephyr support for specific boards in the documentation at :ref:`boards`. +Enabling TLS support +================================= + +Enable TLS support in the sample by building the project with the +``overlay-tls.conf`` overlay file enabled, for example, using these commands: + +.. zephyr-app-commands:: + :zephyr-app: samples/net/sockets/echo_client + :board: qemu_x86 + :conf: "prj.conf overlay-tls.conf" + :goals: build + :compact: + +An alternative way is to specify ``-DOVERLAY_CONFIG=overlay-tls.conf`` when +running cmake. + +The certificate and private key used by the sample can be found in the sample's +``src`` directory. The default certificates used by Socket Echo Client and +:ref:`sockets-echo-server-sample` enable establishing a secure connection +between the samples. + + Running echo-server in Linux Host ================================= @@ -68,6 +90,10 @@ Run echo-client application in QEMU: Note that echo-server must be running in the Linux host terminal window before you start the echo-client application in QEMU. +You can verify TLS communication with a Linux host as well. See +https://github.com/zephyrproject-rtos/net-tools documentation for information +on how to test TLS with Linux host samples. + See the :ref:`sockets-echo-server-sample` documentation for an alternate way of running, with the echo-client on the Linux host and the echo-server in QEMU. diff --git a/samples/net/sockets/echo_server/README.rst b/samples/net/sockets/echo_server/README.rst index c571a5abdd0..de9c3cc4594 100644 --- a/samples/net/sockets/echo_server/README.rst +++ b/samples/net/sockets/echo_server/README.rst @@ -1,7 +1,7 @@ .. _sockets-echo-server-sample: -Echo Server -########### +Socket Echo Server +################## Overview ******** @@ -43,6 +43,27 @@ will need to consult its documentation for application deployment instructions. You can read about Zephyr support for specific boards in the documentation at :ref:`boards`. +Enabling TLS support +================================= + +Enable TLS support in the sample by building the project with the +``overlay-tls.conf`` overlay file enabled, for example, using these commands: + +.. zephyr-app-commands:: + :zephyr-app: samples/net/sockets/echo_server + :board: qemu_x86 + :conf: "prj.conf overlay-tls.conf" + :goals: build + :compact: + +An alternative way is to specify ``-DOVERLAY_CONFIG=overlay-tls.conf`` when +running cmake. + +The certificate used by the sample can be found in the sample's ``src`` +directory. The default certificates used by Socket Echo Server and +:ref:`sockets-echo-client-sample` enable establishing a secure connection +between the samples. + Running echo-client in Linux Host ================================= @@ -69,6 +90,10 @@ In a terminal window: Note that echo-server must be running in QEMU before you start the echo-client application in host terminal window. +You can verify TLS communication with a Linux host as well. See +https://github.com/zephyrproject-rtos/net-tools documentation for information +on how to test TLS with Linux host samples. + See the :ref:`sockets-echo-client-sample` documentation for an alternate way of running, with the echo-server on the Linux host and the echo-client in QEMU. diff --git a/samples/net/sockets/http_get/README.rst b/samples/net/sockets/http_get/README.rst index b2aac13d536..f71ac28a2b0 100644 --- a/samples/net/sockets/http_get/README.rst +++ b/samples/net/sockets/http_get/README.rst @@ -45,6 +45,31 @@ and dumps the response. You can edit the source code to issue a request to any other site on the Internet (or on the local network, in which case no NAT/routing setup is needed). +Enabling TLS support +================================= + +Enable TLS support in the sample by building the project with the +``overlay-tls.conf`` overlay file enabled, for example, using these commands: + +.. zephyr-app-commands:: + :zephyr-app: samples/net/sockets/http_get + :board: qemu_x86 + :conf: "prj.conf overlay-tls.conf" + :goals: build + :compact: + +An alternative way is to specify ``-DOVERLAY_CONFIG=overlay-tls.conf`` when +running cmake. + +The certificate used by the sample can be found in the sample's ``src`` +directory. The certificate was selected to enable access to the default website +configured in the sample (https://google.com). To access a different web page +over TLS, provide an appropriate certificate to authenticate to that web server. + +Note, that TLS support in the sample depends on non-posix, TLS socket +functionality. Therefore, it is only posibly to run TLS in this sample +on Zephyr. + Running application on POSIX Host =================================