SSL/TLS Support in EMQX Edge

TLS (Transport Layer Security) and its predecessor, SSL (Secure Sockets Layer), are cryptographic protocols that provide secure communication over networks. EMQX Edge supports TLS to ensure data confidentiality, integrity, and authentication for MQTT connections and bridging.

Note: SSL is outdated and no longer considered secure. EMQX Edge supports only the modern TLS protocol.

Overview of TLS Benefits

TLS enhances communication security with the following core capabilities:

• Encryption – Encrypts all transmitted data to prevent unauthorized access and eavesdropping.
• Authentication – Uses digital certificates to verify the identities of clients and servers.
• Data Integrity – Ensures that messages are not altered during transmission.
• Flexibility – Supports a variety of encryption algorithms and is widely compatible across platforms.
• Trust Model – Establishes trust through Certificate Authorities (CAs), enabling secure identity verification.

One-Way vs. Two-Way TLS Authentication

EMQX Edge supports both one-way and two-way (mutual) authentication models depending on security requirements:

Feature	One-Way Authentication	Two-Way Authentication
Use Case	Common in HTTPS/web access	High-security environments (e.g., banking)
How It Works	Server provides certificate; client verifies	Both client and server exchange and verify certificates
Client Verification	Not performed	Client identity is verified
Setup Complexity	Simple configuration	More complex setup and certificate management
Security Level	Moderate	High

Generate Server and Client Certificates with OpenSSL

To enable TLS authentication, you must generate the necessary certificates.

Step 1: Create a Self-Signed Certificate Authority (CA)

1. Run the following command to generate an RSA private key

openssl genrsa -out ca.key 2048

2. Generate a Self-Signed CA Certificate:

openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.pem

During the certificate generation process, OpenSSL will prompt you to enter the certificate's subject information, such as Country, State/Province, City, Organization, Organizational Unit, Common Name (the name of the CA), and Email Address. Enter the relevant information as prompted.

Step 2: Generate a Server Certificate

1. Generate an RSA private key for the server:

openssl genrsa -out server.key 2048

2. Use the server private key to create a Certificate Signing Request (CSR):

openssl req -new -key ./server.key -out server.csr

3. Use the self-signed CA certificate generated in Step 1 and the private key to issue a Server Certificate:

openssl x509 -req -in ./server.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out server.pem -days 3650 -sha256

Step 3: Generate a Client Certificate (For Two-Way Authentication)

The process of generating a client certificate is similar to generating a server certificate:

# Generate client private key
openssl genrsa -out client-key.pem 2048

# Generate CSR for client
openssl req -new -key client-key.pem -out client.csr

# Sign the client certificate with the CA
openssl x509 -req -days 3650 -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out client.pem

Configure Two-Way Authentication for Bridging in EMQX Edge

EMQX Edge provides configuration options for two-way authentication to bridge to a remote server. To enable TLS for bridging or client connections, edit the nanomq.conf configuration file, as shown in the example below:

# nanomq.conf
...
bridges.mqtt.emqx1 {
...
# # Ssl config ##
     ssl {
        # # SSl key password
        # # String containing the user's password. Only used if the private keyfile
        # # is password-protected.
        # #
        # # Value: String
        key_password = "yourpass"
        # # SSl keyfile
        # # Path of the file containing the client's private key.
        # #
        # # Value: File
        keyfile = "/etc/certs/key.pem"
        # # Ssl cert file
        # # Path of the file containing the client certificate.
        # #
        # # Value: File
        certfile = "/etc/certs/cert.pem"
        # # Ssl ca cert file
        # # Path of the file containing the server's root CA certificate.
        # #
        # # Value: File
        cacertfile = "/etc/certs/cacert.pem"
    }
...

• keyfile: Path to the client's private key file.
• certfile: Path to the client certificate.
• cacertfile: Path to the CA certificate used to validate the server.

This configuration enables secure TLS communication between EMQX Edge and remote MQTT brokers, supporting both one-way and two-way authentication as needed.