Cirrus Link Website
Contact Us (Sales/Support)
Forum
Chariot MQTT Server Documentation
Cirrus Link Modules Docs for Ignition 8.x
Ignition User Manual
Knowledge Base Articles
Inductive University
Forum
MQTT Distributor can be enabled to use TLS to encrypt the communication between MQTT clients. This is useful if MQTT Distributor is used on a public network. Since MQTT communications are not encrypted by default, enabling TLS is highly recommended on a public network.
As of module release version 3.4.7, the Cirrus Link MQTT Distributor module is capable of reusing the existing Ignition web server SSL certificates to secure your MQTT communication. This is the recommended process to secure your MQTT communication using SSL/TLS. If using modules versioned before 3.4.7, the details here will help you through this process.
Follow the steps outlined here to SSL enable the Ignition Web Server.
Once the Ignition Web Server has been SSL enabled, enable SSL/TLS for MQTT Distributor by checking the "Enable TLS" configuration setting under Config→MQTT Distributor→Settings→General→TLS Settings. Click Save to confirm the configuration update.
Once TLS has been enabled for MQTT Distributor, the only change required* for MQTT Engine and MQTT Transmission to connect to Distributor over SSL/TLS, is to update the MQTT Server URL. Update the following MQTT Server URL configuration settings with the appropriate MQTT Server URL for your environment. For example, 'ssl://mqttserver:8883'
SSL/TLS Configuration Settings:
The screenshot below shows MQTT Transmission configured for SSL/TLS. Configure MQTT Engine to use SSL/TLS in the same way.
At this point, MQTT Engine and MQTT Transmission should show they're connected to MQTT Distributor over SSL/TLS.
If running pre-3.4.7 modules, your Ignition web server is not SSL/TLS enabled, you're using self-signed certificates or the default workflow above did not work as expected, read on to see notes and variations on the standard process for enabling SSL/TLS.
This step should only be necessary if you're running pre-3.4.7 modules. The steps below will show how to create a Java keystore (JKS) containing all appropriate certificates and how to configure MQTT Distributor to use this keystore.
If running pre-3.4.7 modules and your Ignition web server is SSL/TLS enabled, you can create the necessary Java keystore (JKS) file from the existing Ignition keystore (<Ignition_Install>\webserver\ssl.pfx). This can be done easily using the KeyStore Explorer tool to convert the Ignition keystore of type PKCS #12 to a Java keystore of type JKS. The details here will help you through this process.
If running pre-3.4.7 modules and your Ignition web server is not SSL/TLS enabled, you will need to create a Java keystore from scratch using the KeyStore Explorer tool. The details here will help you through this process.
If using self-signed certificates in your environment, the steps to enable SSL/TLS are identical to the default workflow with the additional requirement that the certificate chain (aka. "chain-of-trust") be available to MQTT Engine and Transmission. When using self-signed certificates, the required CA certificates are not known to MQTT clients by default as they would be if the certificate was generated by a real CA and the CA certificate was provided by Java's default keystore. Therefore, MQTT Engine and Transmission must be configured to use the appropriate certificate chain.
The certificate chain (aka. "chain-of-trust") is a collection of the public root CA (Certificate Authority) certificate and any/all public intermediate CA certificates between the root and the CA that issued the certificate. If there are no intermediate CAs, then the chain is made up of only the public root CA certificate. You will need to configure MQTT Engine and Transmission to trust these CAs by adding their certificates under MQTT Engine and MQTT Transmission configuration. If a single certificate, move to the next step to upload and configure this certificate. If more than one certificate makes up the certificate chain, you will need to copy the contents of each certificate into a single file (in x509 PEM format; give it a name like 'ca-chain.cert.pem') and move to the next step to upload then configure this certificate.
To upload the certificate chain (aka. "chain-of-trust") to MQTT Engine and MQTT Transmission, launch the Ignition Web Portal, navigate to the "Servers" tab in the module configuration for each module, click on the "Certificates" tab and click 'Create new Certificate' to bring up the creation UI. Next, choose the certificate to upload, give it a friendly name like 'CaChain' and click 'Save'. The two screenshots below show configuration specific to MQTT Transmission. Configure MQTT Engine certificates in the same way.
Associate the certificate just uploaded to each module by setting the 'CA Certificate File' configuration setting to be equal to the certificate created. Click 'Save'.
MQTT Engine and Transmission should now show connected to Distributor over SSL/TLS. If the connection is unsuccessful, review the steps in the default workflow to ensure they were completed successfully.
The first step to securing MQTT communication is to get a certificate from a certificate authority (CA). There are many available such as Verisign, Thawte and RapidSSL. There are also a number of other certificate authorities available. The general process is as follows:
Creating your own CA, intermediate CA, and generating your own signed certificates can be done following the three steps below using some open source tooling. Note creating an Intermediate CA is not explicitly required, but is recommended if you will be using self-signed certs in a private network in production. If this is simply for development that step can be skipped and the root CA can be used to sign server certificates. Again, using self-signed certs in production over the Internet is not recommended.