MQTT Broker (Mosquitto) with server certificate (self-signed)

Translation of the original in Spanish. Read it in: CatalàCastellano

Part 2 of 5Certificates, PKI and MQTT over TLS
  1. Certificate management (PKI) - easy-rsa
  2. MQTT Broker (Mosquitto) with server certificate (self-signed)
  3. MQTT Broker (Mosquitto) with server certificate (self-signed) and client certificate
  4. MQTT Broker (Mosquitto) with server certificate (Let's Encrypt)
  5. Certificate formats: PEM, DER and PKCS#12 and private key handling

Scenario description

This describes how to set up an MQTT broker using Mosquitto, one of the fastest and simplest servers to deploy. It shows the simplest possible configuration file to load the certificates generated both for TCP connections and for Websockets.

Next, it demonstrates in full detail how the encrypted connection is negotiated through the certificate; we will do this using OpenSSL as a TCP+SSL/TLS client; afterwards the Mosquitto clients will be used to subscribe and publish messages on a demo topic. Then it will also show how to consume the service with a simple piece of Python code. Finally, the service will be consumed with the EMQ MQTTX client via the console, which will let us consume the service over TCP and also over Websockets.

Assumptions

  • We have the basic concepts described in the post Certificate management (PKI) - easy-rsa.

  • It is assumed that we have a PKI deployed as explained in Certificate management (PKI) - easy-rsa. It is also assumed that its configuration is in the vars file.

  • We will also assume that we have a DNS server that resolves, at least, on our private network. This step could also be replaced with the relevant changes to /etc/hosts, but I consider that a bad practice if it can be avoided.

  • It is also assumed that we have Mosquitto and its tools/clients installed on the operating system we are going to use. All our demonstrations will be on Linux Ubuntu 22.04

Video demonstration

MQTT Broker (Mosquitto) con certificado servidor (self-signed) · Original on YouTube ↗

Obtaining the certificates

We create the certificate request

The goal is to fill in the fields our certificate will have with the information that identifies our service. The most important field is the X.509 DN, because it must match at least one of the machine's canonical names (FQDN). If not, we will have problems when clients connect, since they will complain that we are not who we say we are. The main purpose of a certificate is to ensure that we are who we say we are.

The Common Name (CN), also known as the Fully Qualified Domain Name (FQDN), is the characteristic value stored inside the DN (Distinguished Name) field, also known as the X.509 DN.

# desde la máquina que queramos con easy-rsa instalado
./easyrsa gen-req mqtt.example.tld
# se genera fichero mqtt.example.tld.req

Signing the certificate request

If the certificate request was not launched from the same PKI, it must be copied to the PKI machine and imported. Let's not forget it. Although in home setups we typically move everything within the same PKI directory structure.

# en la PKI:
## importamos el certificado, si no se ha hecho la petición desde aquí
## se asume que se copió el fichero de certificate request en
## /the-path/mqtt.example.tld.req
./easyrsa import-req /the-path/mqtt.example.tld.req mqtt.example.tld
## esto colocará una copia del fichero .req en la PKI y algunos enlaces.

## Se le pide a la PKI que firme el certificado
./easyrsa sign-req server mqtt.example.tld
### esto generará el fichero .key y .crt necesarios para armar el servidor.

Creating and signing the certificate request

In a single command, when doing everything from the PKI (on a single server) we can obtain: private key, certificate request and signed certificate. This certificate will be of the server type.

./easyrsa build-server-full mqtt.example.tld

# sin cifrado de la clave privada:
./easyrsa build-server-full mqtt.example.tld --no-pass

IMPORTANT, there is no point in running this command if we have previously done the request creation, (import) and signing.

Mosquitto configuration with certificates

This configuration is very simple and will only bring up a Mosquitto on the TCP/8883 port in addition to the WSS/8884 port.

mosquitto.conf

# mqtt secure
listener 8883 0.0.0.0
cafile certs/ca.crt
keyfile certs/mqtt.example.tld.key
certfile certs/mqtt.example.tld.crt
crlfile certs/pki.example.tld.crl
allow_anonymous true
require_certificate false

# websockets secure
listener 8884 0.0.0.0
protocol websockets
cafile certs/ca.crt
keyfile certs/mqtt.example.tld.key
certfile certs/mqtt.example.tld.crt
crlfile certs/pki.example.tld.crl
require_certificate false

To launch the service, we simply need to use the command:

mosquitto -c mosquitto.conf

When we launch the service we will be asked for the passphrase of the private key twice, once for each of the listerners we have configured, TCP and WSS.

Connection negotiation (OpenSSL s_client)

OpenSSL is the tool underneath easy-rsa and the reference library for SSL/TLS; it also provides tools that will let us debug encrypted connections. For this use case we will use openssl s_client, which will let us see all the details of the SSL/TLS negotiation with the MQTT server.

# self-signed fail chechking
openssl s_client mqtt.example.tld:8883
# using my CA, self-signed succesful checking
openssl s_client -CAfile certs/ca.crt mqtt.example.tld:8883

In the demo video you can see more details of how the negotiation between the server and the client is analysed.

Mosquitto clients

Using mosquitto_sub and mosquitto_pub it is demonstrated how traffic is exchanged over an encrypted link. Nothing out of the ordinary, but in encrypted environments and for evolutions of this scenario we will see that it has some limitations.

I subscribe to the topic called topic1 and wait for messages to be published on it:

mosquitto_sub --cafile pki/ca.crt -d -h mqtt.example.tld -p 8883 -t topic1 -v

I publish a message on the topic with the content: value1

mosquitto_pub --cafile pki/ca.crt -d -h mqtt.example.tld -p 8883 -t topic1 -m message1

Clients developed in Python

These are a couple of very simple scripts that only intend to illustrate how simple it is to specify our own CA when initialising the secure connection with the MQTT server.

# se requiere uv, si no lo tienes instalado:
curl -LsSf https://astral.sh/uv/install.sh | sh
# lanzamos el suscriptor
uv run mqtt_sub.py
# lanzamos el publicador
uv run mqtt_pub.py

MQTTX-cli clients using TCP and Websockets

When launching the MQTT broker we exposed the endpoint over TCP and the one over Websockets, but we have not used the second one for anything yet. So, then, let's take advantage of the power of the EMQ client called MQTTX to repeat the same functions as before, but now subscribing with Websockets and publishing with TCP.

# para no tener que instalar mqttx-cli lo usaremos desde Docker:
alias mqttx-cli='docker run -it --rm --entrypoint /usr/local/bin/mqttx -v ./mosquitto/certs/ca.crt:/tmp/ca.crt emqx/mqttx-cli'

# suscripción
mqttx-cli sub \
  --ca /tmp/ca.crt
  -h mqtt.example.tld \
  -p 8884 -l wss \
  -t topic1

# publicación
mqttx-cli pub \
  --ca /tmp/ca.crt
  -h mqtt.example.tld \
  -p 8883 -l mqtts \
  -t topic1 -m message1

References