Encrypting MQTT: TLS for the Mosquitto broker in Home Assistant

With TLS, card numbers and commands no longer travel through your network in plain text. You need a certificate for the broker, a few lines in the Mosquitto add-on and port 8883 in the bridge.

By default, MQTT runs unencrypted on port 1883. In a well-protected home network that is often acceptable, but every device in the same network could read along. For access control, encryption is worth the few minutes it takes.

What you need

• Home Assistant with the Mosquitto broker add-on
• a certificate and key for the broker in the /ssl folder of Home Assistant, for example from the Let’s Encrypt add-on or self-signed
• a KLOKL Bridge with firmware v1.0.2

Step 1: enable TLS in the add-on

Open Settings → Add-ons → Mosquitto broker → Configuration. Enter the file names of certificate and key as they lie in /ssl. With the defaults, the configuration looks like this:

1logins: []
2require_certificate: false
3certfile: fullchain.pem
4keyfile: privkey.pem
5customize:
6  active: false
7  folder: mosquitto
Copy

Save and restart the add-on. In its log you should now see that it also listens on port 8883. Port 1883 stays available for devices that cannot do TLS yet; once everything is switched over, you can close it in the add-on’s network settings.

Step 2: switch the bridge to MQTTS

1. Open the web interface of the bridge.
2. In the MQTT settings, set the port to 8883 and switch on TLS (MQTTS).
3. Save. The bridge reconnects on its own.
4. In Home Assistant the device should be online again within a few seconds.

What TLS protects against, and what not

With TLS, the traffic between bridge and broker is encrypted; someone who listens in on the network sees no card numbers. In firmware v1.0.2 the bridge does not yet check the broker’s certificate against a certificate authority. That keeps self-signed certificates simple, but it does not protect against an attacker inside your network who actively poses as the broker. Therefore:

• use a separate MQTT user with a strong password for the bridge
• keep IoT devices in their own network segment if your router can do that
• do not make the broker reachable from the internet

All MQTT topics of the bridge are listed in the documentation.