MQTT Mosquitto broker with SSL/TLS transport security

Just a quick note in setting up transport layer security on the MQTT Mosquitto broker for both supported protocols: MQTT and WebSockets.

There are several posts on the web regarding this, namely:

SSL Client certs to secure mqtt and Mosquitto websocket support

Those posts explain more or less what is needed to be done to have TLS/SSL transport security. These are just my notes:

Generating the server certificates:
This can be quite easily accomplished by using the following script:
This script will generate a self signed certificate to be used by Mosquito for providing TLS for the MQTT and WebSocket protocol. All that is needed to run the script is to have openssl installed on your Linux machine.

If the script is called without parameters, it will generate a self signed certificate for the hostname where the script is running. Otherwise a we can pass a hostname as the first parameter to the script.

After running the script, the following files are generated:

  1. ca.crt – The CA (Certificate Authority, who published the host certificate) public certificate.
  2. hostname.crt – The hostname, that will run the mosquitto broker, public certificate.
  3. hostname.key – The hostname private key.

After having these files, we need to configure the Mosquitto Broker to use them.

Mosquitto configuration:
To configure the Mosquito broker we need first to copy the certificates and key files to a known directory. We will create a certs directory under /etc/mosquitto:

sudo -s
mkdir -p /etc/mosquitto/certs
cp ca.crt /etc/mosquitto/certs
cp hostname.* /etc/mosquitto/certs

After this we can modify the mosquitto configuration file. One important thing to keep in mind is that lines must be following each other without blank lines after the listener directive.


# Plain MQTT protocol
listener 1883

# End of plain MQTT configuration

listener 8883
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/hostname.crt
keyfile /etc/mosquitto/certs/hostname.key

# End of MQTT over TLS/SLL configuration

# Plain WebSockets configuration
listener 9001
protocol websockets

# End of plain Websockets configuration

# WebSockets over TLS/SSL
listener 9883
protocol websockets
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/hostname.crt
keyfile /etc/mosquitto/certs/hostname.key

We will make one more change, but restart mosquitto broker now and do some testing.

Testing MQTT TLS/SSL configuration
We can use Mqtt-Spy to subscribe to our defined test topic: test. We can use plain MQTT or use MQTT over TLS/SSL:

MQTT Spy simple TLS configuration
MQTT Spy simple TLS configuration

We can use then the MQTT spy tool to publish or subscribe MQTT topics.

By command line, the mosquitto_sub and mosquitto_pub only worked if the port number for MQTTS is provided, otherwise it gives a TLS error:

mosquitto_pub --cafile /etc/mosquitto/certs/ca.crt -h localhost -t "test" -m "message" -p 8883

mosquitto_sub -t \$SYS/broker/bytes/\# -v --cafile /etc/mosquitto/certs/ca.crt -p 8883

This should work without any issues.

Testing MQTT websockets over TLS/SSL configuration
The issue with this testing is that we are using a self signed certificate, so only useful for local, restricted, testing.
Before we can use the MQTT websockets with TLS/SSL enabled we need to use the browser and visit the following URL:


Note that we are using HTTPS. When connecting to the above URL, the browser should complain about the insecure connection, due to the self signed certificate, and we need to add an exception and always accept that certificate. After that the error should be something like connection reset or failed to load page. This is normal, since the browser won’t upgrade the connection to a web socket.
We can now use the Hive MQTT Websockets Client to test our connection, and it should work fine (Note the connected green icon and SSL is selected):
Hive MQTT WebSocket client

Forcing TLSv1.2
All this work of enabling TLS/SSL on the Mosquitto Broker is needed, since most IoT clouds that have MQTT interface need that the connection is over TLS/SSL. More specifically AWS IoT cloud needs the connection to be protected by TLS/SSL, but that connection must be only on version 1.2 of the TLS protocol. AWS IoT cloud also requires client authentication through client certificates, but we are not dealing with this part on this post.

So we are now configuring our Mosquitto broker to only accept TLSv1.2 connections. To do that we modify the mosquitto.conf file and add the following line:

listener 8883
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/hostname.crt
keyfile /etc/mosquitto/certs/hostname.key
tls_version tlsv1.2

# WebSockets over TLS/SSL
listener 9883
protocol websockets
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/hostname.crt
keyfile /etc/mosquitto/certs/hostname.key
tls_version tlsv1.2

and restart the broker.

Testing TLS V1.2
We can specify the TLS version on the mosquitto command line utils:

[pcortex@pcortex:~]$ mosquitto_pub --cafile ./ca.crt --tls-version tlsv1.2 -h localhost -t "test" -m "mes" -p 8883 -d
Client mosqpub/26994-pcortex sending CONNECT
Client mosqpub/26994-pcortex received CONNACK
Client mosqpub/26994-pcortex sending PUBLISH (d0, q0, r0, m1, 'test', ... (3 bytes))
Client mosqpub/26994-pcortex sending DISCONNECT
[pcortex@pcortex:~]$ mosquitto_pub --cafile ./ca.crt --tls-version tlsv1.1 -h localhost -t "test" -m "m3224" -p 8883 
Error: A TLS error occurred.

As we can see the lower versions of the TLS protocol are now not accepted.
The Websockets client should work without any issues.

This configuration only solves the transport security, not the authentication security. The later can be accomplished by using the username/password process or using client certificates, which is the process that Amazon AWS IoT cloud uses. But those are topics for other posts. Edit: Follow-up at: Client authentication

20 thoughts on “MQTT Mosquitto broker with SSL/TLS transport security

  1. your directive to move the files is to: /etc/mosquitto/CERTS….. but you point the conf file to /etc/mosquitto …(wuthout CERTS) is that ok?

    1. Hi, No, it’s not ok. The path mut be a full path. I’ve corrected the post.
      Thanks for pointing it out, and sorry for the late answer.

  2. Hi, I managed to install and configure Mosquitto with TLS1.2 and on local server works perfect. I need now to go to next step, to have access from the internet to the broker.
    For this I got a CA.crt (bf4fb25c4671fbd3.crt) SSL certificate form (took me 10 minutes with the help form chatting with a representative).
    At this point I am stuck with the next steps, configuring the mosquitto.conf and getting other files (server.key and server.crt).
    Any help will be appreciated,
    Regards, Ovidiu

    1. On the local server, I suppose that self signed certificates where used, with your own CA, right?

      The issue with the ca.crt is the public key for their own certificate authority, so the server certificates for your server must be provided by them. This means that you need to ask a server certificate files from them.

    1. You must not leave blank spaces and blank lines between the protocol definition and port definition, otherwise the broker assumes default ports.

  3. When I try

    mosquitto_sub -h localhost -p 8883 -t “hellomqtt/topic” -d –cafile /etc/mosquitto/certs/ca.crt

    I get

    Error: Connection refused

    Where should I look to see what is wrong (on Ubuntu 16.04)?

    1. It looks like that the broker is not listening at the specified port 8883.
      Just do first the following command: netstat -nap | grep 8883
      and an output/should show that the mosquitto broker is listening at that port:

      tcp 0 0* LISTEN 30970/mosquitto

      If not, there is something wrong at the configuration file. Make sure that there are no blank lines between the listen and protocol configuration lines.

      Hope this helps.

  4. Hi, I’m trying to connect to wss in from a browser(Chrome 62.0.3202.94), but I get the following message:
    mqttws31.min.js:36 WebSocket connection to ‘wss://localhost:9883/mqtt’ failed: Error in connection establishment: net::ERR_INSECURE_RESPONSE

    Is it possible that the error message is caused by the self signed certificate is using SHA-1 instead of SHA-2?


  5. Hi I followed the above step to configure MQTT over TLS/SSL

    listener 8883
    cafile /etc/mosquitto/certs/ca.crt
    certfile /etc/mosquitto/certs/hostname.crt
    keyfile /etc/mosquitto/certs/hostname.key

    but whenever I start mosquito it is throwing following error

    Error: Unknown configuration variable “cafile”.
    Error: Unable to open configuration file.

    Why this is happening? Pleaase help

    I am using 64 bit ubuntu 14.04

    Thanks in advance

  6. Hi,
    I followed all steps from ur guidance, but i didn’t connect with mosquitto server.
    netstat -nap | grep 8883 this time i didn’t get any output.

    When i execute the bellow commands i got issue like Error: Connection refused

    mosquitto_pub –cafile ./ca.crt –tls-version tlsv1.2 -h localhost -t “test” -m “mes” -p 8883 -d
    Error: Connection refused
    mosquitto_pub –cafile ./ca.crt –tls-version tlsv1.1 -h localhost -t “test” -m “m3224” -p 8883
    Error: Connection refused

    I copied ca.crt, saitech.key and saitech.crt files into /etc/mosquitto/certs/ path

    This is my configuration file(Mosquitto.conf)

    listener 1883

    pid_file /var/run/

    persistence true
    persistence_location /var/lib/mosquitto/

    log_dest file /var/log/mosquitto/mosquitto.log

    include_dir /etc/mosquitto/conf.d

    listener 8883

    cafile /etc/mosquitto/ca_certificates/ca.crt
    keyfile /etc/mosquitto/certs/saitech.key
    certfile /etc/mosquitto/certs/saitech.crt
    tls_version tlsv1.2

    pid_file /var/run/
    persistence true
    persistence_location /var/lib/mosquitto/
    log_dest file /var/log/mosquitto/mosquitto.log
    cafile /etc/mosquitto/ca_certificates/ca.crt
    certfile /etc/mosquitto/certs/client.crt
    keyfile /etc/mosquitto/certs/client.key
    require_certificate true

    Could you please give suggestion on this issue.


    1. In your configuration you have a path to a mosquitto log file. What’s in it? It seems something is failing and hece mosquitto is not boundig to the configured port.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.