Secure MQTT Connection Between HMI and Ignition Gateway
Technical Note 5136
Applicable Model(s)
cMT Series
Title
Secure MQTT Connections Between Maple Systems HMIs and Ignition Gateway using SSL/TLS Certificates
Date
02/24/2020
Rev
00
P/N
0907-5136
Summary
By default, most MQTT Brokers and Clients send data unencrypted over port 1883. This Technical Note describes how to enable end-to-end encrypted connections between your Maple Systems HMIs and Inductive Automation’s Ignition Gateway platform using SSL/TLS certificates.
Requirements
Download and install the following software programs before you continue:
- Oracle Java version 8 or higher: https://java.com/en/download
- Keystore Explorer: https://keystore-explorer.org/downloads.html
- MQTT.fx: https://mqttfx.jensd.de
NOTE: You should already have Ignition Gateway with Cirrus Link MQTT Modules, as well as EBPro installed on your PC prior to starting the SSL Certificate Installation process outlined below. If you do not, please see our Sparkplug B MQTT Quick-Start Guide (See: Manuals & Guides) or visit our Software Download Center to download EBPro Full Version, respectively.
Solution
Create an SSL Certificate
This section adapted from Inductive Automation video: “How to Set Up Transport Layer Security”
Create a Java Keystore File and RootCA Certificate
NOTE: Download Keystore Explorer from keystore-explorer.org if you have not already done so.
1.
Open Keystore Explorer and create a new keystore in JKS format.
a.
Select: File > New > JKS, and click OK.
2.
You may import a purchased certificate if you already have one or follow the instructions below to generate a self-signed certificate.
3.
To generate a certificate, right-click on the main window (blank, white area) and select Generate Key Pair.
4.
Select RSA algorithm, key size: 2048 (bits).
5.
Leave these defaults as they are: Version 3 and SHA-256 with RSA.
6.
Click on the Address Book icon next to the Name field.
7.
Enter a name, such as “RootCA”
8.
Fill in the Organization Unit (OU), and Organization (O) fields
a.
Example #1: OU: “IT”; O: “IA”
b.
Example #2: OU: “Support”; O: “Maple Systems”
9.
Click OK.
10.
To add extensions, Click the green + (plus) button.
a.
Add Type: Basic Constraints – Check the box to enable “Subject is a CA” and click OK to add.
b.
Add Type: Key Usage – Check the boxes to enable “Certificate Signing” and “CRL Sign”, then click OK to add.
11.
Click OK to finish generating Key Pair Certificate.
12.
Enter an Alias, e.g.: “RootCA”, and click OK.
13.
Specify a password for the keystore file.
NOTE: You will need to record this password and enter it into Ignition when you import the certificate.
14.
Click OK. The message “Key Pair Generation Successful” should now appear.
Create and Sign a New Key Pair (Certificate) Using the RootCA
1.
Right-click on the newly generated ‘rootca’ certificate, select Sign, and choose Sign New Key Pair.
2.
Select RSA, 2048-bit and click OK.
3.
Add a name by filling in the following fields:
a.
Common Name (CN) – the IP address or hostname for the server, e.g. “192.168.100.10” or “localhost”.
b.
OU – Use the same value that was configured during step 8 of the previous section.
c.
O – Use the same value that was configured during step 8 of the previous section.
d.
Example of Name field when finished:
- CN = localhost
- OU = Support
- IA = MapleSystems
4.
Click OK.
5.
Set the Alias (leave as default), e.g.: “localhost (RootCA)”.
6.
Enter a password for this key pair (use the same password configured in step 13 of the previous section).
7.
Save the keystore as ‘cert.jks’.
8.
Select File > Save, enter the password, and name it ‘cert.jks’.
9.
Set the type to KeyStore Files.
10.
Click OK/Save.
11.
Export the Certificate Chain (.pem file) for this RootCA certificate.
12.
From KeyStore Explorer, right-click on ‘rootca’, and select Export > Export Certificate Chain.
13.
Leave these defaults as they are:
- Export Length: Head Only
- Export Format: X.509
14.
Make sure that the PEM option is checked.
15.
Edit the filename and add the .pem extension:
- Example (Original): “C:\PATH\TO\rootca.cer”
- Example (Modified): “C:\PATH\TO\rootca.pem”
16.
Click Export. You should see the message ‘Export Certificate Chain Successful’.
Ignition Gateway MQTT Distributor Settings
1.
From Ignition Gateway > MQTT Distributor Settings, click on Enable TLS (default port: 8883).
2.
Under TLS Settings > Java Keystore File, click on Choose File.
3.
Browse to the ‘cert.jks’ file saved previously, select it and click Open.
4.
Enter the Java keystore password in the ‘Keystore password’ field
5.
Click Save Changes.
Ignition Gateway MQTT Transmission Settings
1.
From the Servers tab, click Edit to the right of the existing server.
2.
Change the URL from “tcp://<hostname>:1883” to “ssl://<hostname>:8883”
- Example: ssl://localhost:8883
3.
In the TLS section, select Certificate File Upload, click Choose File.
4.
Browse to and select ‘rootca.pem’ and click Open.
5.
Click Save Changes.
6.
If successful, on the Servers tab, you should see ‘1 of 1’, or ‘2 of 2’ are now connected.
Ignition Gateway MQTT Engine Settings
1.
From the Servers tab, click Edit to the right of the existing server.
2.
Change the URL from “tcp://<hostname>:1883” to “ssl://<hostname>:8883”.
- Example: ssl://localhost:8883
3.
In the TLS section, select Certificate File Upload, click Choose File.
4.
Browse to and select ‘rootca.pem’ and click Open.
5.
Click Save Changes.
6.
If successful, the status should say Connected on the Servers tab.
Installing SSL Certificates on Maple Systems HMIs
NOTE: You can use the same certificate that was installed into Ignition Gateway in previous steps.
SSL Certificates on Maple Systems cMT HMIs, Gateways, and Servers
1.
In EBPro, navigate to IIoT/Energy > MQTT, click on Settings to open MQTT Server Object Properties.
2.
Open the General tab.
3.
Change the port from 1883 to 8883.
4.
Check the box for Authentication and fill in the Ignition Gateway username and password.
5.
In the TLS/SSL tab:
a.
Check Enable and check Server Verification.
b.
Disable “Server name must match certificate’s information”.
c.
Click Import…, then browse to select the ‘rootca.pem’ file, and click Open.
d.
Click OK, then click Exit on the main MQTT Options window.
Testing with Simulation Mode in EBPro
- If the (simulated) HMI cannot connect to the server, double-check the username and password entered on the General tab and try again.
- Else, if unable to connect, check the Ignition Gateway logs for additional error messages.
- If your EBPro installation is on a separate PC than your Ignition Gateway server, you may need to open port 8883 on either or both PCs in order for communication between the two devices to be established.
- See our Sparkplug B MQTT Quick-Start Guide (See: Manuals & Guides) for more information on networking and firewall settings.
- Once you are able to establish a secure connection using Simulation mode in EBPro, you may download the project to your HMI.
NOTE: Visit our Sample Projects page in order to download a free copy of our Sparkplug B MQTT Sample Project. You can use this for testing purposes or adapt it for your own application.