added support for secure TLS connections (#699)
* added support for secure TLS connections on ESP32 and ESP8266 close #101 * added TLS test builds * added documentation for TLS fixed some some issues in the documentation * added documentation for error code=54
This commit is contained in:
Leon Kiefer authored and GitHub committed
1 parent
60d173ff51
commit
b5527d2e7b
14 files changed
+180
-40
No files matched your search
@@ -0,0 +1,34 @@
|
||||
# Advanced configuration of the gateway
|
||||
|
||||
## Secure connection to the broker
|
||||
By default the connection between the gateway and the MQTT broker is not encrypted and the identity of the broker is not verified.
|
||||
For connections in a private local area network this might not be a big issue, but if you connect to a broker on the internet or the gateway is connected to a public network there is a high security risk.
|
||||
|
||||
To secure the connection, Transport Layer Security (TLS) can be used which is supported by most MQTT brokers.
|
||||
Setting up and configuring TLS in the MQTT broker is a complex process and perhaps include creating a self-signed certificate.
|
||||
The configuration of the broker is not covered here, you should look into the documentation of your broker.
|
||||
|
||||
### Prerequisites
|
||||
The MQTT broker is configured for TLS and you have access to the CA certificate which was used to sign the MQTT broker certificate.
|
||||
You are using ESP8266 or ESP32, for other boards TLS is not supported.
|
||||
|
||||
### Configure secure connection in the gateway
|
||||
To enable the secure connection and use TLS uncomment `//#define SECURE_CONNECTION` in `User_config.h`.
|
||||
Set `MQTT_SERVER` to the Common Name (CN) of the certificate of the broker.
|
||||
This can be the hostname or the ip of the broker.
|
||||
|
||||
The CA certificate should be in PEM ascii format.
|
||||
If your CA certificate is not in the correct format or you don't know the format, use `openssl` to convert the certificate to the correct format.
|
||||
In `User_config.h` replace the `...` with the content of your certificate which is between the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines:
|
||||
```cpp
|
||||
const char* certificate CERT_ATTRIBUTE = R"EOF("
|
||||
-----BEGIN CERTIFICATE-----
|
||||
...
|
||||
-----END CERTIFICATE-----
|
||||
")EOF";
|
||||
```
|
||||
|
||||
If you have no ntp server in your local network (included in the router) or not using dhcp, you should uncomment `//# define NTP_SERVER "pool.ntp.org"` to use a ntp server for time synchronization.
|
||||
This is related to the `W: failed, ssl error code=54` error message, which indicate that the time of the esp is not correct.
|
||||
|
||||
You can know compile and upload to your board and the gateway should connect with TLS to your broker.
|
||||
@@ -8,10 +8,10 @@
|
||||
* Unzip the libraries into your arduino libraries folder (example D:/Users/XXXX/Documents/Arduino/libraries)
|
||||
* If necessary replace the spaces into each library folder by _: example rename “ESP32 BLE Arduino” folder to “ESP32_BLE_Arduino”
|
||||
* Open the file main.ino from OpenMQTTGateway/main folder with the arduino IDE
|
||||
* Change the settings and the desired gateways into user_config.h (uncomment the modules you want)
|
||||
* Change the settings and the desired gateways into User_config.h (uncomment the modules you want)
|
||||
|
||||
*Example for the use of RF gateway*
|
||||
```C++
|
||||
```cpp
|
||||
#define ZgatewayRF "RF" //ESP8266, Arduino, ESP32
|
||||
//#define ZgatewayIR "IR" //ESP8266, Arduino, Sonoff RF Bridge
|
||||
//#define ZgatewayLORA "LORA" //ESP8266, Arduino, ESP32
|
||||
@@ -27,4 +27,4 @@
|
||||
* Upload ➡️
|
||||
* You should see the logs into the serial monitor
|
||||
|
||||
With an ESP if you did not set your network and mqtt parameters manualy you can now open the [web portal configuration](portal.md).
|
||||
With an ESP if you did not set your network and mqtt parameters manually you can now open the [web portal configuration](portal.md).
|
||||
@@ -1,9 +1,8 @@
|
||||
# Upload Binaries
|
||||
This section is usefull if you want to directly flash your ESP from your desktop. Once flashed you can change wifi and broker settings.
|
||||
This section is useful if you want to directly flash your ESP from your desktop. Once flashed you can change wifi and broker settings.
|
||||
Nevertheless you will not be able to change advanced parameters, if you want to do so refer to [Upload from PlatformIO][pio] section.
|
||||
|
||||
Download the binary corresponding to your board and gateway [here](https://github.com/1technophile/OpenMQTTGateway/releases) from github and uncompress it.
|
||||
Note that the -all binary packages are produced for tests only.
|
||||
|
||||
## ESP32
|
||||
* Download the bootloader [here](https://github.com/espressif/arduino-esp32/raw/master/tools/sdk/bin/bootloader_dio_80m.bin)
|
||||
@@ -13,7 +12,7 @@ https://www.espressif.com/en/products/hardware/esp32/resources
|
||||
* Uncompress the package
|
||||
* Execute `flash_download_tools`
|
||||
* Choose ESP32 DownloadTool
|
||||
* Set the files and the adress as below:
|
||||
* Set the files and the address as below:
|
||||
|
||||
And set the parameters used by arduino IDE, we are able to upload to ESP32 a binary file containing OpenMQTTGateway.
|
||||
* Set the config as above
|
||||
@@ -33,6 +32,6 @@ https://github.com/marcelstoer/nodemcu-pyflasher/releases
|
||||
* Click on *FlashNodeMCU*
|
||||
The upload details appears.
|
||||
|
||||
With an ESP if you did not set your network and mqtt parameters manualy you can now open the [web portal configuration](portal.md).
|
||||
With an ESP if you did not set your network and mqtt parameters manually you can now open the [web portal configuration](portal.md).
|
||||
|
||||
Note that to reset the wifi and mqtt settings you can check *yes, wipes all data*
|
||||
+6
-6
@@ -1,6 +1,6 @@
|
||||
# Upload with PlatformIO
|
||||
This section is usefull if you want to do advanced configuration of your project or if you choose an Arduino. Indeed the ESP family can be loaded directly without any configuration from your desktop.
|
||||
Advanced configurations means changing the default used pins, the MQTT subjects and all the expert parameters that you can find in [user_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h) and in all [config_XX.h](https://github.com/1technophile/OpenMQTTGateway/tree/development/main).
|
||||
Advanced configurations means changing the default used pins, the MQTT subjects and all the expert parameters that you can find in [User_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h) and in all [config_XX.h](https://github.com/1technophile/OpenMQTTGateway/tree/development/main).
|
||||
If you don't have to change the default parameters except wifi and broker setting you can go directly to the [Load](load) section.
|
||||
|
||||
Download the [CODE](https://github.com/1technophile/OpenMQTTGateway/releases) from github.
|
||||
@@ -28,9 +28,9 @@ default_envs = esp32dev-rf
|
||||
If you don't know which env to activate you can refer to [devices](../prerequisites/devices).
|
||||
|
||||
The different listed configurations represents some standard environments, to overload them with special parameters or modules you can modify the config files. The definitions coming from [platformio.ini](https://github.com/1technophile/OpenMQTTGateway/blob/development/platformio.ini) file and config files are cumulative.
|
||||
The main config file is [user_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h), added to it you have one config file per gateway, sensor or actuator, you will find them in the [main](https://github.com/1technophile/OpenMQTTGateway/tree/development/main) folder.
|
||||
The main config file is [User_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h), added to it you have one config file per gateway, sensor or actuator, you will find them in the [main](https://github.com/1technophile/OpenMQTTGateway/tree/development/main) folder.
|
||||
|
||||
If you want to add more sensors or gateways to one `default_envs` you can uncomment them into [user_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/d2dd6138558909b71cc44f69665340247bd5f356/main/User_config.h#L84) or add the modules directly into your environment definition of your .ini files.
|
||||
If you want to add more sensors or gateways to one `default_envs` you can uncomment them into [User_config.h](https://github.com/1technophile/OpenMQTTGateway/blob/d2dd6138558909b71cc44f69665340247bd5f356/main/User_config.h#L84) or add the modules directly into your environment definition of your .ini files.
|
||||
|
||||
Example to add IR to `esp32dev-rf` add the `build_flags` below to the env definition:
|
||||
``` ini
|
||||
@@ -102,7 +102,7 @@ With the V0.9 we added the support of json for receiving and publishing.
|
||||
Per default Json reception and Json publication is activated, the previous simple reception mode is also activated to avoid regression on commands.
|
||||
|
||||
You can deactivate Json or simple mode following theses instructions:
|
||||
```C++
|
||||
```cpp
|
||||
#define jsonPublishing true //comment if you don't want to use Json publishing (one topic for all the parameters)
|
||||
//example home/OpenMQTTGateway_ESP32_DEVKIT/BTtoMQTT/4XXXXXXXXXX4 {"rssi":-63,"servicedata":"fe0000000000000000000000000000000000000000"}
|
||||
//#define simplePublishing true //comment if you don't want to use simple publishing (one topic for one parameter)
|
||||
@@ -114,7 +114,7 @@ You can deactivate Json or simple mode following theses instructions:
|
||||
```
|
||||
|
||||
If you are using platformio you can also comment the definitions above and define your parameters into platformio.ini file by setting the following `build_flags`:
|
||||
```C++
|
||||
```cpp
|
||||
'-DjsonPublishing=true'
|
||||
'-DjsonReceiving=true'
|
||||
'-DsimpleReceiving=true'
|
||||
@@ -138,4 +138,4 @@ With an ESP if you did not set your network and mqtt parameters manualy you can
|
||||
|
||||
::: warning Note
|
||||
simpleReceiving on Arduino boards doesn't accept 64 bits MQTT values, you can only send 32bits values from the MQTT broker.
|
||||
:::
|
||||
:::
|
||||
@@ -62,3 +62,16 @@ This can be due to corruption of the ESP flash memory, try to erase flash and up
|
||||
|
||||
If you didn't find your answer here post a question to the forum:
|
||||
[](https://community.openmqttgateway.com)
|
||||
|
||||
## ESP does not connect to broker with TLS enabled
|
||||
If you get the following error:
|
||||
`W: failed, ssl error code=54` ("Certificate is expired or not yet valid.")
|
||||
|
||||
This is most probable caused by the time of the esp is not correct/synchronized.
|
||||
The esp uses the Network Time Protocol (NTP) to get the current time from a time server.
|
||||
If you get this error ntp is not configured correctly in the gateway.
|
||||
Uncomment `//# define NTP_SERVER "pool.ntp.org"` to set the `pool.ntp.org` as the time server.
|
||||
You can also choose any other ntp time server you like.
|
||||
|
||||
It is normal that the time synchronization process takes some time and the MQTT connection will not be successful the first time.
|
||||
If you set the ntp server for the gateway and keep getting the errors you should check your certificate validity duration.
|
||||
Reference in new issue
Block a user