TLS/SSL Configuration - MQTT Explorer

TLS/SSL encryption protects your MQTT connections by encrypting all data in transit, including credentials and message payloads. MQTT Explorer supports various certificate configurations for secure broker connections.

Why Use TLS/SSL?

Credential Protection

Encrypts username and password during authentication to prevent credential theft.

Data Privacy

Encrypts all MQTT messages in transit, protecting sensitive data from eavesdropping.

Broker Authentication

Verifies the broker’s identity to prevent man-in-the-middle attacks.

Client Authentication

Optionally authenticates clients using certificates for mutual TLS (mTLS).

Never send credentials or sensitive data over unencrypted connections in production environments.

Quick Start

Enable TLS

In the connection settings, toggle Encryption (tls) to enable TLS/SSL.

Adjust Port

Change the port to your broker’s TLS port (typically 8883 for MQTT or 8443 for WebSocket).

Configure Certificate Validation

Keep Validate certificate enabled for production (verifies against system CAs)
Disable for self-signed certificates in testing

Connect

Click Connect to establish an encrypted connection.

TLS Configuration Options

Basic TLS Settings

encryption

boolean

default:false

Enable TLS/SSL encryption for the connection.When enabled:

Connection uses TLS encryption (mqtts:// or wss://)
Port typically changes to 8883 (MQTT) or 8443 (WebSocket)
All data is encrypted in transit

// Connection with TLS enabled
{
  protocol: "mqtt",
  host: "mqtt.example.com",
  port: 8883,
  encryption: true,
  certValidation: true
}

certValidation

boolean

default:true

Validate the broker’s certificate against trusted certificate authorities.When enabled (recommended for production):

Verifies broker certificate is signed by a trusted CA
Validates certificate hostname matches connection host
Checks certificate expiration
Prevents man-in-the-middle attacks

When disabled (testing only):

Accepts self-signed certificates
Accepts expired certificates
Accepts hostname mismatches
Bypasses CA validation

Only disable certificate validation for testing with self-signed certificates. In production, always use properly signed certificates and keep validation enabled.

Certificate Types

MQTT Explorer supports three types of certificates for different security scenarios:

Server Certificate (CA Certificate)

A self-signed or custom CA certificate to verify the broker’s identity.When to use:

Broker uses a self-signed certificate
Broker uses a certificate from a private/internal CA
Additional security by pinning the exact CA certificate

Configuration:

Click Advanced → Certificates
Upload Server Certificate (CA)
Keep Validate certificate enabled

Certificate format: PEM-encoded X.509 certificate

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL0UG+mRmrLMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
...
-----END CERTIFICATE-----

When you provide a CA certificate, MQTT Explorer trusts this specific CA in addition to system CAs.

Client Certificate (Mutual TLS)

A certificate that identifies this MQTT client to the broker.When to use:

Broker requires client certificate authentication (mutual TLS/mTLS)
Enhanced security with certificate-based client authentication
IoT device authentication

Configuration:

Click Advanced → Certificates
Upload Client Certificate (public certificate)
Upload Client Key (private key)

Certificate format: PEM-encoded X.509 certificate Key format: PEM-encoded private key (RSA or EC)

# Client Certificate
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL0UG+mRmrLMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
...
-----END CERTIFICATE-----

# Client Key
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7VJTUt9Us8cKj
...
-----END PRIVATE KEY-----

Keep the client key secure. Never share or commit private keys to version control.

Client Key

The private key corresponding to the client certificate.Requirements:

Must match the client certificate
Should not be password-protected (or decrypt first)
PEM format only

Supported key types:

RSA (2048-bit or 4096-bit)
Elliptic Curve (EC) keys

Security considerations:

Store keys securely with restricted file permissions
Never commit keys to version control
Use separate keys for each client
Rotate keys periodically

Certificate Configuration

Uploading Certificates

Open Certificate Settings

In the connection dialog:

Select your connection profile
Click Advanced button
Click Certificates button

Select Certificate File

For each certificate type:

Click the file selection button
Choose your PEM-format certificate file
The certificate name and preview will appear

Verify Certificate

Check that:

Certificate name is displayed correctly
File size is reasonable (typically < 10KB)
Certificate format is PEM (starts with -----BEGIN CERTIFICATE-----)

Save Configuration

Click Back then Save to persist the certificate configuration.

Certificate Formats

MQTT Explorer accepts certificates in PEM format only. If your certificates are in a different format, convert them first:

# Convert DER certificate to PEM
openssl x509 -inform der -in certificate.der -out certificate.pem

Common TLS Configurations

Public CA Certificate (Let’s Encrypt, DigiCert)

Enable TLS

Toggle Encryption (tls) on

Set Port

Change port to 8883 (or your broker’s TLS port)

Validate Certificate

Keep Validate certificate enabled

Connect

No additional certificates needed - system CA bundle is used

Example: Connecting to HiveMQ Cloud or other commercial brokers with public certificates.

Self-Signed Certificate

Enable TLS

Toggle Encryption (tls) on

Disable Validation (Option 1)

Toggle Validate certificate off

This bypasses all certificate validation. Only use for testing.

Upload CA (Option 2 - Recommended)

Keep Validate certificate enabled
Click Advanced → Certificates
Upload your self-signed certificate as Server Certificate (CA)
This validates against your specific certificate

Connect

Connect with TLS enabled and your chosen validation method

Example: Testing with Mosquitto using a self-signed certificate.

Mutual TLS (mTLS)

For brokers requiring client certificate authentication:

Enable TLS and Validation

Toggle Encryption (tls) on
Keep Validate certificate enabled
Set port to 8883

Upload Client Certificate

Click Advanced → Certificates:

Upload Client Certificate (your certificate)
Upload Client Key (your private key)

Optional: Upload CA

If broker uses a self-signed or private CA:

Upload Server Certificate (CA)

Connect

Both client and server will authenticate using certificates

Example: IoT platforms requiring device certificates (AWS IoT Core, Azure IoT Hub).

Generating Self-Signed Certificates

For testing purposes, you can generate self-signed certificates:

# Generate CA private key
openssl genrsa -out ca.key 4096

# Generate CA certificate (self-signed)
openssl req -new -x509 -days 365 -key ca.key -out ca.crt \
  -subj "/CN=MQTT Test CA"

# This ca.crt is your "Server Certificate (CA)"

For production, use certificates from a trusted CA like Let’s Encrypt or your organization’s PKI infrastructure.

Browser Mode Considerations

When running MQTT Explorer in browser mode, certificate handling differs:

WebSocket TLS (wss://)

protocol

string

default:"ws"

Use ws protocol for WebSocket connections (required in browser mode)

Non-encrypted: ws://broker.example.com:8080
TLS encrypted: wss://broker.example.com:8443

Enable Encryption (tls) to use wss://

Certificate Limitations

Browser security restrictions limit certificate handling:

Browsers validate certificates using their own CA store
Cannot upload custom CA certificates (browser security policy)
Cannot disable certificate validation (browser restriction)
Client certificates require browser’s certificate manager

Workaround: Deploy MQTT Explorer behind a reverse proxy with proper TLS termination.

Reverse Proxy Setup

For browser mode, use a reverse proxy to handle TLS:

# nginx configuration
server {
    listen 443 ssl http2;
    server_name mqtt-explorer.example.com;
    
    # Let's Encrypt certificates
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    
    # Modern TLS configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    
    # WebSocket support
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Troubleshooting

Certificate validation failed

Symptoms: Connection fails with certificate verification errorCommon causes:

Self-signed certificate without proper configuration
Expired certificate
Hostname mismatch
Untrusted CA

Solutions:

For testing: Disable certificate validation (not recommended for production)
For production: Upload the CA certificate as “Server Certificate (CA)”

Verify certificate:

# Check certificate details
openssl x509 -in certificate.pem -text -noout

# Test connection
openssl s_client -connect broker.example.com:8883 -CAfile ca.crt

Check hostname: Ensure the hostname in your connection matches the certificate CN/SAN

Client certificate not working

Symptoms: Connection refused, authentication error with mTLSCommon causes:

Client certificate and key don’t match
Key is password-protected
Certificate not signed by broker’s trusted CA
Wrong certificate format

Solutions:

Verify certificate and key match:

# Compare modulus (should be identical)
openssl x509 -noout -modulus -in client.crt | openssl md5
openssl rsa -noout -modulus -in client.key | openssl md5

Remove password from key:

openssl rsa -in encrypted.key -out decrypted.key

Check certificate chain: Ensure client cert is signed by CA trusted by broker
Verify PEM format: Certificate should start with -----BEGIN CERTIFICATE-----

Hostname mismatch error

Symptoms: “Hostname does not match certificate CN” errorCauses:

Connecting via IP address but certificate is for hostname
Certificate CN doesn’t match connection hostname
Missing Subject Alternative Name (SAN) entries

Solutions:

Use correct hostname: Connect using the name in the certificate

Add SAN entries: Regenerate certificate with SAN:

# Create config file with SAN
cat > san.cnf <<EOF
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req

[req_distinguished_name]
CN = broker.example.com

[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = broker.example.com
DNS.2 = mqtt.example.com
IP.1 = 192.168.1.100
EOF

openssl req -new -x509 -key ca.key -out ca.crt -config san.cnf

Disable validation: For testing only, disable certificate validation

Wrong certificate format

Symptoms: “Invalid certificate” error, upload failsCauses:

Certificate is not in PEM format
File is corrupted or truncated
File contains wrong data

Solutions:

Verify PEM format:

# Should show certificate details
openssl x509 -in certificate.pem -text -noout

Convert from DER:

openssl x509 -inform der -in cert.der -out cert.pem

Check file content: Ensure file starts with -----BEGIN CERTIFICATE-----
Re-export certificate: Export from source and try again

TLS handshake timeout

Symptoms: Connection times out during TLS handshakeCauses:

TLS version mismatch
Cipher suite incompatibility
Network/firewall blocking TLS traffic
Broker not listening on TLS port

Solutions:

Verify broker is listening:

# Check port
telnet broker.example.com 8883

# Test TLS handshake
openssl s_client -connect broker.example.com:8883

Check TLS version: Ensure broker supports TLS 1.2 or 1.3
Firewall rules: Verify port 8883 is open
Broker logs: Check for TLS errors

Security Best Practices

Always Use TLS in Production

Never transmit credentials or sensitive data over unencrypted connections.

Validate Certificates

Keep certificate validation enabled except for testing with self-signed certificates.

Use Strong Keys

Use 2048-bit or 4096-bit RSA keys, or 256-bit EC keys for adequate security.

Rotate Certificates

Renew certificates before expiration and rotate keys periodically (annually).

Secure Private Keys

Protect client private keys with file permissions (chmod 600) and never commit to version control.

Monitor Expiration

Set up alerts for certificate expiration at least 30 days in advance.

Next Steps

Authentication

Configure username/password authentication to work with your TLS setup.

Connection Setup

Learn about other connection configuration options.

Security Policy

Review MQTT Explorer’s complete security policy and best practices.

Environment Variables

Configure TLS settings using environment variables for server deployments.

Get Started

Deployment

Features

Guides

Advanced

​Why Use TLS/SSL?

Credential Protection

Data Privacy

Broker Authentication

Client Authentication

​Quick Start

​TLS Configuration Options

​Basic TLS Settings

​Certificate Types

​Certificate Configuration

​Uploading Certificates

​Certificate Formats

​Common TLS Configurations

​Public CA Certificate (Let’s Encrypt, DigiCert)

​Self-Signed Certificate

​Mutual TLS (mTLS)

​Generating Self-Signed Certificates

​Browser Mode Considerations

​WebSocket TLS (wss://)

​Certificate Limitations

​Reverse Proxy Setup

​Troubleshooting

​Security Best Practices

Always Use TLS in Production

Validate Certificates

Use Strong Keys

Rotate Certificates

Secure Private Keys

Monitor Expiration

​Next Steps

Authentication

Connection Setup

Security Policy

Environment Variables

Build docs developers (and LLMs) love

Why Use TLS/SSL?

Quick Start

TLS Configuration Options

Basic TLS Settings

Certificate Types

Certificate Configuration

Uploading Certificates

Certificate Formats

Common TLS Configurations

Public CA Certificate (Let’s Encrypt, DigiCert)

Self-Signed Certificate

Mutual TLS (mTLS)

Generating Self-Signed Certificates

Browser Mode Considerations

WebSocket TLS (wss://)

Certificate Limitations

Reverse Proxy Setup

Troubleshooting

Security Best Practices

Next Steps