Setup PKI for the MQTT Broker

If you want to use MQTT over TLS (MQTTS) or Secure Web Socket (WSS) you need to setup a Public Key Infrastructure (PKI).

Read the blog article about secure communication in IoT to learn more about encryption and certificates.

Structure overview

The Public Key Infrastructure for HiveMQ consists of two Java Key Stores (JKS):

• Keystore: The Keystore contains the HiveMQ certificate and private keys. This store must be confidential, since anyone with access to it could generate valid client certificates and read or send messages in your MQTT infrastructure.
• Truststore: The Truststore contains all the clients public certificates. HiveMQ uses it to verify the authenticity of the connections.

Before you begin

You need to have the following tools installed:

• OpenSSL. If you are using Windows, you can install it with Chocolatey.
• Java

Create a Keystore

Open a terminal and run the following command:

keytool -genkey -keyalg RSA -alias hivemq -keystore hivemq.jks -storepass <password> -validity <days> -keysize 4096 -dname "CN=united-manufacturing-hub-mqtt" -ext "SAN=IP:127.0.0.1"

Replace the following placeholders:

• <password>: The password for the keystore. You can use any password you want.
• <days>: The number of days the certificate should be valid.

The command runs for a few minutes and generates a file named hivemq.jks in the current directory, which contains the HiveMQ certificate and private key.

If you want to explore the contents of the keystore, you can use Keystore Explorer.

Generate client certificates

Open a terminal and create a directory for the client certificates:

mkdir pki

Follow these steps for each client you want to generate a certificate for.

1. Create a new key pair:

   openssl req -new -x509 -newkey rsa:4096 -keyout "pki/<servicename>-key.pem" -out "pki/<servicename>-cert.pem" -nodes -days <days> -subj "/CN=<servicename>"
   

2. Convert the certificate to the correct format:

   openssl x509 -outform der -in "pki/<servicename>-cert.pem" -out "pki/<servicename>.crt"
   

3. Import the certificate into the Truststore:

   keytool -import -file "pki/<servicename>.crt" -alias "<servicename>" -keystore hivemq-trust-store.jks -storepass <password>
   

Replace the following placeholders:

• <servicename> with the name of the client. Use the service name from the Network > Services tab in UMHLens / OpenLens.
• <days> with the number of days the certificate should be valid.
• <password> with the password for the Truststore. You can use any password you want.

Import the PKI into the United Manufacturing Hub

First you need to encode in base64 the Keystore, the Truststore and all the PEM files. Use the following script to encode everything automatically:

• Windows
• macOS/Linux

Get-ChildItem .\ -Recurse -Include *.jks,*.pem | ForEach-Object {
    $FileContent = Get-Content $_ -Raw
    $fileContentInBytes = [System.Text.Encoding]::UTF8.GetBytes($FileContent)
    $fileContentEncoded = [System.Convert]::ToBase64String($fileContentInBytes)
    $fileContentEncoded > $_".b64"
    Write-Host $_".b64 File Encoded Successfully!"
}

find ./ -regex '.*\.jks\|.*\.pem' -exec openssl base64 -A -in {} -out {}.b64 \;

You could also do it manually with the following command:

openssl base64 -A -in <filename> -out <filename>.b64

Now you can import the PKI into the United Manufacturing Hub. To do so:

1. Open UMHLens / OpenLens.
2. Navigate to Helm > Releases.
3. Select the united-manufacturing-hub release.
4. Click the Upgrade button.
5. Find the _000_commonConfig.infrastructure.mqtt.tls section.
6. Update the value of the keystoreBase64 field with the content of the hivemq.jks.b64 file and the value of the keystorePassword field with the password you used for the keystore.
7. Update the value of the truststoreBase64 field with the content of the hivemq-trust-store.jks.b64 file and the value of the truststorePassword field with the password you used for the truststore.
8. Update the value of the <servicename>.cert field with the content of the <servicename>-cert.pem.b64 file and the value of the <servicename>.key field with the content of the <servicename>-key.pem.b64 file.
9. Click the Upgrade button to apply the changes.

What’s next

• Learn more about HiveMQ’s TLS configuration in the HiveMQ documentation.