MQTT Distributor can be enabled to use TLS to encrypt the communication between MQTT clients which 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.
| Review our notes on Getting a Certificate from a Certificate Authority or Creating a Self-Signed Certificate |
As of module release version 4.0.4, the Cirrus Link MQTT Distributor module is capable of reusing the existing Ignition web server SSL certificates to secure your MQTT communication. Upgrading your MQTT Distributor module to a newer version and reusing the Ignition web server SSL certificates is the recommended process to secure your MQTT communication using SSL/TLS. See the Ignition Compability with Cirrus Link Modules for details. |
If using modules versioned before 4.0.4, the steps here will help you through creating a Java keystore (JKS) containing all appropriate certificates and how to configure MQTT Distributor to use this keystore. |
Review the following list for the required certificates:
Follow the steps outlined in the Ignition Secure Communication (SSL / TLS) document using the Certification wizard to import the certificates needed to SSL enable the Ignition Web Server.
Once configured, you will be able to view the SLL/TLS Certificate details which should be displayed similar to the image below:
Once the Ignition Web Server has been SSL enabled, enable SSL/TLS for MQTT Distributor by selecting the "Enable TLS" configuration setting under TLS Setting section for MQTT Distributor.
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 each of the servers with the appropriate MQTT Server URL for your environment. For example, 'ssl://mqttserver:8883'
For MQTT Transmission, navigate to the Servers Settings Main section and update the URL as shown below:
For MQTT Engine, navigate to the Servers Settings Main section and update the URL as shown below:
If you are using self-signed certificates in your environment, an additional requirement is that the certificate chain (aka. "chain-of-trust") be available to MQTT Engine and Transmission. Follow the instructions in the Using Self-signed Certificates section. |
If you are not using self-signed certificates in your environment, at this point MQTT Engine and MQTT Transmission should show they're connected to MQTT Distributor over SSL/TLS.
If using self-signed certificates in your environment, there is 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.
| This step is only necessary if you're running pre-4.0.4 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 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 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.
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.