From f31d10ae0fe02511796092cf1b44fe5306e9376f Mon Sep 17 00:00:00 2001 From: Oscar Michael Abrina Date: Thu, 22 Oct 2020 19:06:19 -0700 Subject: [PATCH] Add instructions for MQTT broker setup on Windows for coreMQTT demos (#360) This adds instructions for setting up a local Mosquitto broker on Windows for use with the coreMQTT demos. There are different instructions for mutual auth, server auth, and plaintext. --- .../MQTT_Basic_TLS/demo_config.h | 12 +-- .../MQTT_Basic_TLS/mqtt_broker_setup.txt | 59 ++++++++++++++ .../MQTT_Keep_Alive/demo_config.h | 34 +-------- .../MQTT_Keep_Alive/mqtt_broker_setup.txt | 31 ++++++++ .../MQTT_Multitask/demo_config.h | 3 + .../MQTT_Multitask/mqtt_broker_setup.txt | 76 +++++++++++++++++++ .../MQTT_Mutual_Auth/demo_config.h | 3 + .../MQTT_Mutual_Auth/mqtt_broker_setup.txt | 76 +++++++++++++++++++ .../MQTT_Plain_Text/demo_config.h | 34 +-------- .../MQTT_Plain_Text/mqtt_broker_setup.txt | 31 ++++++++ .../MQTT_Serializer/demo_config.h | 34 +-------- .../MQTT_Serializer/mqtt_broker_setup.txt | 31 ++++++++ 12 files changed, 318 insertions(+), 106 deletions(-) create mode 100644 FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/mqtt_broker_setup.txt create mode 100644 FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/mqtt_broker_setup.txt create mode 100644 FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/mqtt_broker_setup.txt create mode 100644 FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/mqtt_broker_setup.txt create mode 100644 FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/mqtt_broker_setup.txt create mode 100644 FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/mqtt_broker_setup.txt diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/demo_config.h b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/demo_config.h index ab8aafa27a..fdf6cc7de8 100644 --- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/demo_config.h +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/demo_config.h @@ -70,11 +70,8 @@ * This demo application can be run with any MQTT broker, that supports server * authentication. * - * For AWS IoT MQTT broker, this is the Thing's REST API Endpoint. - * - * @note Your AWS IoT Core endpoint can be found in the AWS IoT console under - * Settings/Custom Endpoint, or using the describe-endpoint REST API (with - * AWS CLI command line tool). + * @note If you would like to setup an MQTT broker for running this demo, + * please see `mqtt_broker_setup.txt`. * * #define democonfigMQTT_BROKER_ENDPOINT "...insert here..." */ @@ -95,11 +92,6 @@ /** * @brief Server's root CA certificate. * - * For AWS IoT MQTT broker, this certificate is used to identify the AWS IoT - * server and is publicly available. Refer to the AWS documentation available - * in the link below. - * https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs - * * @note This certificate should be PEM-encoded. * * Must include the PEM header and footer: diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/mqtt_broker_setup.txt b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/mqtt_broker_setup.txt new file mode 100644 index 0000000000..019b092651 --- /dev/null +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/mqtt_broker_setup.txt @@ -0,0 +1,59 @@ +It is our recommendation to always use strong mutual authentication in any Internet of Things +application. Instructions below are for setting up a local Mosquitto broker that supports +TLS server-only authentication for use with this MQTT demo. +1. Generate certificates with OpenSSL. + a. Download and install [Git For Windows](https://git-scm.com/download/win). + Most of you may already have this installed. Git For Windows provides an + OpenSSL binary for generating certificates. + b. Open PowerShell and enter the following commands to generate TLS certificates: + i. cd "C:\Program Files\Git\usr\bin" # If Git is installed elsewhere, update the path. + ii. mkdir $home\Documents\certs + iii. .\openssl.exe req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout $home\Documents\certs\ca.key -out $home\Documents\certs\ca.crt + iv. .\openssl.exe req -nodes -sha256 -new -keyout $home\Documents\certs\server.key -out $home\Documents\certs\server.csr + v. .\openssl.exe x509 -req -sha256 -in $home\Documents\certs\server.csr -CA $home\Documents\certs\ca.crt -CAkey $home\Documents\certs\ca.key -CAcreateserial -out $home\Documents\certs\server.crt -days 365 +2. Download Mosquitto from https://mosquitto.org/download/ +3. Install Mosquitto as a Windows service by running the installer. +4. Go to the path where Mosquitto was installed. The default path is C:\Program Files\mosquitto. +5. Update mosquitto.conf to have the following entries and don't forget to substitute your Windows username: + port 8883 + cafile C:\Users\%Substitute Windows username%\Documents\certs\ca.crt + certfile C:\Users\%Substitute Windows username%\Documents\certs\server.crt + keyfile C:\Users\%Substitute Windows username%\Documents\certs\server.key + tls_version tlsv1.2 +6. Start the Mosquitto service. + More details about running Mosquitto as a Windows service can be found at + https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and + https://github.com/eclipse/mosquitto/blob/master/readme.md +7. Verify that Mosquitto server is running locally and listening on port 8883 + by following the steps below. + a. Open PowerShell. + b. Type in command `netstat -a -p TCP | findstr 8883` to check if there + is an active connection listening on port 8883. + c. Verify that there is an output as shown below + `TCP 0.0.0.0:8883 :0 LISTENING` + d. If there is no output on step c, go through the Mosquitto documentation + listed above to check if the setup was correct. +8. Make sure the Mosquitto broker is allowed to communicate through + Windows Firewall. The instructions for allowing an application on Windows 10 + Defender Firewall can be found at the link below. + https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall + After running this MQTT example, consider disabling the Mosquitto broker to + communicate through Windows Firewall for avoiding unwanted network traffic + to your machine. +9. After verifying that a Mosquitto broker is running successfully, update + the config `democonfigMQTT_BROKER_ENDPOINT` to the local IP address of your + Windows host machine. Please note that "localhost" or address "127.0.0.1" + will not work as this example is running on a Windows Simulator and not on a + Windows host natively. Also note that, if the Windows host is using a + Virtual Private Network(VPN), connection to the Mosquitto broker may not work. +10. In the certs folder of your Documents, you will find a file called `ca.crt`. + Copy its contents to `#define democonfigROOT_CA_PEM`. Keep in mind that it + must include the PEM header and footer and be formatted in this manner: + #define democonfigROOT_CA_PEM \ + "-----BEGIN CERTIFICATE-----\n" \ + "...base64 data...\n" \ + "-----END CERTIFICATE-----\n" +11. Update the config `democonfigdisableSNI` to `( pdTRUE )`. It needs to be + configured this way because the local MQTT broker will only have an IP + address but not a hostname. However, SNI (Server name indication) should + be enabled whenever possible. diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/demo_config.h b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/demo_config.h index 23b9be191c..acd96194d8 100644 --- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/demo_config.h +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/demo_config.h @@ -65,38 +65,8 @@ /** * @brief MQTT broker end point to connect to. * - * @note For running this demo an MQTT broker, which can be run locally on - * the same host is recommended. Any MQTT broker, which can be run on a Windows - * host can be used for this demo. However, the instructions below are for - * setting up a local Mosquitto broker on a Windows host. - * 1. Download Mosquitto from https://mosquitto.org/download/ - * 2. Install Mosquitto as a Windows service by running the installer. - * More details about installing as a Windows service can be found at - * https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and - * https://github.com/eclipse/mosquitto/blob/master/readme.md - * 3. Verify that Mosquitto server is running locally and listening on port - * 1883 by following the steps below. - * a. Open Power Shell. - * b. Type in command `netstat -a -p TCP | grep 1883` to check if there - * is an active connection listening on port 1883. - * c. Verify that there is an output as shown below - * `TCP 0.0.0.0:1883 :0 LISTENING` - * d. If there is no output on step c,go through the Mosquitto documentation - * listed above to check if the installation was successful. - * 4. Make sure the Mosquitto broker is allowed to communicate through - * Windows Firewall. The instructions for allowing an application on Windows 10 - * Defender Firewall can be found at the link below. - * https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall - * After running this MQTT example, consider disabling the Mosquitto broker to - * communicate through Windows Firewall for avoiding unwanted network traffic - * to your machine. - * 5. After verifying that a Mosquitto broker is running successfully, update - * the config democonfigMQTT_BROKER_ENDPOINT to the local IP address of the - * Windows host machine. Please note that "localhost" or address "127.0.0.1" - * will not work as this example is running on a Windows Simulator and not on - * Windows host natively. Also note that, if the Windows host is using a - * Virtual Private Network(VPN), connection to the Mosquitto broker may not - * work. + * @note If you would like to setup an MQTT broker for running this demo, + * please see `mqtt_broker_setup.txt`. * * #define democonfigMQTT_BROKER_ENDPOINT "insert here." */ diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/mqtt_broker_setup.txt b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/mqtt_broker_setup.txt new file mode 100644 index 0000000000..52f79c84bc --- /dev/null +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/mqtt_broker_setup.txt @@ -0,0 +1,31 @@ +It is our recommendation to always use strong mutual authentication in any Internet of Things +application. Instructions below are for setting up a local Mosquitto broker that communicates +over plaintext for use with this MQTT demo. +1. Download Mosquitto from https://mosquitto.org/download/ +2. Install Mosquitto as a Windows service by running the installer. +3. Start the Mosquitto service. + More details about running Mosquitto as a Windows service can be found at + https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and + https://github.com/eclipse/mosquitto/blob/master/readme.md +4. Verify that Mosquitto server is running locally and listening on port 1883 + by following the steps below. + a. Open PowerShell. + b. Type in command `netstat -a -p TCP | findstr 1883` to check if there + is an active connection listening on port 1883. + c. Verify that there is an output as shown below + `TCP 0.0.0.0:1883 :0 LISTENING` + d. If there is no output on step c, go through the Mosquitto documentation + listed above to check if the setup was correct. +5. Make sure the Mosquitto broker is allowed to communicate through + Windows Firewall. The instructions for allowing an application on Windows 10 + Defender Firewall can be found at the link below. + https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall + After running this MQTT example, consider disabling the Mosquitto broker to + communicate through Windows Firewall for avoiding unwanted network traffic + to your machine. +6. After verifying that a Mosquitto broker is running successfully, update + the config `democonfigMQTT_BROKER_ENDPOINT` to the local IP address of your + Windows host machine. Please note that "localhost" or address "127.0.0.1" + will not work as this example is running on a Windows Simulator and not on a + Windows host natively. Also note that, if the Windows host is using a + Virtual Private Network(VPN), connection to the Mosquitto broker may not work. diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/demo_config.h b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/demo_config.h index 3bdad9b538..62ec41f69b 100644 --- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/demo_config.h +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/demo_config.h @@ -102,6 +102,9 @@ * * @note This certificate should be PEM-encoded. * + * @note If you would like to setup an MQTT broker for running this demo, + * please see `mqtt_broker_setup.txt`. + * * Must include the PEM header and footer: * "-----BEGIN CERTIFICATE-----\n"\ * "...base64 data...\n"\ diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/mqtt_broker_setup.txt b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/mqtt_broker_setup.txt new file mode 100644 index 0000000000..0491f4097f --- /dev/null +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/mqtt_broker_setup.txt @@ -0,0 +1,76 @@ +Instructions below are for setting up a local Mosquitto broker that supports +TLS mutual authentication for use with this MQTT demo. +1. Generate certificates with OpenSSL. + a. Download and install [Git For Windows](https://git-scm.com/download/win). + Most of you may already have this installed. Git For Windows provides an + OpenSSL binary for generating certificates. + b. Open PowerShell and enter the following commands to generate TLS certificates: + i. cd "C:\Program Files\Git\usr\bin" # If Git is installed elsewhere, update the path. + ii. mkdir $home\Documents\certs + iii. .\openssl.exe req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout $home\Documents\certs\ca.key -out $home\Documents\certs\ca.crt + iv. .\openssl.exe req -nodes -sha256 -new -keyout $home\Documents\certs\server.key -out $home\Documents\certs\server.csr + v. .\openssl.exe x509 -req -sha256 -in $home\Documents\certs\server.csr -CA $home\Documents\certs\ca.crt -CAkey $home\Documents\certs\ca.key -CAcreateserial -out $home\Documents\certs\server.crt -days 365 + vi. .\openssl.exe genrsa -out $home\Documents\certs\client.key 2048 + vii. .\openssl.exe req -new -out $home\Documents\certs\client.csr -key $home\Documents\certs\client.key + viii. .\openssl.exe x509 -req -in $home\Documents\certs\client.csr -CA $home\Documents\certs\ca.crt -CAkey $home\Documents\certs\ca.key -CAcreateserial -out $home\Documents\certs\client.crt -days 365 +2. Download Mosquitto from https://mosquitto.org/download/ +3. Install Mosquitto as a Windows service by running the installer. +4. Go to the path where Mosquitto was installed. The default path is C:\Program Files\mosquitto. +5. Update mosquitto.conf to have the following entries and don't forget to substitute your Windows username: + port 8883 + cafile C:\Users\%Substitute Windows username%\Documents\certs\ca.crt + certfile C:\Users\%Substitute Windows username%\Documents\certs\server.crt + keyfile C:\Users\%Substitute Windows username%\Documents\certs\server.key + require_certificate true + tls_version tlsv1.2 +6. Start the Mosquitto service. + More details about running Mosquitto as a Windows service can be found at + https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and + https://github.com/eclipse/mosquitto/blob/master/readme.md +7. Verify that Mosquitto server is running locally and listening on port 8883 + by following the steps below. + a. Open PowerShell. + b. Type in command `netstat -a -p TCP | findstr 8883` to check if there + is an active connection listening on port 8883. + c. Verify that there is an output as shown below + `TCP 0.0.0.0:8883 :0 LISTENING` + d. If there is no output on step c, go through the Mosquitto documentation + listed above to check if the setup was correct. +8. Make sure the Mosquitto broker is allowed to communicate through + Windows Firewall. The instructions for allowing an application on Windows 10 + Defender Firewall can be found at the link below. + https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall + After running this MQTT example, consider disabling the Mosquitto broker to + communicate through Windows Firewall for avoiding unwanted network traffic + to your machine. +9. After verifying that a Mosquitto broker is running successfully, update + the config `democonfigMQTT_BROKER_ENDPOINT` to the local IP address of your + Windows host machine. Please note that "localhost" or address "127.0.0.1" + will not work as this example is running on a Windows Simulator and not on a + Windows host natively. Also note that, if the Windows host is using a + Virtual Private Network(VPN), connection to the Mosquitto broker may not work. +10. In the certs folder of your Documents, you will find a file called `ca.crt`. + Copy its contents to `#define democonfigROOT_CA_PEM`. Keep in mind that it + must include the PEM header and footer and be formatted in this manner: + #define democonfigROOT_CA_PEM \ + "-----BEGIN CERTIFICATE-----\n" \ + "...base64 data...\n" \ + "-----END CERTIFICATE-----\n" +11. In the certs folder of your Documents, you will find a file called `client.crt`. + Copy its contents to `#define democonfigCLIENT_CERTIFICATE_PEM`. Keep in mind + that it must include the PEM header and footer and be formatted in this manner: + #define democonfigCLIENT_CERTIFICATE_PEM \ + "-----BEGIN CERTIFICATE-----\n" \ + "...base64 data...\n" \ + "-----END CERTIFICATE-----\n" +11. In the certs folder of your Documents, you will find a file called `client.key`. + Copy its contents to `#define democonfigCLIENT_PRIVATE_KEY_PEM`. Keep in mind + that it must include the PEM header and footer and be formatted in this manner: + #define democonfigCLIENT_PRIVATE_KEY_PEM \ + "-----BEGIN RSA PRIVATE KEY-----\n" \ + "...base64 data...\n" \ + "-----END RSA PRIVATE KEY-----\n" +12. Update the config `democonfigdisableSNI` to `( pdTRUE )`. It needs to be + configured this way because the local MQTT broker will only have an IP + address but not a hostname. However, SNI (Server name indication) should + be enabled whenever possible. diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/demo_config.h b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/demo_config.h index 6ec15888ef..11bef2c6a2 100644 --- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/demo_config.h +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/demo_config.h @@ -75,6 +75,9 @@ * Settings/Custom Endpoint, or using the describe-endpoint REST API (with * AWS CLI command line tool). * + * @note If you would like to setup an MQTT broker for running this demo, + * please see `mqtt_broker_setup.txt`. + * * #define democonfigMQTT_BROKER_ENDPOINT "...insert here..." */ diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/mqtt_broker_setup.txt b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/mqtt_broker_setup.txt new file mode 100644 index 0000000000..0491f4097f --- /dev/null +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/mqtt_broker_setup.txt @@ -0,0 +1,76 @@ +Instructions below are for setting up a local Mosquitto broker that supports +TLS mutual authentication for use with this MQTT demo. +1. Generate certificates with OpenSSL. + a. Download and install [Git For Windows](https://git-scm.com/download/win). + Most of you may already have this installed. Git For Windows provides an + OpenSSL binary for generating certificates. + b. Open PowerShell and enter the following commands to generate TLS certificates: + i. cd "C:\Program Files\Git\usr\bin" # If Git is installed elsewhere, update the path. + ii. mkdir $home\Documents\certs + iii. .\openssl.exe req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout $home\Documents\certs\ca.key -out $home\Documents\certs\ca.crt + iv. .\openssl.exe req -nodes -sha256 -new -keyout $home\Documents\certs\server.key -out $home\Documents\certs\server.csr + v. .\openssl.exe x509 -req -sha256 -in $home\Documents\certs\server.csr -CA $home\Documents\certs\ca.crt -CAkey $home\Documents\certs\ca.key -CAcreateserial -out $home\Documents\certs\server.crt -days 365 + vi. .\openssl.exe genrsa -out $home\Documents\certs\client.key 2048 + vii. .\openssl.exe req -new -out $home\Documents\certs\client.csr -key $home\Documents\certs\client.key + viii. .\openssl.exe x509 -req -in $home\Documents\certs\client.csr -CA $home\Documents\certs\ca.crt -CAkey $home\Documents\certs\ca.key -CAcreateserial -out $home\Documents\certs\client.crt -days 365 +2. Download Mosquitto from https://mosquitto.org/download/ +3. Install Mosquitto as a Windows service by running the installer. +4. Go to the path where Mosquitto was installed. The default path is C:\Program Files\mosquitto. +5. Update mosquitto.conf to have the following entries and don't forget to substitute your Windows username: + port 8883 + cafile C:\Users\%Substitute Windows username%\Documents\certs\ca.crt + certfile C:\Users\%Substitute Windows username%\Documents\certs\server.crt + keyfile C:\Users\%Substitute Windows username%\Documents\certs\server.key + require_certificate true + tls_version tlsv1.2 +6. Start the Mosquitto service. + More details about running Mosquitto as a Windows service can be found at + https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and + https://github.com/eclipse/mosquitto/blob/master/readme.md +7. Verify that Mosquitto server is running locally and listening on port 8883 + by following the steps below. + a. Open PowerShell. + b. Type in command `netstat -a -p TCP | findstr 8883` to check if there + is an active connection listening on port 8883. + c. Verify that there is an output as shown below + `TCP 0.0.0.0:8883 :0 LISTENING` + d. If there is no output on step c, go through the Mosquitto documentation + listed above to check if the setup was correct. +8. Make sure the Mosquitto broker is allowed to communicate through + Windows Firewall. The instructions for allowing an application on Windows 10 + Defender Firewall can be found at the link below. + https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall + After running this MQTT example, consider disabling the Mosquitto broker to + communicate through Windows Firewall for avoiding unwanted network traffic + to your machine. +9. After verifying that a Mosquitto broker is running successfully, update + the config `democonfigMQTT_BROKER_ENDPOINT` to the local IP address of your + Windows host machine. Please note that "localhost" or address "127.0.0.1" + will not work as this example is running on a Windows Simulator and not on a + Windows host natively. Also note that, if the Windows host is using a + Virtual Private Network(VPN), connection to the Mosquitto broker may not work. +10. In the certs folder of your Documents, you will find a file called `ca.crt`. + Copy its contents to `#define democonfigROOT_CA_PEM`. Keep in mind that it + must include the PEM header and footer and be formatted in this manner: + #define democonfigROOT_CA_PEM \ + "-----BEGIN CERTIFICATE-----\n" \ + "...base64 data...\n" \ + "-----END CERTIFICATE-----\n" +11. In the certs folder of your Documents, you will find a file called `client.crt`. + Copy its contents to `#define democonfigCLIENT_CERTIFICATE_PEM`. Keep in mind + that it must include the PEM header and footer and be formatted in this manner: + #define democonfigCLIENT_CERTIFICATE_PEM \ + "-----BEGIN CERTIFICATE-----\n" \ + "...base64 data...\n" \ + "-----END CERTIFICATE-----\n" +11. In the certs folder of your Documents, you will find a file called `client.key`. + Copy its contents to `#define democonfigCLIENT_PRIVATE_KEY_PEM`. Keep in mind + that it must include the PEM header and footer and be formatted in this manner: + #define democonfigCLIENT_PRIVATE_KEY_PEM \ + "-----BEGIN RSA PRIVATE KEY-----\n" \ + "...base64 data...\n" \ + "-----END RSA PRIVATE KEY-----\n" +12. Update the config `democonfigdisableSNI` to `( pdTRUE )`. It needs to be + configured this way because the local MQTT broker will only have an IP + address but not a hostname. However, SNI (Server name indication) should + be enabled whenever possible. diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/demo_config.h b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/demo_config.h index 23b9be191c..acd96194d8 100644 --- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/demo_config.h +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/demo_config.h @@ -65,38 +65,8 @@ /** * @brief MQTT broker end point to connect to. * - * @note For running this demo an MQTT broker, which can be run locally on - * the same host is recommended. Any MQTT broker, which can be run on a Windows - * host can be used for this demo. However, the instructions below are for - * setting up a local Mosquitto broker on a Windows host. - * 1. Download Mosquitto from https://mosquitto.org/download/ - * 2. Install Mosquitto as a Windows service by running the installer. - * More details about installing as a Windows service can be found at - * https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and - * https://github.com/eclipse/mosquitto/blob/master/readme.md - * 3. Verify that Mosquitto server is running locally and listening on port - * 1883 by following the steps below. - * a. Open Power Shell. - * b. Type in command `netstat -a -p TCP | grep 1883` to check if there - * is an active connection listening on port 1883. - * c. Verify that there is an output as shown below - * `TCP 0.0.0.0:1883 :0 LISTENING` - * d. If there is no output on step c,go through the Mosquitto documentation - * listed above to check if the installation was successful. - * 4. Make sure the Mosquitto broker is allowed to communicate through - * Windows Firewall. The instructions for allowing an application on Windows 10 - * Defender Firewall can be found at the link below. - * https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall - * After running this MQTT example, consider disabling the Mosquitto broker to - * communicate through Windows Firewall for avoiding unwanted network traffic - * to your machine. - * 5. After verifying that a Mosquitto broker is running successfully, update - * the config democonfigMQTT_BROKER_ENDPOINT to the local IP address of the - * Windows host machine. Please note that "localhost" or address "127.0.0.1" - * will not work as this example is running on a Windows Simulator and not on - * Windows host natively. Also note that, if the Windows host is using a - * Virtual Private Network(VPN), connection to the Mosquitto broker may not - * work. + * @note If you would like to setup an MQTT broker for running this demo, + * please see `mqtt_broker_setup.txt`. * * #define democonfigMQTT_BROKER_ENDPOINT "insert here." */ diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/mqtt_broker_setup.txt b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/mqtt_broker_setup.txt new file mode 100644 index 0000000000..52f79c84bc --- /dev/null +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/mqtt_broker_setup.txt @@ -0,0 +1,31 @@ +It is our recommendation to always use strong mutual authentication in any Internet of Things +application. Instructions below are for setting up a local Mosquitto broker that communicates +over plaintext for use with this MQTT demo. +1. Download Mosquitto from https://mosquitto.org/download/ +2. Install Mosquitto as a Windows service by running the installer. +3. Start the Mosquitto service. + More details about running Mosquitto as a Windows service can be found at + https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and + https://github.com/eclipse/mosquitto/blob/master/readme.md +4. Verify that Mosquitto server is running locally and listening on port 1883 + by following the steps below. + a. Open PowerShell. + b. Type in command `netstat -a -p TCP | findstr 1883` to check if there + is an active connection listening on port 1883. + c. Verify that there is an output as shown below + `TCP 0.0.0.0:1883 :0 LISTENING` + d. If there is no output on step c, go through the Mosquitto documentation + listed above to check if the setup was correct. +5. Make sure the Mosquitto broker is allowed to communicate through + Windows Firewall. The instructions for allowing an application on Windows 10 + Defender Firewall can be found at the link below. + https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall + After running this MQTT example, consider disabling the Mosquitto broker to + communicate through Windows Firewall for avoiding unwanted network traffic + to your machine. +6. After verifying that a Mosquitto broker is running successfully, update + the config `democonfigMQTT_BROKER_ENDPOINT` to the local IP address of your + Windows host machine. Please note that "localhost" or address "127.0.0.1" + will not work as this example is running on a Windows Simulator and not on a + Windows host natively. Also note that, if the Windows host is using a + Virtual Private Network(VPN), connection to the Mosquitto broker may not work. diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/demo_config.h b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/demo_config.h index f6763222fa..4be735903d 100644 --- a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/demo_config.h +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/demo_config.h @@ -65,38 +65,8 @@ /** * @brief MQTT broker end point to connect to. * - * @note For running this demo an MQTT broker, which can be run locally on - * the same host is recommended. Any MQTT broker, which can be run on a Windows - * host can be used for this demo. However, the instructions below are for - * setting up a local Mosquitto broker on a Windows host. - * 1. Download Mosquitto from https://mosquitto.org/download/ - * 2. Install Mosquitto as a Windows service by running the installer. - * More details about installing as a Windows service can be found at - * https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and - * https://github.com/eclipse/mosquitto/blob/master/readme.md - * 3. Verify that Mosquitto server is running locally and listening on port - * 1883 by following the steps below. - * a. Open Power Shell. - * b. Type in command `netstat -a -p TCP | grep 1883` to check if there - * is an active connection listening on port 1883. - * c. Verify that there is an output as shown below - * `TCP 0.0.0.0:1883 :0 LISTENING` - * d. If there is no output on step c,go through the Mosquitto documentation - * listed above to check if the installation was successful. - * 4. Make sure the Mosquitto broker is allowed to communicate through - * Windows Firewall. The instructions for allowing an application on Windows 10 - * Defender Firewall can be found at the link below. - * https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall - * After running this MQTT example, consider disabling the Mosquitto broker to - * communicate through Windows Firewall for avoiding unwanted network traffic - * to your machine. - * 5. After verifying that a Mosquitto broker is running successfully, update - * the config democonfigMQTT_BROKER_ENDPOINT to the local IP address of the - * Windows host machine. Please note that "localhost" or address "127.0.0.1" - * will not work as this example is running on a Windows Simulator and not on - * Windows host natively. Also note that, if the Windows host is using a - * Virtual Private Network(VPN), connection to the Mosquitto broker may not - * work. + * @note If you would like to setup an MQTT broker for running this demo, + * please see `mqtt_broker_setup.txt`. * * #define democonfigMQTT_BROKER_ENDPOINT "insert here." */ diff --git a/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/mqtt_broker_setup.txt b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/mqtt_broker_setup.txt new file mode 100644 index 0000000000..52f79c84bc --- /dev/null +++ b/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/mqtt_broker_setup.txt @@ -0,0 +1,31 @@ +It is our recommendation to always use strong mutual authentication in any Internet of Things +application. Instructions below are for setting up a local Mosquitto broker that communicates +over plaintext for use with this MQTT demo. +1. Download Mosquitto from https://mosquitto.org/download/ +2. Install Mosquitto as a Windows service by running the installer. +3. Start the Mosquitto service. + More details about running Mosquitto as a Windows service can be found at + https://github.com/eclipse/mosquitto/blob/master/readme-windows.txt and + https://github.com/eclipse/mosquitto/blob/master/readme.md +4. Verify that Mosquitto server is running locally and listening on port 1883 + by following the steps below. + a. Open PowerShell. + b. Type in command `netstat -a -p TCP | findstr 1883` to check if there + is an active connection listening on port 1883. + c. Verify that there is an output as shown below + `TCP 0.0.0.0:1883 :0 LISTENING` + d. If there is no output on step c, go through the Mosquitto documentation + listed above to check if the setup was correct. +5. Make sure the Mosquitto broker is allowed to communicate through + Windows Firewall. The instructions for allowing an application on Windows 10 + Defender Firewall can be found at the link below. + https://support.microsoft.com/en-us/help/4558235/windows-10-allow-an-app-through-microsoft-defender-firewall + After running this MQTT example, consider disabling the Mosquitto broker to + communicate through Windows Firewall for avoiding unwanted network traffic + to your machine. +6. After verifying that a Mosquitto broker is running successfully, update + the config `democonfigMQTT_BROKER_ENDPOINT` to the local IP address of your + Windows host machine. Please note that "localhost" or address "127.0.0.1" + will not work as this example is running on a Windows Simulator and not on a + Windows host natively. Also note that, if the Windows host is using a + Virtual Private Network(VPN), connection to the Mosquitto broker may not work.