Who should use MQTT over TLS (MQTTS)
Most people don’t need to use MQTTS. In most home automation setups, communication between the client (Droplet) and server (your MQTT broker, on Home Assistant or another platform) takes place over your home’s WiFi network, which in most cases is safe and secure. Many smart home devices communicate in this way.
Communicating over MQTT without TLS is suitable for a local network, where the server can be trusted and there is unlikely to be anyone eavesdropping. However, for traffic over the real internet, there are risks associated with non-TLS communication. If the client doesn’t verify the server’s identity, it could be sending its data to a malicious entity impersonating the server. If the exchange between client and server is not encrypted, an adversary could stand in the middle, reading or altering messages as they pass between client and server. MQTT over TLS prevents these attacks.
The Droplet also has the option to use TLS without verifying the server’s certificate. This would be suitable for local network applications, where the server can be assumed to be trustworthy, but it is still desired for data to be encrypted.
MQTTS options
MQTTS options
In addition to the standard MQTT options (see this article for general setup instructions), there are some additional options. Using these settings may require configuration changes to your MQTT broker. (See below for an example of how to configure a Home Assistant MQTT broker for TLS.)
Port
Most MQTT brokers use port 8883 for MQTTS communication. While it is not mandatory to use this port for MQTTS, it is recommended for compatibility.
TLS Encryption
Enabling this option will cause messages between Droplet and your MQTT broker to be encrypted. However, there is no server verification.
CA Certificate
Enter the Certificate Authority (CA) certificate that issued your broker’s server certificate. Below, there are instructions for how to generate and install a CA and server certificate for Home Assistant. If you are using another MQTT broker, the procedure may be different, or the certificates may already be present.
The maximum length of the certificate is 2048 characters.
How it works
How it works
When the client (a Droplet) connects to the server (an MQTT broker), the server provides a certificate affirming its identity, as well as its public encryption key. The client then verifies the validity of the certificate – that it matches the server’s stated identity, and that it was issued by an authority the client knows to be trustworthy (a certificate authority (CA)). The client and server use their keys to create session-specific encryption keys. The handshake is now complete, and they can begin communication.
Most internet browsers come with CA certificates from the major CAs already installed. When the user tries to visit a website over HTTPS, the browser verifies the server’s certificate against these known CAs. However, the Droplet doesn’t have knowledge of any of these CA certificates. Also, a user who wants to set up MQTT may not want to pay for certificates from the major CAs, and may generate all the certificates on their local machines. We provide an out-of-band process where they can install their home-generated CA certificate on the Droplet via BLE, so that the Droplet knows what servers it can trust.
Configuring Home Assistant for MQTTS with Host Verification
Configuring Home Assistant for MQTTS with Host Verification
Note: In Home Assistant (or other places), you may see TLS referred to as SSL.
This guide assumes you have the Home Assistant Mosquitto Broker app and the openssl command line utility already installed.
Generating certificates
You can do this on your Home Assistant using the terminal, or generate the certificates on another computer and copy them over at the end. These instructions are from the mosquitto-tls man page.
First, generate a CA certificate and key. This command will ask you for a passphrase. Remember it, since you will need it later.
openssl req -new -x509 -days 10000 -extensions v3_ca -keyout ca.key -out ca.crt
Openssl will ask you to enter some information. For this step, you can either answer the prompts or press enter to leave them blank. However, the Common Name entered here must be different from what you will later enter when generating your server certificate, or else there will be a problem with verifying the certificates.
$ openssl req -new -x509 -days 10000 -extensions v3_ca -keyout ca.key -out ca.crt -noenc
...+........+....+...+.....+...+...+.+...+...+........+.......+++++++++++++++++++++++++++++++++++++++*........+++++++++++++++++++++++++++++++++++++++*.+....+.....+....+..+.........+.+..................+..+...+.......+...+.....+.+...+...+..+.+..............+.+.........+.....+..........+........+...+.......+..+.+......+..............+.+.........+..+....+.....+.+.........+.....+.+.....+...+.......+..+......+.......+........+....+......+...........+....+..+....+...+...+..+.+.........+..++++++
..+...+........+......+++++++++++++++++++++++++++++++++++++++*.......+......+..+.+..+..........+..+.+............+..+.............+.....+.........+.+.....+...+............+.......+.....+.+..+++++++++++++++++++++++++++++++++++++++*.......+...+..+.+..+............+.........+.........+.+......+.....+....+......+...+.....+......+.........+.......+......+...+..+...+....+..+...+......+...............+....+............+...+..+....+..+...+....+...+.....+.............+...........+....+..+.........+.+.....+....+......+.............................+...+...+............+...+...+.+...+...+........+............+....+...+..+.+...............+.....+.........+..........+........+...+...+.........+.......+...+..+.+...+......+.....+......+...++++++
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:New York
Locality Name (eg, city) []:New York
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Hydrific
Organizational Unit Name (eg, section) []:Software
Common Name (e.g. server FQDN or YOUR name) []:Hydrific
Email Address []:[email protected]
Next, generate the server key. If you are asked for a passphrase, press enter to leave it blank.
openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:2048 -out server.key
Generate the certificate signing request.
openssl req -out server.csr -key server.key -new
Here again you will be asked some questions. When asked for a passphrase or challenge password, press enter to leave it empty. If you set a password, the Mosquitto broker will not be able to open the certificate.
The information you enter must differ in some way from what you entered for the CA. Also, make sure to enter your HA’s hostname or IP address as the Common Name. Do not enter "http://" at the beginning. It should be formatted as a fully-qualified domain name.
$ openssl req -out server.csr -key server.key -new
Enter pass phrase for server.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:New York
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:hydrifichomeassistant.local
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
Sign the CSR with the CA we created earlier. You will need to enter the passphrase you used to generate the CA certificate and key in the first step.
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 10000
You should now have these files:
$ ls
ca.crt ca.key ca.srl server.crt server.csr server.key
Installing certificates & configuring the broker
Copy the server certificate (server.crt) and the server private key (server.key) to the ~/ssl folder on your Home Assistant. This is the folder where the Mosquitto broker will look for certificate and key files.
Go to Settings > Apps > Mosquitto broker > Configuration and make sure the certificate file and private key file names match what you installed. Save the changes and restart the broker.
Installing the CA certificate on your Droplet
Open the Droplet app and navigate to the MQTT options. Enable the TLS slider and paste in the contents of the ca.crt file. You most likely also want to change the port to 8883 - by default, the HA Mosquitto broker uses port 8883 for MQTTS. Copy the CA certificate to the Droplet app.
Save the changes. Communications between your Droplet and MQTT broker will now be encrypted, and the Droplet will verify that the server’s certificate was issued by its trusted CA.
Troubleshooting
Troubleshooting
If you are having trouble connecting your Droplet over MQTTS, here are some things to try:
Are you able to connect your Droplet to your MQTT broker without TLS, over port 1883? If even that fails, it indicates something else is wrong with your setup. See this article for information on basic MQTT setup.
Check the logs in the HA Mosquitto app. If there are messages about being unable to open
server.crtorserver.key, make sure you did not set a passphrase when creating them.Make sure you correctly entered the Common Name as a fully-qualified domain name that matches the domain name of your Home Assistant, such as
homeassistant.local- with no “https://” at the beginning or port at the end.Make sure you selected the correct port to use for MQTTS. Typically, it is 8883. You can check that this matches the port selected for MQTTS on your broker’s settings page.
If you used something like Apple Notes to transfer the certificate from your computer to the Droplet app, it may inadvertently modify the certificate (by adding whitespace, or converting some characters to rich text), which will invalidate the certificate. Make sure you copy the certificate into the Droplet app through some means that does not alter the input in any way.