Configuring TLS in the Mosquitto MQTT broker

sheng chen — Wed, 08 Oct 2025 13:44:13 +0000

Configuring TLS in the Mosquitto MQTT broker involves setting up secure communication between the broker and clients (or bridges) using OpenSSL or a compatible library like wolfSSL. The configuration is primarily defined in the Mosquitto configuration file (mosquitto.conf) and involves specifying certificates, keys, and TLS options to ensure encrypted connections, server authentication, and optionally client authentication. Below are the details of TLS configuration for the Mosquitto broker, covering key settings, their purposes, and practical considerations.
TLS Configuration in Mosquitto Broker
Key Configuration Options in mosquitto.conf
The following settings in the Mosquitto configuration file control TLS behavior for listeners (ports where the broker accepts connections) and bridges (connections to other brokers). These settings can be applied globally or per listener/bridge.

Enabling TLS on a Listener:

Setting: listener [bind_address]

Defines a port for the broker to listen on (e.g., listener 8883 for the standard MQTT TLS port).

TLS Enablement:

require_certificate: If set to true, clients must provide a valid certificate for mutual authentication. Default is false.
use_identity_as_username: If true, uses the client certificate’s Common Name (CN) as the MQTT username. Useful for authentication without passwords.
use_subject_as_username: If true, uses the full client certificate subject as the username.

Example:

listener 8883
cafile /path/to/ca.crt
certfile /path/to/server.crt
keyfile /path/to/server.key
require_certificate true

Certificate and Key Files:

cafile: Path to the Certificate Authority (CA) certificate file used to verify client certificates (required for require_certificate true).
capath: Directory containing CA certificates (alternative to cafile for multiple CAs).
certfile: Path to the broker’s server certificate (required for TLS).
keyfile: Path to the broker’s private key (required for TLS).
keyform: Format of the private key (pem or engine, default is pem).

Example:

cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key

TLS Protocol and Cipher Settings:

tls_version: Specifies the minimum TLS version (e.g., tlsv1.3, tlsv1.2, tlsv1.1). Default is unset, allowing OpenSSL to negotiate the highest supported version.
ciphers: Specifies allowed cipher suites (e.g., TLS_AES_256_GCM_SHA384). Use OpenSSL cipher list format. Default is unset, using OpenSSL defaults.
ciphers_tls1.3: Specific ciphers for TLS 1.3 (if supported by OpenSSL).
Example:

tls_version tlsv1.2
ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256

Pre-Shared Key (PSK) Support:

psk_hint: A hint sent to clients for PSK-based authentication (optional).
psk_file: Path to a file containing PSK identities and keys (format: identity:key in hex).
use_identity_as_username: If true, uses the PSK identity as the MQTT username.
Example:

listener 8883
psk_hint mybroker
psk_file /etc/mosquitto/psk.txt
use_identity_as_username true

Example psk.txt:

client1:1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d

CRL and OCSP:

crlfile: Path to a Certificate Revocation List (CRL) to check for revoked client certificates.
**require_ocsp: If true, enforces OCSP (Online Certificate Status Protocol) validation for client certificates. Default is false.
Example:

crlfile /etc/mosquitto/certs/revoked.crl
require_ocsp false

TLS Engine (Hardware Acceleration):

tls_engine: Specifies an OpenSSL engine for hardware-based cryptography (e.g., pkcs11 for HSMs).
tls_engine_kpass_sha1: SHA1 hash of the key password for the engine (if required).
Example:

tls_engine pkcs11
tls_engine_kpass_sha1 1234567890abcdef

Bridge-Specific TLS Settings:

When configuring a bridge (Mosquitto connecting as a client to another broker), TLS settings are specified under a bridge_ prefix.
Key Settings:

bridge_cafile, bridge_capath: CA certificate(s) to verify the remote broker.
bridge_certfile, bridge_keyfile: Client certificate and key for mutual authentication.
bridge_tls_version: TLS version for the bridge connection.
bridge_psk, bridge_identity: PSK and identity for PSK-based authentication.

Example:

connection mybridge
address remotebroker.com:8883
bridge_cafile /etc/mosquitto/certs/remote_ca.crt
bridge_certfile /etc/mosquitto/certs/client.crt
bridge_keyfile /etc/mosquitto/certs/client.key
bridge_tls_version tlsv1.2

WebSocket TLS:

For WebSocket listeners (protocol websockets), TLS settings are identical to MQTT listeners but applied to the WebSocket port.
Example:

listener 9001
protocol websockets
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key

Implementation Details in Mosquitto Broker
The TLS implementation for the broker is primarily handled in net.c and related files, leveraging OpenSSL for cryptographic operations:

TLS Context Setup: The broker creates an SSL_CTX for each listener with TLS enabled, using settings from mosquitto.conf. It loads certificates and keys via SSL_CTX_use_certificate_file and SSL_CTX_use_PrivateKey_file.
Handshake: For each client connection, an SSL object is created and bound to the socket. The handshake (SSL_accept) verifies client certificates if require_certificate is true.
Data Transfer: Uses SSL_read and SSL_write for encrypted communication, integrated with the broker’s event loop in net.c.
PSK Handling: Implements a PSK callback (SSL_CTX_set_psk_server_callback) to validate client PSKs against the psk_file.
Error Handling: TLS errors are logged using Mosquitto’s logging system, and clients are disconnected on failures (e.g., invalid certificates).

Practical Considerations

Certificate Setup:

Generate certificates using OpenSSL or a CA like Let’s Encrypt.
Example:

openssl req -x509 -newkey rsa:2048 -keyout server.key -out server.crt -days 365 -nodes

Ensure file permissions are restrictive (e.g., chmod 600 server.key).

Security:

Use tls_version tlsv1.2 or tlsv1.3 to avoid deprecated protocols.
Specify secure ciphers to mitigate vulnerabilities (e.g., disable weak ciphers like CBC-based ones).
Enable require_certificate for high-security environments, but ensure clients are configured with valid certificates.

Performance:

TLS handshakes add CPU overhead; consider session resumption for frequent client connections.
Use hardware acceleration (tls_engine) for large-scale deployments.

Testing:

Use tools like mosquitto_sub or mosquitto_pub with --cafile, --cert, and --key to test TLS connections.
Example:

mosquitto_sub -h localhost -p 8883 -t test/topic --cafile ca.crt --cert client.crt --key client.key

Example Full TLS Configuration

conflistener 8883
protocol mqtt
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
tls_version tlsv1.2
require_certificate true
use_identity_as_username true

listener 9001
protocol websockets
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key

connection mybridge

address remotebroker.com:8883
bridge_cafile /etc/mosquitto/certs/remote_ca.crt
bridge_certfile /etc/mosquitto/certs/client.crt
bridge_keyfile /etc/mosquitto/certs/client.key
Debugging TLS Issues

Enable verbose logging with log_type all in mosquitto.conf to capture TLS errors.
Check OpenSSL errors in the Mosquitto log (e.g., /var/log/mosquitto/mosquitto.log).
Use openssl s_client to test the broker’s TLS setup:
bashopenssl s_client -connect localhost:8883 -CAfile ca.crt

Source Reference
These details are based on Mosquitto versions up to 2.0.18, with configuration options documented in man mosquitto.conf and the source code (net.c, security.c). Check the Mosquitto GitHub repository or official documentation for the latest updates.

DEV Community: sheng chen

Configuring TLS in the Mosquitto MQTT broker