From 3eda52f6cda9162e21d67a16c67f10943b1a4222 Mon Sep 17 00:00:00 2001 From: David Cermak Date: Wed, 12 Jun 2019 14:55:58 +0200 Subject: [PATCH] mqtt: update example documentation on generating a certificate for ssl authentication to hosts Closes https://github.com/espressif/esp-idf/issues/3593 --- examples/protocols/mqtt/ssl/README.md | 9 +++++++-- examples/protocols/mqtt/ssl_mutual_auth/README.md | 1 + examples/protocols/mqtt/tcp/README.md | 2 ++ examples/protocols/mqtt/ws/README.md | 1 + examples/protocols/mqtt/wss/README.md | 8 +++++++- 5 files changed, 18 insertions(+), 3 deletions(-) diff --git a/examples/protocols/mqtt/ssl/README.md b/examples/protocols/mqtt/ssl/README.md index 5925c4001..db711fdcf 100644 --- a/examples/protocols/mqtt/ssl/README.md +++ b/examples/protocols/mqtt/ssl/README.md @@ -3,6 +3,7 @@ (See the README.md file in the upper level 'examples' directory for more information about examples.) This example connects to the broker iot.eclipse.org using ssl transport and as a demonstration subscribes/unsubscribes and send a message on certain topic. +(Please note that the public broker is maintained by the community so may not be always available, for details please see this [disclaimer](https://iot.eclipse.org/getting-started/#sandboxes)) It uses ESP-MQTT library which implements mqtt client to connect to mqtt broker. @@ -18,10 +19,14 @@ This example can be executed on any ESP32 board, the only required interface is * Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details. * When using Make build system, set `Default serial port` under `Serial flasher config`. -Note how to create a PEM certificate for iot.eclipse.org: +PEM certificate for this example could be extracted from an openssl `s_client` command connecting to iot.eclipse.org. +In case a host operating system has `openssl` and `sed` packages installed, one could execute the following command to download and save the root certificate to a file (Note for Windows users: Both Linux like environment or Windows native packages may be used). ``` -openssl s_client -showcerts -connect iot.eclipse.org:8883 /dev/null|openssl x509 -outform PEM >iot_eclipse_org.pem +echo "" | openssl s_client -showcerts -connect iot.eclipse.org:8883 | sed -n "1,/Root/d; /BEGIN/,/END/p" | openssl x509 -outform PEM >iot_eclipse_org.pem ``` +Please note that this is not a general command for downloading a root certificate for an arbitrary host; +this command works with iot.eclipse.org as the site provides root certificate in the chain, which then could be extracted +with text operation. ### Build and Flash diff --git a/examples/protocols/mqtt/ssl_mutual_auth/README.md b/examples/protocols/mqtt/ssl_mutual_auth/README.md index 9b20b37ca..bf5b57d70 100644 --- a/examples/protocols/mqtt/ssl_mutual_auth/README.md +++ b/examples/protocols/mqtt/ssl_mutual_auth/README.md @@ -3,6 +3,7 @@ (See the README.md file in the upper level 'examples' directory for more information about examples.) This example connects to the broker test.mosquitto.org using ssl transport with client certificate and as a demonstration subscribes/unsubscribes and send a message on certain topic. +(Please note that the public broker is maintained by the community so may not be always available, for details please visit http://test.mosquitto.org) It uses ESP-MQTT library which implements mqtt client to connect to mqtt broker. diff --git a/examples/protocols/mqtt/tcp/README.md b/examples/protocols/mqtt/tcp/README.md index 7247a7a22..7920a75e9 100644 --- a/examples/protocols/mqtt/tcp/README.md +++ b/examples/protocols/mqtt/tcp/README.md @@ -2,6 +2,8 @@ (See the README.md file in the upper level 'examples' directory for more information about examples.) This example connects to the broker URI selected using `make menuconfig` (using mqtt tcp transport) and as a demonstration subscribes/unsubscribes and send a message on certain topic. +(Please note that the public broker is maintained by the community so may not be always available, for details please see this [disclaimer](https://iot.eclipse.org/getting-started/#sandboxes)) + Note: If the URI equals `FROM_STDIN` then the broker address is read from stdin upon application startup (used for testing) It uses ESP-MQTT library which implements mqtt client to connect to mqtt broker. diff --git a/examples/protocols/mqtt/ws/README.md b/examples/protocols/mqtt/ws/README.md index 236521f90..d0eff6be2 100644 --- a/examples/protocols/mqtt/ws/README.md +++ b/examples/protocols/mqtt/ws/README.md @@ -3,6 +3,7 @@ (See the README.md file in the upper level 'examples' directory for more information about examples.) This example connects to the broker iot.eclipse.org over web sockets as a demonstration subscribes/unsubscribes and send a message on certain topic. +(Please note that the public broker is maintained by the community so may not be always available, for details please see this [disclaimer](https://iot.eclipse.org/getting-started/#sandboxes)) It uses ESP-MQTT library which implements mqtt client to connect to mqtt broker. diff --git a/examples/protocols/mqtt/wss/README.md b/examples/protocols/mqtt/wss/README.md index 453d52f70..187797930 100644 --- a/examples/protocols/mqtt/wss/README.md +++ b/examples/protocols/mqtt/wss/README.md @@ -2,6 +2,7 @@ (See the README.md file in the upper level 'examples' directory for more information about examples.) This example connects to the broker iot.eclipse.org over secure websockets and as a demonstration subscribes/unsubscribes and send a message on certain topic. +(Please note that the public broker is maintained by the community so may not be always available, for details please see this [disclaimer](https://iot.eclipse.org/getting-started/#sandboxes)) It uses ESP-MQTT library which implements mqtt client to connect to mqtt broker. @@ -19,9 +20,14 @@ This example can be executed on any ESP32 board, the only required interface is Note how to create a PEM certificate for iot.eclipse.org: +PEM certificate for this example could be extracted from an openssl `s_client` command connecting to iot.eclipse.org. +In case a host operating system has `openssl` and `sed` packages installed, one could execute the following command to download and save the root certificate to a file (Note for Windows users: Both Linux like environment or Windows native packages may be used). ``` -openssl s_client -showcerts -connect iot.eclipse.org:8883 /dev/null|openssl x509 -outform PEM >iot_eclipse_org.pem +echo "" | openssl s_client -showcerts -connect iot.eclipse.org:443 | sed -n "1,/Root/d; /BEGIN/,/END/p" | openssl x509 -outform PEM >iot_eclipse_org.pem ``` +Please note that this is not a general command for downloading a root certificate for an arbitrary host; +this command works with iot.eclipse.org as the site provides root certificate in the chain, which then could be extracted +with text operation. ### Build and Flash