Last updated: 2026-02-13

Mosquitto TLS/SSL Configuration Guide

This guide provides recommended TLS/SSL settings for Eclipse Mosquitto MQTT broker to encrypt connections between clients and the broker. Securing MQTT with TLS is essential for IoT deployments where devices transmit sensitive telemetry and control data.

Prerequisites

Eclipse Mosquitto 2.0 or later
OpenSSL 1.1.1 or later
SSL certificates (server certificate, private key, and CA certificate)

Certificate Setup

Place your certificates in a dedicated directory:

mkdir -p /etc/mosquitto/ssl
chmod 750 /etc/mosquitto/ssl
chown mosquitto:mosquitto /etc/mosquitto/ssl

cp server.crt /etc/mosquitto/ssl/server-cert.pem
cp server.key /etc/mosquitto/ssl/server-key.pem
cp ca.crt /etc/mosquitto/ssl/ca.pem

chmod 640 /etc/mosquitto/ssl/*.pem
chown mosquitto:mosquitto /etc/mosquitto/ssl/*.pem

Listener TLS Configuration

Configure a TLS-encrypted listener in mosquitto.conf. The standard MQTT-over-TLS port is 8883.

Basic TLS Listener

# TLS listener on port 8883
listener 8883

# Certificate files
cafile /etc/mosquitto/ssl/ca.pem
certfile /etc/mosquitto/ssl/server-cert.pem
keyfile /etc/mosquitto/ssl/server-key.pem

# TLS protocol version
tls_version tlsv1.2

# Cipher suites (OpenSSL format)
ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305

# TLS 1.3 cipher suites
ciphers_tls1.3 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

Configuration Explained

listener 8883 -- Opens a listener on the standard MQTTS port.
tls_version tlsv1.2 -- Sets the minimum TLS protocol version. Mosquitto 2.0 with OpenSSL 1.1.1+ supports both TLS 1.2 and TLS 1.3.
ciphers -- OpenSSL cipher string for TLS 1.2 connections.
ciphers_tls1.3 -- OpenSSL ciphersuites string for TLS 1.3 connections.

Client Certificate Authentication

To require clients to present a TLS certificate (mutual TLS), add these settings to the TLS listener:

require_certificate true
use_identity_as_username true

require_certificate true -- Clients must present a valid certificate signed by the CA in cafile.
use_identity_as_username true -- Uses the certificate's Common Name (CN) as the MQTT username, removing the need for password-based authentication.

Multiple Listeners

You can run both a plaintext listener (for local trusted networks) and a TLS listener simultaneously:

# Plaintext listener on localhost only
listener 1883 127.0.0.1
allow_anonymous true

# TLS listener on all interfaces
listener 8883
cafile /etc/mosquitto/ssl/ca.pem
certfile /etc/mosquitto/ssl/server-cert.pem
keyfile /etc/mosquitto/ssl/server-key.pem
tls_version tlsv1.2
ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305
ciphers_tls1.3 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

WebSocket TLS

Mosquitto can serve MQTT over WebSockets with TLS for browser-based clients:

listener 8884
protocol websockets

cafile /etc/mosquitto/ssl/ca.pem
certfile /etc/mosquitto/ssl/server-cert.pem
keyfile /etc/mosquitto/ssl/server-key.pem
tls_version tlsv1.2
ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305

Complete Configuration

# Per-listener settings
per_listener_settings true

# Plaintext listener on localhost only
listener 1883 127.0.0.1
allow_anonymous true

# TLS listener on port 8883
listener 8883
cafile /etc/mosquitto/ssl/ca.pem
certfile /etc/mosquitto/ssl/server-cert.pem
keyfile /etc/mosquitto/ssl/server-key.pem
tls_version tlsv1.2
ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305
ciphers_tls1.3 TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
require_certificate false

# Password file for TLS listener
password_file /etc/mosquitto/passwd

Client Connections

mosquitto_pub / mosquitto_sub

mosquitto_pub -h mqtt.example.com -p 8883 \
    --cafile /path/to/ca.pem \
    -t "test/topic" -m "Hello TLS"

mosquitto_sub -h mqtt.example.com -p 8883 \
    --cafile /path/to/ca.pem \
    -t "test/topic"

With client certificates (mutual TLS):

mosquitto_pub -h mqtt.example.com -p 8883 \
    --cafile /path/to/ca.pem \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -t "test/topic" -m "Hello mTLS"

Python (paho-mqtt)

import paho.mqtt.client as mqtt
import ssl

client = mqtt.Client()
client.tls_set(
    ca_certs="/path/to/ca.pem",
    tls_version=ssl.PROTOCOL_TLS_CLIENT
)
client.connect("mqtt.example.com", 8883)

Verification

Test the TLS connection with openssl:

openssl s_client -connect mqtt.example.com:8883

Verify the port is listening:

ss -tlnp | grep 8883

Test publish and subscribe over TLS:

mosquitto_sub -h mqtt.example.com -p 8883 --cafile /path/to/ca.pem -t "test/#" &
mosquitto_pub -h mqtt.example.com -p 8883 --cafile /path/to/ca.pem -t "test/hello" -m "works"

Check Mosquitto logs:

grep -i tls /var/log/mosquitto/mosquitto.log