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
- Certificate management (PKI) - easy-rsa
- MQTT Broker (Mosquitto) with server certificate (self-signed)
- MQTT Broker (Mosquitto) with server certificate (self-signed) and client certificate
- MQTT Broker (Mosquitto) with server certificate (Let's Encrypt)
- 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
varsfile. -
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
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