mqtt: update example documentation on generating a certificate for ssl authentication...

Closes https://github.com/espressif/esp-idf/issues/3593

diff --git a/examples/protocols/mqtt/ssl/README.md b/examples/protocols/mqtt/ssl/README.md
index 5925c4001eec7d7e1dbc90b990e6fff6cc4865f2..db711fdcf1921627fbd0a131af5d5d182040c44b 100644 (file)
--- 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 2>/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 9b20b37cad34b224078bd8d4a2cdf328d91a5647..bf5b57d70496baf856395c0b5fda30b00b68fa38 100644 (file)
--- 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 7247a7a228141a01b1f129cfc6d62d969fce04f5..7920a75e9ef5be2528d86bb0b127192eef6e39be 100644 (file)
--- 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 236521f90ee71169276dbb6adad54431c5febc27..d0eff6be296f62cce9a7ac2ccf4f47d58622496e 100644 (file)
--- 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 453d52f70f384919297a1672c3b7c653271ef1b6..1877979308259b13ff0685107b4ac4158c86bcdd 100644 (file)
--- 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 2>/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