MQTT Broker (Mosquitto) with server certificate (self-signed) and client certificate
Translation of the original in Spanish. Read it in: CatalàCastellano
Part 3 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
In this post we are going to explore the configuration of an MQTT broker using Mosquitto, implementing mutual security through certificates: a self-signed certificate for the server and specific certificates for the clients. We will analyse step by step how to set up the environment, starting from a minimal configuration that allows the use of both TCP connections and Websockets.
Throughout the article the process of negotiating the encrypted connection will be demonstrated in detail using OpenSSL as a TCP+SSL/TLS client, and afterwards the Mosquitto clients will be used to subscribe and publish messages on a demo topic. In addition, we will see how to consume the service through a simple Python script and, to finish, we will use the EMQ MQTTX client from the console, which will let us interact both over TCP and through Websockets.
This practical approach will help you understand in depth how to guarantee security in MQTT communication by implementing certificates both on the server and on the clients. Let's begin!
Assumptions
The following points are assumed for the development of this post:
-
PKI and easy-rsa: We have the basic knowledge about certificate management through a PKI, as described in the post Certificate management (PKI) - easy-rsa. It is assumed that the PKI is already deployed following the indications of that post and that the configuration is in the
varsfile. -
DNS resolution: A DNS server that resolves the host names within our private network is available. Although it is possible to modify the
/etc/hostsfile to achieve this, that practice is considered less advisable in environments where a proper DNS solution can be chosen. -
Mosquitto installation: It is assumed that Mosquitto and its tools/clients are installed on the operating system we will use. In this post, all demonstrations will be carried out on Linux Ubuntu 22.04.
These assumptions will let us focus on the configuration and use of certificates on the MQTT broker without having to detail each of the previous steps for creating and administering the certificate infrastructure.
Video demonstration
Obtaining the certificates
We start from what is described in the post: MQTT Broker (Mosquitto) with server certificate (self-signed)
Therefore, we only have to create the certificate for the clients we are going to use. The MQTT server ones are already ready.
# desde la máquina que queramos con easy-rsa instalado
./easyrsa gen-req client.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/client.example.tld.req
./easyrsa import-req /the-path/client.example.tld.req client.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 client client.example.tld
### esto generará el fichero .crt necesarios para armar el cliente.
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 client type.
./easyrsa build-client-full client.example.tld
# sin cifrado de la clave privada:
./easyrsa build-client-full client.example.tld --no-pass
IMPORTANT, there is no point in running this command if we have previously done the request creation, (import) and signing.
If we want to issue a certificate that is useful both as client and as server we can use:
./easyrsa build-serverClient-full clientserver.example.tld
# sin cifrado de la clave privada:
./easyrsa build-serverClient-full clientserver.example.tld --no-pass
Mosquitto configuration with server certificate and client certificate requirement
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 true
# 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 true
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.
On the other hand, if use_subject_as_usernameis set to true, the complete subject field of the certificate will be used as the username. In the event that use_identity_as_username or use_subject_as_username are disabled, the client must authenticate through the usual methods, such as verification through password_file. Likewise, any certificate issued by the authorities indicated in cafile or capath will be considered valid for the connection, which offers greater flexibility in issuing and checking client certificates.
When Mosquitto's require_certificate parameter is set to true, the client is required to present a valid certificate in order to connect successfully to the MQTT service. In this context, the additional parameters use_identity_as_usernameand use_subject_as_usernameare relevant: if use_identity_as_usernameis set to true, the Common Name (CN) taken from the client certificate will be used instead of the MQTT username for access control, omitting the password, since it is assumed that only authenticated clients have valid certificates.
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 \
-CAfile certs/ca.crt \
mqtt.example.tld:8883
# using my CA, self-signed succesful checking
openssl s_client \
-CAfile certs/ca.crt \
--cert certs/client.example.tld.crt \
--key certs/client.example.tld.key \
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 -d \
--cafile pki/ca.crt \
--cert certs/client.example.tld.crt \
--key certs/client.example.tld.key \
-h mqtt.example.tld -p 8883 \
-t topic1 -v
I publish a message on the topic with the content: value1
mosquitto_pub -d \
--cafile pki/ca.crt \
--cert certs/client.example.tld.crt \
--key certs/client.example.tld.key \
-h mqtt.example.tld -p 8883 \
-t topic1 -m "message1"
When we run the commands, we will be asked for the passphrase of the private key. Both to publish and to subscribe, since both need access to the file "certs/client.example.tld.key" which is encrypted with a symmetric key.
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.
This client for the moment does not support symmetric encryption protection on the private key, so first we must extract the private key into a new file:
# extraer clave privada de fichero cifrado:
openssl rsa -in python_client/certs/client.example.tld.key -out python_client/certs/client.example.tld.key.raw
# para completar el proceso se deberá introducir la clave simétrica
# mqttx-cli using docker
alias mqttx-cli 'docker run --rm \
--entrypoint /usr/local/bin/mqttx \
-v ./pki/ca.crt:/tmp/ca.crt \
-v ./python_client/certs/client.example.tld.crt:/tmp/client.example.tld.crt \
-v ./python_client/certs/client.example.tld.key.raw:/tmp/client.example.tld.key \
emqx/mqttx-cli'
# suscripción
mqttx-cli sub \
--ca /tmp/ca.crt \
--cert /tmp/client.example.tld.crt \
--key /tmp/client.example.tld.key \
-h mqtt.example.tld \
-p 8884 -l wss \
-t topic1
# publicación
mqttx-cli pub \
--ca /tmp/ca.crt \
--cert /tmp/client.example.tld.crt \
--key /tmp/client.example.tld.key \
-h mqtt.example.tld \
-p 8883 -l mqtts \
-t topic1 -m message1