Created TLS (markdown)

TLS.md

@@ -0,0 +1,69 @@
+# SSL/TLS on Tasmota
+
+> TLS offer increased security between your connected devices and your MQTT server, providing server authentication and encryption. Please refer to the general discussion in [Securing-your-IoT-from-hacking](Securing-your-IoT-from-hacking)
+
+Starting version 6.5.0.15, there are major changes to TLS to make it lighter in memory and easier to use. It has now reduced flash and memory requirements that makes it compatible with Web and Hue EmulatioN.
+
+> Note: If you are upgrading from a previous TLS activated version, there are breaking changes in the way Fingerprints are calculated, read below.
+
+At the TASMOTA configuration, you need to enable to use the TLS Version. This is done by enable `#define USE_MQTT_TLS` in `sonoff/my_user_config.h` and change the port number to `8883`.
+
+If you are using Letsencrypt to generate your server certificates, you should activate `#define USE_MQTT_TLS_CA_CERT`. Tasmota will transparently check the servers certificate with Letsencrypt CA. If you are generating sels-signed certificates or prefer fingerprints, read below.
+
+### Fingerprint validation
+
+The fingerprint is now calculated over the server's Public Key and no more its Certificate. The good news is that Public Key tend to change far less often than certificates, i.e. Letscencrypt triggers a certificate renewal every 3 months, the Public Key fingerprint will not change after a certificate renewal. The bad news is that there is no simple command to retrieve the server's Public Key fingerprint.
+
+So to simplify your task, we have added two more options: 1/ auto-learn of fingerprint, 2/ disabling all-together the fingerprint validation.
+
+**Option 1: Fingerprint auto-learn.** If set, Tasmota will automatically learn the fingerprint during the first connection and will set the Fingerprint settings to the targer fingerprint. To do so, use one of the following commands:
+
+```
+MqttFingerprint1 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+```
+
+or
+
+```
+MqttFingerprint2 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+```
+
+**Option 2: Disable Fingerpring.** You can completely disable server fingerprint validation, which means that Tasmota will not check the server's identity. It means that your traffic can possibly be intercepted and read/changed. This should be used only on trusted networks, i.e. with an MQTT on your local network. **YOU HAVE BEEN WARNED!**
+
+To do so, set one of the Fingerprints to all 0xFF:
+
+```
+MqttFingerprint2 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
+```
+
+### Limitations:
+
+Starting with 6.5.0.15, AxTLS has been replaced with [[https://bearssl.org/][BearSSL]]. This allows a much lighter use of memory - typically 6.0k constantly, and an additional 6.8k during TLS connection. This makes TLS now compatible with Web and Hue/Wemo emulation.
+
+The main limitations are:
+
+- Your SSL/TLS server must support the TLS 1.2 and the `RSA_WITH_AES_128_GCM_SHA256` cipher - which is the case with default Mosquitto configuration
+- The server certificate must have an RSA private key (max 2048 bits) and the certificate must be signed with RSA and SHA256 hash. This is the case with default Letsencrypt certificates.
+- Your SSL/TLS should support TLS 1.2 MFLN to limit buffer to 1024 bytes. If MFLN is not supported, it will still work well as long as the server does not send any message above 1024 bytes (which should be ok, since Tasmota cannot parse MQTT messages above 1024 bytes)
+
+### Below are the instructions of pre-6.5.0.15 versions.
+
+Before v 6.5.0.15: to the value you're getting from the mosquitto server. To get the fingerprint you can use the following command on your MQTT server:
+
+```
+openssl s_client -connect localhost:8883 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -in /dev/stdin
+```
+
+Note: The openssl output will most likely be a Colon separated fingerprint
+
+```
+A5:02:FF:13:99:9F:8B:39:8E:F1:83:4F:11:23:65:0B:32:36:FC:07
+```
+
+Tasmota requires the fingerprint expressed as 20 space separated bytes
+
+```
+A5 02 FF 13 99 9F 8B 39 8E F1 83 4F 11 23 65 0B 32 36 FC 07
+```
+
+Note that when you create your certificate, you should make sure to set the CN field to the value of MQTT_HOST. Setting your CN to a domain name but your MQTT_HOST to an IP address will cause the signature verification on the sonoff to fail.