How to Enable TLS for a Listener on Port 8883 in HiveMQ

Overview

This article explains how to configure Transport Layer Security (TLS) for an MQTT listener on port 8883 in HiveMQ Self-Managed deployments. TLS provides encrypted communication between MQTT clients and the HiveMQ broker, ensuring secure data transmission.

Prerequisites

Before configuring a TLS listener, ensure you have:

A Java Keystore (JKS format) containing your server certificate and private key .
The keystore password
The private key password (if applicable)
Access to the HiveMQ config.xml file

Configuration Steps

Step 1: Locate the Configuration File

Navigate to your HiveMQ installation directory and open the config.xml file located in the conf folder.

Step 2: Add the TLS TCP Listener

Add a tls-tcp-listener to the listeners section in your config.xml file. Port 8883 is the IANA standard port for secure MQTT.


<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <listeners>
        <tls-tcp-listener>
            <port>8883</port>
            <bind-address>0.0.0.0</bind-address>
            <name>my-secure-tcp-listener</name>
            <tls>
                <keystore>
                    <path>/path/to/the/key/store.jks</path>
                    <password>password-keystore</password>
                    <private-key-password>password-key</private-key-password>
                </keystore>
            </tls>
        </tls-tcp-listener>
    </listeners>
</hivemq>

Step 3: Configure Required Properties

The following properties must be configured :

port: The port used for TCP connections (8883 for secure MQTT)
bind-address: The host IP address on which the listener is bound (default: 0.0.0.0)
name: Optional setting to customize the listener name (default: tls-tcp-listener-{port})
keystore.path: The path to the key store where your certificate and private key are located
keystore.password: The password to open the key store

Step 4: Save and Restart HiveMQ

After adding the configuration, save the config.xml file and restart HiveMQ for the changes to take effect .

Optional TLS Configuration

The tls element supports additional configuration options :

protocols: Enabled TLS protocol versions (default: TLSv1.3, TLSv1.2)
cipher-suites: Enabled cipher suites for encryption
client-authentication-mode: How HiveMQ authenticates client certificates (NONE, OPTIONAL, or REQUIRED)
handshake-timeout: Milliseconds for SSL connection establishment (default: 10000)
concurrent-handshake-limit: Maximum number of simultaneous SSL handshakes (default: -1 for unlimited)
native-ssl: Defines whether HiveMQ uses BoringSSL for the TLS implementation

Runtime Key Store Management

HiveMQ reloads key stores and trust stores during runtime . You don't need to restart HiveMQ when you add or remove client certificates from a trust store or change a server certificate in the key store . If the same master password is used, you can replace the key store or trust store file with no downtime .

Verification

Using the Health API

After configuration, verify the listener is running correctly by checking the Health API endpoint (https://docs.hivemq.com/hivemq/latest/user-guide/health-api.html).

/api/v1/health/mqtt/<listener-name>

The MQTT health component provides information about MQTT listeners and their connection state. If a TLS-related failure occurs, the listener reports a DEGRADED health status.

Troubleshooting

Common Issues

Keystore not found: Verify the path to the keystore file is correct and accessible by the HiveMQ process
Incorrect passwords: Ensure the keystore password and private key password are correct
Certificate issues: Verify your certificate is valid and not expired
Port conflicts: Ensure port 8883 is not already in use by another application

Prevention and Best Practices

Store keystore files in a secure location with appropriate file permissions
Use strong passwords for keystores and private keys
Regularly update certificates before expiration
Monitor the Health API for listener status
Test TLS connections after configuration changes
Consider using client certificate authentication for additional security

Additional Resources

For detailed information on creating a self-signed Java Keystore for testing purposes, see the HiveMQ documentation.

For information on cipher suite preference configuration, see the Cipher Suite Preference section in the HiveMQ documentation.

Related Topics: HiveMQ Configuration, MQTT Security, TLS/SSL, Listener Configuration

Product: HiveMQ Self-Managed