Page History

...

• Installing the Java Runtime Environment
• Installing Ignition
• Installing the following MQTT Modules
  • MQTT Distributor
    • v1v2.7.1 or greater if using Ignition 7.7.X v1.8.1 or greater if using Ignition 7.8.X
    MQTT Engine
    • v1.7.3 x or greater if using Ignition 7.78.Xxv1
    • v3.81.3 0 or greater if using Ignition 7.89.X

Overview:

MQTT Distributor can be enabled to use TLS for encryption of 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.  There are two ways this can be done.  First is to certificate signed by a publicly trusted certificate authority (CA).  While there are nominal costs associated with this, it is the proper and recommended way to go if communicating over the Internet.  Alternatively, it is possible to create and use a self-signed certificate.  This is useful for debugging and development.  However, it is not recommended in production scenarios over the Internet.  It is, however, a viable option if utilizing a private network in which encryption is a requirement.

...

You will now be asked to specify a password for the keypair.  At this point MQTT Distributor requires that the Key Pair passwords match the overall Keystore password.  So, make sure you note this password because we'll need to use it as the overall keystore password as well.

If your certificate also requires an intermediate certificate, it must be appended to the keypair.  Do so by right-clicking the keypair and navigating to Append Certificate as shown below.  In the case of self-signed certs, this means clients only need to have the root CA certificate trusted on their system.  In the case of certificates signed by trusted CAs, the clients don't need to have any additional TLS configuration loaded on their system.

Image Removed

Now browse to your intermediate certificate as shown below and click Append:

Image Removed

You should see the following.  Simply click OK.

Image Removed

At this point, you can save your keystore and specify a keystore password.  Do so by clicking the save icon in the upper left menu:

...

At this point, the Java keystore simply needs to be set in MQTT Distributor's configuration.  Do so by browsing the the Ignition Gateway Web UI and select the Configure tab:

Image Removed

.  Then select MQTT Distributor settings on the left side menu :

Image Removed

as shown below.

Image Added Find the 'TLS Setting' section of the General Settings tab as shown below.

Image AddedMake sure the 'Enable TLS' is checked.  Select the 'Java Keystore File' 'Browse' You should see the following.  The bottom option is to specify a Java Keystore File.  Select the browse button and then browse to the Java Keystore file you created above.

Image Removed

Also, make sure to enter Enter the Keystore password and click the Enable TLS tick box as shown below and then click Save Changes:.

Image Removed

At this point, all MQTT clients can now connect over TLS enabled connections.  Note the new port of 8883.  If using a certificate signed by a publicly trusted CA and the OS with the MQTT client supports that specific CA, the clients don't have to make any modifications to their list of trusted root certificates.  If using a self-signed certificate there are a couple options:

• The root CA cert can be added to the Operation System's list of trusted root certificates
  • This means the application doesn't need to handle special cases (i.e. modifications to the Java Truststore)
• The client side application can be modified to load the root CA certificate to validate the server certificate against
  • This doesn't require OS changes

 Note if your certificate also requires an intermediate certificate, this must also be added to the MQTT client so the full chain of trust can be established.

Using the Certificate to Secure Communication with MQTT Engine or MQTT Transmission:

In MQTT Engine or Transmission, there may be a need to specify the TLS components for the client configuration.  In the case of using certificates signed by a trusted CA that do not require an internediate cert don't need any special configuration other changing the form of the URL.  The form should be as follows:

• ssl://[sever_url]:8883

An example is here:

Image Added

If the trusted CA you purchased your certificate from requires an intermediate certificate or if you created a self signed certificate, you will need to specify the CA certificate chain in the configuration.  If you received your certificate from a trusted CA and they require an intermediate certificate, it will be provided by the CA.  If you followed the tutorial above for a self-signed certificate and also created an intermediate CA, it will be the file called 'ca-chain.cert.pem'.  If you simply created a CA without an intermediate cert, it will be the public CA certificate.  Once you've identified the CA certificate chain based on these descriptions, copy it to a file called 'root.ca.pem' on your development system.  Note this filename change is important and required.  Upload the file via the configuration as shown here by clicking Save Changes:

Image Added

Once the settings are saved, the MQTT client associated with MQTT Engine or MQTT Transmission will connect using TLS.