diff --git a/images/mqtt/tls-connect-1.png b/images/mqtt/tls-connect-1.png new file mode 100644 index 0000000..17ecc84 Binary files /dev/null and b/images/mqtt/tls-connect-1.png differ diff --git a/mqtt/tls-connect-to-broker.md b/mqtt/tls-connect-to-broker.md new file mode 100644 index 0000000..750d3f9 --- /dev/null +++ b/mqtt/tls-connect-to-broker.md @@ -0,0 +1,128 @@ +--- +layout: default +title: Connect to an MQTT broker with TLS encryption +slug: + - label: mqtt + url: /#mqtt + - secure connect +--- + +### Problem + +You want to have an encrypted connection to your Mosquitto MQTT broker. + +### Solution + +Create a valid set of certificates and keys for the broker to use. + +Change the configuration of the broker to start a TLS encrypted port (`mqtts`) using the above. + +Alter the MQTT Config node, changing the "Server" name to start with `mqtts://`. + +#### Example + +**Valid Certificate Creation** + +THe easiest approach for this is to use [Let's Encrypt](https://letsencrypt.org/getting-started/). This is beyond the scope of this article but there are plenty of examples and tutorials available on the Internet. For this to work successfully, you also need to be able to use a registered domain name on your internal network because you cannot use Let's Encrypt with IP addresses or non-public domain names. + +Alternatively, you can create a self-signed set of certificates. Again, this is beyond the scope of the article. However, you may need to create a trusted root certificate and provide its public cert instead of the one that Debian provides that is listed in the configuration below. + +**Mosquitto configuration** + +This assumes that you are using Let's Encrypt or other certificates signed by a root CA already trusted by the Debian operating system. + +Note the entries in `<...>` which need to be replaced with your own folders and files. + +For Linux installations, this goes into a file of any name of the form `*.conf` in the folder `/etc/mosquitto/conf.d/`. So you have to edit it with root privalages (e.g. using `sudo`). On other platforms, please refer to the [Mosquitto configuration documentation](https://mosquitto.org/man/mosquitto-8.html). + +{{ page.lcb }}% raw %} +~~~text +# Default Listener: 1883 +port 1883 +# Bind the default listener to localhost only if you want to force external connections to be TLS only +#bind_address localhost + +# Secure listener +listener 8883 +# TLS +## This is standard and should always be this when using Let's Encrypt +## If using a self-signed certificate, this needs to be your custom Root CA public certificate +cafile /etc/ssl/certs/DST_Root_CA_X3.pem +## These are from your installation of LE +certfile //.cer +keyfile //.key +## Forces use of modern version of TLS to avoid security issues +tls_version tlsv1.2 + +## Forces ALL CLIENTs using this port to provide a valid certificate - change the node config to allow this from NR +#require_certificate true +~~~ +{: .shell} +{{ page.lcb }}% endraw %} + +After making these changes, you have to restart the mosquitto broker. On Linux, you can usr the command: + +~~~text +[~]$ sudo systemctl restart mosquitto +~~~ +{: .shell} + +Other platforms, including Docker-based installations may be different. + +**MQTT Config node configuration** + +![](/images/mqtt/tls-connect-1.png) + +Notes + +* You need to use the IP name rather than IP address in the server name if using Let's Encrypt (otherwise the certificate isn't valid). +* You need to change the server name to a url, prefixed with `mqtts://`. + + This disables the port field, I change that first to `8883` to remind me what the correct port will be. + + If you need to change the port to something other than the default, include it on the URL: + + ``` + mqtts://broker.domain.tld:9999 + ``` + +* You **do not** need to set the "Enable secure connection" flag unless you want to authenticate the Node-RED client to the broker (if you set the require_certificate to true for example). +* If you do not set the "Enable secure connection" flag however, the node will not validate the certificate chain. + +### Discussion + +Mosquitto allows you to create multiple ports for connectivity. This lets you use websockets and TLS encrypted connections in addition to the default connection. + +The folder `/etc/mosquitto/conf.d/` can contain any number of config files which will all be applied so that you can split your custom changes into separate files if you like. + +Just remember that once you use a custom file to set ports, the default port (1883) is no longer active so you have to specify that as well if you still want it to be active. The standard port for MQTT over TLS (MQTTS) is 8883. You can, however, use other ports if they are not in use. Make sure you use a port number greater than 1024 otherwise the broker must be run with root privalages which is not recommended for security reasons. + +You can check which ports the broker has opened with the command: + +~~~text +[~]$ sudo netstat -lptu | grep mosquitto +tcp 0 0 0.0.0.0:8883 0.0.0.0:* LISTEN 17697/mosquitto +tcp 0 0 0.0.0.0:1883 0.0.0.0:* LISTEN 17697/mosquitto +tcp6 0 0 [::]:8883 [::]:* LISTEN 17697/mosquitto +tcp6 0 0 [::]:1883 [::]:* LISTEN 17697/mosquitto +~~~ +{: .shell} + +You can test whether the server device is allowing connections on a port by using telnet from another device. + +~~~text +[~]$ telnet 8883 +~~~ +{: .shell} + +If the connection opens, then the target device is accepting connections on that port. + +Note that the operating system automatically opens the required ports through the devices firewall. + +If you want to monitor what the broker is doing, including seeing which clients connect to which ports, use the following command: + +~~~text +[~]$ sudo tail /var/log/mosquitto/mosquitto.log -f +~~~ +{: .shell} +