This document describes how to configure Server and Client authentication when setting secure (SSL) based authentication with Client Certificates to create secure connections between Chariot, MQTT Engine and MQTT Transmission.
Note |
---|
Available in Chariot version 2.3.1 and greater |
Prerequisites
Tip |
---|
The command line tools openssl and keytool are used. Install the OpenSSL command line tool and add the OpenSSL PATH in the Windows environment variables if necessary. Keytool is part of the standard java distribution and is located in the bin sub-directory of your jdk installation directory. Chariot includes a java distribution under the <chariot_install_dir>/lib/runtime/jdk11.0.12_7/bin folder.Add the keytool PATH in the Windows environment variables if necessary. You will need to restart your any open command window to pick up this configuration change. |
Generating Certificates and Keys
As a first step, we need to generate the certificate hierarchy for Chariot, MQTT Engine and MQTT Transmission.
...
These are the steps that need to be completed for the certificate hierarchy:
Anchor |
---|
| GenerateCACertificateChain |
---|
| GenerateCACertificateChain |
---|
|
Generate CA Certificate Chain
Navigate to the ChariotCerts parent folder to run the commands below:
Anchor |
---|
| GenerateRootCACertificate |
---|
| GenerateRootCACertificate |
---|
|
Generate Root CA certificate signed with the Root CAGenerate a private key file (ca.key) for the Root CA using the command below. You will be required to enter a pass phrase to be associated with the ca.key file.
Tip |
---|
Make note of this pass phrase for the Root CA private key file (ca.key) as it will be used multiple times whilst creating the certificate hierarchy. |
Code Block |
---|
|
openssl genrsa -des3 -out ca/ca.key 2048 |
Generate a self-signed certificate (ca.crt) for the Root CA using the command below. This command generates a new self-signed X.509 certificate named "ca.crt" valid for 3650 days (10 years) using the RSA private key "ca.key". You will be required to enter the pass phrase associated with the private key file "ca.key".
Code Block |
---|
|
openssl req -new -x509 -key ca/ca.key -days 3650 -out ca/ca.crt |
Note |
---|
There are a number of fields associated with the creation of the certificate. Fill them out with your relevant details where the Common Name must be the Fully Qualified Domain Name (FQDN) of the Chariot server. |
Anchor |
---|
| GenerateServerCACertificate |
---|
| GenerateServerCACertificate |
---|
|
Generate Server CA certificate signed with the Root CA
- Generate a private key file (serverCA.key) for the Server CA using the command below. You will be required to enter a pass phrase to be associated with the serverCA.key file.
...
We are now going to repeat this process for the remaining certificates required in the certificate hierarchy.
Anchor |
---|
| GenerateMQTTEngineClientCACertificate |
---|
| GenerateMQTTEngineClientCACertificate |
---|
|
Generate MQTT Engine Client CA certificate signed with the Root CAGenerate a private key file (engineCA.key) for MQTT Engine CA using the command below. You will be required to enter a pass phrase to be associated with the engineCA.key file.
Tip |
---|
Make note of this pass phrase for the MQTT Engine CA private key file (engineCA.key) as it will be used again whilst creating the certificate hierarchy. |
Code Block |
---|
|
openssl genrsa -des3 -out ca/engine/engineCA.key 2048 |
Generate a Certificate Signing Request (CSR) for the MQTT Engine CA using the command below. This command generates a new CSR named "engineCA.csr’ using the RSA private key "engineCA.key" and you will be required to enter the pass phrase for the engineCA.key file created in the previous step.
Code Block |
---|
|
openssl req -new -key ca/engine/engineCA.key -out ca/engine/engineCA.csr |
Note |
---|
There are a number of fields associated with the creation of the certificate. Fill them out with your relevant details where the Common Name must be the Fully Qualified Domain Name (FQDN) of the Chariot server. |
Sign the MQTT Engine CA with the Root CA using the command below. This command will sign the CSR "engineCA.csr" with the Root CA certificate ‘ca.crt’ and RSA private key ‘ca.key’, creating a new X.509 certificate named ‘engineCA.crt’ valid for 3650 days (10 years). You will be required to enter the pass phrase associated with the Root CA private key file "ca.key".
Code Block |
---|
|
openssl x509 -req -in ca/engine/engineCA.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out ca/engine/engineCA.crt -days 3650 |
Anchor |
---|
| GenerateMQTTTransmissionClientCACertificate |
---|
| GenerateMQTTTransmissionClientCACertificate |
---|
|
Generate MQTT Transmission Client CA certificate signed with the Root CAGenerate a private key file (transmissionCA.key) for MQTT Transmission CA using the command below. You will be required to enter a pass phrase to be associated with the transmissionCA.key file.
Tip |
---|
Make note of this pass phrase for the MQTT Transmission CA private key file (transmissionCA.key) as it will be used again whilst creating the certificate hierarchy. |
Code Block |
---|
|
openssl genrsa -des3 -out ca/transmission/transmissionCA.key 2048 |
Generate a Certificate Signing Request (CSR) for the MQTT Transmission CA using the command below. This command generates a new CSR named "transmissionCA.csr’ using the RSA private key "transmissionCA.key" and you will be required to enter the pass phrase for the transmissionCA.key file created in the previous step.
Code Block |
---|
|
openssl req -new -key ca/transmission/transmissionCA.key -out ca/transmission/transmissionCA.csr |
Note |
---|
There are a number of fields associated with the creation of the certificate. Fill them out with your relevant details where the Common Name must be the Fully Qualified Domain Name (FQDN) of the Chariot server. |
Sign the MQTT Transmission CA with the Root CA using the command below. This command will sign the CSR "transmissionCA.csr" with the Root CA certificate ‘ca.crt’ and RSA private key ‘ca.key’, creating a new X.509 certificate named ‘transmissionCA.crt’ valid for 3650 days (10 years). You will be required to enter the pass phrase associated with the Root CA private key file "ca.key".
Code Block |
---|
|
openssl x509 -req -in ca/transmission/transmissionCA.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out ca/transmission/transmissionCA.crt -days 3650 |
...
Note |
---|
Depending on the version of openSSL that you are using, you may see additional .srl files created which contain the signed certificate's unique serial number. These files are not used directly by the modules and not included in the certificate hierachy displayed above. |
Anchor |
---|
| GenerateServerCertificate |
---|
| GenerateServerCertificate |
---|
|
Generate Server certificate signed with Server CA private key
Generate private key in PKCS8 format (server.key) for the Chariot server using the command below.
Code Block |
---|
|
openssl genrsa -out certs/server/server.key 2048 |
Generate a Certificate Signing Request (CSR) for the Chariot server using the command below. This command generates a new CSR named "server.csr’ using the RSA private key "server.key".
Code Block |
---|
|
openssl req -new -key certs/server/server.key -out certs/server/server.csr |
Note |
---|
There are a number of fields associated with the creation of the certificate. Fill them out with your relevant details where the Common Name must be the Fully Qualified Domain Name (FQDN) of the Chariot server. |
Sign the Server CSR with the Server CA using the command below. This command will sign the CSR "server.csr" with the Server CA certificate ‘serverCA.crt’ and RSA private key ‘serverCA.key’, creating a new X.509 certificate named ‘serverCA.crt’ valid for 3650 days (10 years). You will be required to enter the pass phrase associated with the private key file "serverCA.key".
Code Block |
---|
|
openssl x509 -req -in certs/server/server.csr -CA ca/server/serverCA.crt -CAkey ca/server/serverCA.key -CAcreateserial -out certs/server/server.crt -days 3650 |
Anchor |
---|
| GenerateMQTTEngineClientCertificate |
---|
| GenerateMQTTEngineClientCertificate |
---|
|
Generate MQTT Engine Client certificate signed with the Engine CA’s private key
Generate private key in PSCK8 format (engine.key) for MQTT Engine using the command below.
Code Block |
---|
|
openssl genrsa -out certs/engine/engine.key 2048 |
Generate a Certificate Signing Request (CSR) for MQTT Engine using the command below. This command generates a new CSR named "engine.csr’ using the RSA private key "engine.key".
Code Block |
---|
|
openssl req -new -key certs/engine/engine.key -out certs/engine/engine.csr |
Note |
---|
There are a number of fields associated with the creation of the certificate. Fill them out with your relevant details where the Common Name must be the Fully Qualified Domain Name (FQDN) of the Chariot server. |
Sign the MQTT Engine Client CSR with the Engine CA using the command below. This command will sign the CSR "engine.csr" with the Engine CA certificate ‘engineCA.crt’ and RSA private key ‘engineCA.key’, creating a new X.509 certificate named ‘engineCA.crt’ valid for 3650 days (10 years). You will be required to enter the pass phrase associated with the private key file "engineCA.key".
Code Block |
---|
|
openssl x509 -req -in certs/engine/engine.csr -CA ca/engine/engineCA.crt -CAkey ca/engine/engineCA.key -CAcreateserial -out certs/engine/engine.crt -days 3650 |
Anchor |
---|
| GenerateMQTTTransmissionClientCertificate |
---|
| GenerateMQTTTransmissionClientCertificate |
---|
|
Generate MQTT Transmission Client certificate signed with the Transmission CA’s private key
Generate private key in PKCS8 format (transmission.key) for MQTT Transmission using the command below.
Code Block |
---|
|
openssl genrsa -out certs/transmission/transmission.key 2048 |
Generate a Certificate Signing Request (CSR) for MQTT Transmission using the command below. This command generates a new CSR named "transmission.csr’ using the RSA private key "transmission.key".
Code Block |
---|
|
openssl req -new -key certs/transmission/transmission.key -out certs/transmission/transmission.csr |
Note |
---|
There are a number of fields associated with the creation of the certificate. Fill them out with your relevant details where the Common Name must be the Fully Qualified Domain Name (FQDN) of the Chariot server. |
Sign the MQTT Transmission Client CSR with the Transmission CA using the command below. This command will sign the CSR "transmission.csr" with the Transmission CA certificate ‘transmissionCA.crt’ and RSA private key ‘transmissionCA.key’, creating a new X.509 certificate named ‘transmissionCA.crt’ valid for 3650 days (10 years). You will be required to enter the pass phrase associated with the private key file "transmissionCA.key".
Code Block |
---|
|
openssl x509 -req -in certs/transmission/transmission.csr -CA ca/transmission/transmissionCA.crt -CAkey ca/transmission/transmissionCA.key -CAcreateserial -out certs/transmission/transmission.crt -days 3650 |
...
chariotcerts/
├── ca/
│ ├── ca.crt
│ ├── ca.key
│ ├── engine/
│ │ ├── engineCA.crt
│ │ ├── engineCA.csr
│ │ ├── engineCA.key
│ ├── server/
│ │ ├── serverCA.crt
│ │ ├── serverCA.csr
│ │ ├── serverCA.key
│ └── transmission/
│ ├── transmissionCA.crt
│ ├── transmissionCA.csr
│ ├── transmissionCA.key
└── certs/
├── engine/
│ ├── engine.crt
│ ├── engine.csr
│ └── engine.key
├── server/
│ ├── server.crt
│ ├── server.csr
│ └── server.key
└── transmission/
├── transmission.crt
├── transmission.csr
└── transmission.key
Setting up SSL Connections Using Two-way Authentication
Now we are ready to setup SSL connections between two clients (MQTT Engine and Transmission) and the Chariot Server.
Here is a summary of what needs to be done:
Server Side Configuration Anchor |
---|
| SetupSSLOnChariot |
---|
| SetupSSLOnChariot |
---|
|
Setup SSL on ChariotNavigate to CONFIGURATION > System > Certificates configuration and upload the files as shown below. Once uploaded, select the Setup SSL button.
...
Navigate to CONFIGURATION > MQTT Server configuration and Enable Secure as shown below. Select the Update button to save the configuration.![](/download/attachments/143392877/image%20%288%29.png?version=1&modificationDate=1678403923900&api=v2)
Anchor |
---|
| ChariotTruststore |
---|
| ChariotTruststore |
---|
|
Update Chariot TruststoreBy default Chariot comes with an empty truststore file clientcerts.jks which is located in the <chariot_install_dir>/security folder.
...
Code Block |
---|
|
Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 2 entries
Alias name: engineca
Creation date: Mar 1, 2023
Entry type: trustedCertEntry
Owner: EMAILADDRESS=ilya.binshtok@cirrus-link.com, CN=MacBook-Pro.local, OU=MQTT Engine CA, O=Cirrus Link, L=Overland Park, ST=Kansas, C=US
Issuer: EMAILADDRESS=ilya.binshtok@cirrus-link.com, CN=MacBook-Pro.local, OU=CA, O=Cirrus Link, L=Overland Park, ST=Kansas, C=US
Serial number: b1d46c8c88db5c8e
Valid from: Wed Mar 01 10:37:08 CST 2023 until: Sat Feb 26 10:37:08 CST 2033
Certificate fingerprints:
SHA1: FE:3B:A0:A1:2D:AF:92:F3:A1:3C:8D:76:ED:8F:05:47:EE:A1:59:E2
SHA256: 8C:43:80:B8:14:90:7D:EB:89:69:58:FA:76:29:3D:50:8F:3D:8F:7E:D5:8F:C9:7C:5B:97:0E:DC:0E:E8:D6:3A
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 1
*******************************************
*******************************************
Alias name: transmissionca
Creation date: Mar 1, 2023
Entry type: trustedCertEntry
Owner: EMAILADDRESS=ilya.binshtok@cirrus-link.com, CN=MacBook-Pro.local, OU=MQTT Transmission CA, O=Cirrus Link, L=Overland Park, ST=Kansas, C=US
Issuer: EMAILADDRESS=ilya.binshtok@cirrus-link.com, CN=MacBook-Pro.local, OU=CA, O=Cirrus Link, L=Overland Park, ST=Kansas, C=US
Serial number: b1d46c8c88db5c8f
Valid from: Wed Mar 01 16:50:36 CST 2023 until: Sat Feb 26 16:50:36 CST 2033
Certificate fingerprints:
SHA1: 01:FD:41:DF:AE:CE:28:A4:16:F8:3E:66:E7:71:FE:88:2F:98:1B:86
SHA256: 9F:BC:1D:10:43:9C:F7:BE:D6:07:58:E1:DD:9D:09:0E:0D:01:82:37:DC:8E:FA:9A:3B:46:1A:98:1E:52:39:AE
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 1
*******************************************
******************************************* |
Anchor |
---|
| ChariotAuthenticationPolicy |
---|
| ChariotAuthenticationPolicy |
---|
|
Update Chariot Clients Authentication PolicyUsing a text editor, set the "clientAuthPolicy" to "required" in the <chariot_install_dir>/conf/com.cirruslink.chariot.server configurationfile.
...
Warning |
---|
You will now need to restart the Chariot service to pickup up the configuration changes |
Client Side Configuration Anchor |
---|
| MQTTEngineClientSide |
---|
| MQTTEngineClientSide |
---|
|
MQTT Engine Client Side Configuration
Add the certificates to the MQTT Engine > Servers > Certificates configuration as shown below:
...
Update the MQTT Engine > Servers > Settings configuration to use the certificates as shown below and setting the URL to be ssl://FQDN:8883 with the FQDN of the Chariot Server. Click the Save Changes button to save the configuration.![](/download/attachments/143392877/image%20%281%29.png?version=1&modificationDate=1678403692717&api=v2)
Anchor |
---|
| MQTTTransmissionClientSide |
---|
| MQTTTransmissionClientSide |
---|
|
MQTT Transmission Client Side ConfigurationAdd certificates to the MQTT Transmission > Servers > Certificates configuration as shown below:
...
Update the MQTT Transmission > Servers > Settings configuration to use the certificates as shown below. Click the Save Changes button to save the configuration.![](/download/attachments/143392877/image%20%283%29.png?version=1&modificationDate=1678403730465&api=v2)
Anchor |
---|
| VerifyConnectivity |
---|
| VerifyConnectivity |
---|
|
Verifying ConnectivityEngine
From the left hand menu bar, navigate to Config > MQTT Engine > Servers and note the Status as Connected.![](/download/attachments/143392877/image%20%285%29.png?version=1&modificationDate=1678403812284&api=v2)
Transmission
From the left hand menu bar, navigate to Config > MQTT Transmission > Servers and note the Status as "x of x". This denotes the number of configured transmitters that are connected.
If you do not see a transmitter connected, verify that you have a transmitter with a valid Sparkplug ID either through setting the Group and Edge ID or through the TagPath. Review our troubleshooting guide for assistance. ![](/download/attachments/143392877/image%20%284%29.png?version=1&modificationDate=1678403794329&api=v2)
Chariot
On the Chariot MQTT server, navigate to STATUS > MQTT where the number of active MQTT Clients will be displayed. This will be a count of 2 or 3 depending on your MQTT Transmission RPC Client configuration.![](/download/attachments/143392877/image%20%289%29.png?version=1&modificationDate=1678403956828&api=v2)
...