This tutorial is a try to make a very simple and reproducible mosquitto TLS setup, that works on modern systems.

Throughout this tutorial I’m assuming mosquitto is installed to /etc/mosquitto.

CA and server certificate

This is the most basic step and setup. We need to generate a CA certificate and a server key. This is the setup for a self-signed certificate server.

Preparation

We will be placing the certificate files in /etc/mosquitto/certs and perhaps need to create this folder first

mkdir -p /etc/mosquitto/certs
chown mosquitto:mosquitto /etc/mosquitto/certs

Create CA certificates

Use the following commands to create a CA certificate. Important: The FQDN must not be the same as the server FQDN, otherwise you might end up with SSL errors. I use 1825 days, or 5 years.

cd /etc/mosquitto/certs
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 1825 -key ca.key -out ca.crt
chown mosquitto:mosquitto ca.{crt,key}

Generate server certificates

Execute the following commands, one after each other. Important: Here the FQDN must be the hostname, otherwise you might end up with SSL errors. I use 1825 days, or 5 years.

cd /etc/mosquitto/certs
openssl genrsa -out server.key 4096
openssl req -new -out server.csr -key server.key
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 1825
chown mosquitto:mosquitto server.{csr,key,crt}

Mosquitto configuration

Ensure, the following lines are in your mosquitto configuration, typically in /etc/mosquitto/mosquitto.conf

listener 8885
tls_version tlsv1.2
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key

Testing the connection

All you need to establish a server connection is the ca.crt file on your client machine. Then you can try to subscribe to the server with the following command

mosquitto_sub -h HOSTNAME -t '#' -p 8885 --insecure --cafile ca.crt --tls-version tlsv1.2

If you can connect, then everything should be good.

Client certificates

For more security, you can add client certificates, which need to be signed by the server. This setup builds atop the pervious setup

Creating a client certificate

Follow the following commands to generate client certificates for the client puppet. Important: Don’t use the server name as FQDN, but anything else (why not use puppet?) otherwise your SSL configuration might get confused.

cd /etc/mosquitto/certs
openssl genrsa -out puppet.key 4096
openssl req -out puppet.csr -key puppet.key -new
openssl x509 -req -in puppet.csr -CA ca.crt --CAkey ca.key --CAcreateserial -out puppet.crt -days 1825
chown mosquitto:mosquitto puppet.{csr,crt,key}

Update the mosquitto configuration

To enforce the usage of client certificates, you will need to add require_certificate true to your listener configuration:

listener 8885
tls_version tlsv1.2
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate true
use_identity_as_username true         # optional - to use the client names as username

Testing the configuration

Like before, but we will need in addition to also configure the client certificate and key file:

mosquitto_sub -h HOSTNAME -t '#' -p 8885 --insecure --cafile ca.crt --cert puppet.crt --key puppet.key --tls-version tlsv1.2

Generate pkcs12 certificates (for Android)

If you want to use your certificates on Android (e.g. for owntracks)

openssl pkcs12 -export -in puppet.crt -inkey puppet.key -name "puppet's certificate/key" -out puppet.p12

Important: Some Android versions require a password for p12 files in order to work properly.