Skip to content
  • There are no suggestions because the search field is empty.

How-To : Set up SSL/TLS for HighByte MQTT Broker with a MQTT Client

What Does This Article Cover?

This article provides step-by-step instructions on how to configure SSL/TLS for securing communications between a HighByte MQTT broker and an MQTT client. We’ll use OpenSSL to generate a Certificate Authority (CA), server, and client certificates. This setup will ensure that the communication between the broker and client is encrypted and authenticated.

What is in this article 


    1. Project Import
    2. Sources Files to MQTT
    3. Writing Files from MQTT
    4. Summary

Prerequisites

  1. A working installation of OpenSSL.
  2. Access to the HighByte MQTT broker configuration and the MQTT client (e.g., MQTT Explorer).
  3. Basic knowledge of command-line operations.

Step 1: Generate a Certificate Authority (CA)

Why?

The CA certificate is the root of trust for all other certificates. It is used to sign the server and client certificates, ensuring that both the broker and the client can trust each other.

Commands:

1. Generate the CA Private Key:

openssl genpkey -algorithm RSA -out ca-key.pem

Explanation: This command creates a private key for the CA, which is necessary to sign other certificates. The RSA algorithm is commonly used for generating keys.

2. Generate the CA Certificate 

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

  • Explanation: This command creates a self-signed CA certificate (ca-cert.pem). The -x509 flag indicates that this certificate will be used for signing other certificates. The -days 365 option sets the certificate's validity to one year.

  • Common Name (CN): When prompted, enter something like HighByte Local CA. This identifies the CA.

 

Step 2: Generate the Server Certificate

Why?

The server certificate is used to secure communications on the broker side. The server certificate must be signed by the CA to ensure that it is trusted by the client.

Commands:

1.Create a Configuration File for SAN (Subject Alternative Names)

         Create a file named san.cnf with the following content:

[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
CN = localhost

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
IP.1 = 127.0.0.1

Explanation: The san.cnf file configures the certificate's Common Name (CN) and SAN fields. The SAN allows the certificate to be valid for multiple names and IP addresses (localhost and 127.0.0.1), which are commonly used in local testing environments.

Note: If HighByte and the MQTT client are on different IP addresses:

If HighByte and the MQTT client are on different IP addresses, you need to add the actual IP address of the MQTT broker to the SAN configuration. For example, if the MQTT broker is hosted at 192.168.1.10, modify the san.cnf file as follows:

[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
CN = 192.168.1.10

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
IP.1 = 127.0.0.1
IP.2 = 192.168.1.10

Explanation: The IP.2 entry in the SAN field allows the certificate to be valid for the broker's IP address (192.168.1.10). The CN is also set to the broker’s IP address, ensuring that the client can connect using this address.

2. Generate the Server Private Key:

openssl genpkey -algorithm RSA -out server-key.pem

Explanation: This command creates the server's private key, which is used to decrypt messages encrypted with the public key.

3.Generate the Server Certificate Signing Request (CSR):

openssl req -new -key server-key.pem -out server.csr -config san.cnf

Explanation: The CSR (server.csr) is created using the server's private key and the san.cnf configuration. The CSR is a request for a certificate and contains the public key and the distinguished name (including the CN).

4. Sign the Server CSR with the CA:

openssl x509 -req -in server.csr -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem -days 365 -extensions v3_req -extfile san.cnf

Explanation: This command signs the server CSR with the CA's private key, generating a server certificate (server-cert.pem). The -extensions v3_req and -extfile san.cnf ensure that the SANs are included in the certificate.

 

Step 3: Generate the Client Certificate

Why?

The client certificate authenticates the client to the broker, ensuring that only trusted clients can connect to the broker.

Commands:

1. Generate the Client Private Key:

openssl genpkey -algorithm RSA -out client-key.pem
  • Explanation: This command creates the client's private key.

2. Generate the Client Certificate Signing Request (CSR):

openssl req -new -key client-key.pem -out client.csr

  • Explanation: The client CSR is created using the client's private key.

  • Common Name (CN): Enter something descriptive like HighByte MQTT Client. This CN identifies the client.

3. Sign the Client CSR with the CA:

openssl x509 -req -in client.csr -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem -days 365 -sha256
  • Explanation: This command signs the client CSR with the CA, creating the client certificate (client-cert.pem).

Step 4: Configure the HighByte MQTT Broker

1.Upload the CA Certificate:

  • Navigate to certificates in HighByte and upload the ca-cert.pem and the ca-key.pem
  • Explanation: The CA certificate is used by HighByte to verify the server and client certificates.

2. Upload the Server Certificate/Key Pair: 

  • Navigate to certificatesd in HighByte and upload the server-cert.pem and server-key.pem
  • Explanation: The server certificate and key secure communications and authenticate the broker to clients.

3. Update HighByte MQTT Settings

  • Click on settings, under MQTT Broker settings click the pencil
  • Turn on the Use SSL Flag
    • Delete the WS connection, I did this in testing to solve an error, not sure if necessary, need further testingUnder Certificate Alias  please select the ca_cert you uploaded in step 4.1





  • TroubleShooting

    Common Errors:

    • Hostname/IP does not match certificate's altnames: Ensure that the server certificate’s SAN field includes the hostname or IP used to connect.
    • Handshake failures: Verify that the correct certificates are being used, and check the MQTT broker logs for more details.
    OpenSSL Testing:

  • You can use OpenSSL to manually test the connection 
  • openssl s_client -connect <broker-ip>:1885 -CAfile ca-cert.pem

     

     
  • Explanation: This command attempts to establish a TLS connection to the broker and can help diagnose issues with the certificates or TLS configuration. 

Summary

By following these steps, you should have a secure SSL/TLS setup for your HighByte MQTT broker and MQTT client. This setup ensures that both the broker and the client can trust each other, and all communications are encrypted.

Additional Resources