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

Table of Contents

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.

Create the following folder structure on your local drive to hold the various certificates in the hierarchy that we will be generating:

chariotcerts/
├── ca/
└── certs/
    ├── engine/
    └── transmission/

When creating a certificate hierarchy, the Root

...

Generating Certificates and Keys

As a first step, we need to generate certificates for Chariot, MQTT Engine and MQTT Transmission. Let’s create the following directory tree to work with:

├── ca/
│ ├── engine/
│ ├── server/
│ └── transmission/
└── certs/
├── engine/
├── server/
└── transmission/

When creating a certificate hierarchy, the Root CA is the highest level of authority in the certificate hierarchy, and is responsible for issuing CA certificates to lower-level CAs, such as the Server CA and Client CAssigned certificates, such as the MQTT Engine and MQTT Transmission certificates that will be shown below. When the Root CA issues a CA certificate to a lower-level CA, it signs the certificate with its private key, which allows clients the MQTT Server to verify the authenticity of the CA certificate certificates using the Root CA's public key.

The Server CA and Client CA, in turn, use their own private keys to sign SSL certificates for servers and clients, respectively. These SSL certificates can then be verified by clients using the CA certificate issued by the Root CA.

The Root CA should sign the CA certificates for both the Server CA and Client CA, while the Server CA and Client CA themselves are responsible for signing SSL certificates for servers and clients, respectively.

These are the steps that need to be completed for the certificate hierarchy:

Generate CA certificate chain

...

Note this tutorial only covers client based authentication using certificates. It does not cover setting up TLS/SSL on an MQTT Server which is used encyrpt communication between MQTT clients and the MQTT Server. This must also be done and information can be found here on how to set this up.

These are the steps that need to be completed for the certificate hierarchy:

Anchor
GenerateRootCACertificate
GenerateRootCACertificate
Generate Root CA certificate

Generate a private key file (ca.key) for the Root CA using the command below. You may choose to enter a passphrase to be associated with the ca.key file as well.
Tip
Make note of this passphrase if you set one for the Root CA private key file (ca.key) as it will be used multiple times.
Code Block
language text
openssl genrsa -des3 -out ca/ca.key 4096
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"

...

Generate a private key file (ca.key) for the Root CA using the command below. You will be required to enter a the pass phrase to be associated with the private key file "ca.key file".

Code Block

language	text

openssl genrsareq -des3new -x509 -outkey 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". A "ca.srl" file will also be created containing the signed certificate's unique serial number. You will be required to enter the pass phrase associated with the private key file "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.

Code Block

language	bash
title	Example CA Creation

Code Block

language	text

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. The required fields are:

Country Name (2 letter code) []:

State or Province Name (full name) []:

Locality Name (eg, city) []:

Organization Name (eg, company) []:

Organizational Unit Name (eg, section) []: We set this to CA

Common Name (eg, fully qualified host name) [] We set this to the FQDN of the Chariot server

Email Address []:

...

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.

Code Block

language	text

openssl genrsa -des3 -out ca/server/serverCA.key 2048

Generate a Certificate Signing Request (CSR) for the server CA using the command below. This command generates a new CSR named "serverCA.csr’ using the RSA private key "serverCA.key" and you will be required to enter the pass phrase created in the previous step.

Code Block

language	text

openssl req -new -key ca/server/serverCA.key -out ca/server/serverCA.csr

...

There are a number of fields associated with the creation of the certificate. The required fields are:

Country Name (2 letter code) []:

State or Province Name (full name) []:

Locality Name (eg, city) []:

Organization Name (eg, company) []:

Organizational Unit Name (eg, section) []: We set this as Server CA

Common Name (eg, fully qualified host name) []: We set this as the FQDN of the Chariot server

Email Address []:

Extra attributes to be sent with the certificate request are:

A challenge password []: Any alpha-numeric phrase


Enter pass phrase for ca/ca.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:KS
Locality Name (eg, city) []:Stilwell
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cirrus Link Solutions
Organizational Unit Name (eg, section) []:Support
Common Name (e.g. server FQDN or YOUR name) []:CLS Example Root CA   
Email Address []:
$

You should have the following files created:

chariotcerts/
├── ca/
   ├── ca.crt
   ├── ca.key

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
GenerateMQTTEngineClientCertificate
GenerateMQTTEngineClientCertificate
Generate MQTT Engine Client certificate signed with the Root CA’s private key

Generate private key in PSCK8 format (engine.key) for MQTT Engine using the command below.
Code Block
language text
openssl genrsa -out certs/engine/engine.key 4096

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

language	text

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.

Code Block

language	bash
title	Example Engine CSR Creation

$ openssl req -new -key certs/engine/engine.key -out certs/engine/engine.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:KS
Locality Name (eg, city) []:Stilwell
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cirrus Link Solutions
Organizational Unit Name (eg, section) []:Support
Common Name (e.g. server FQDN or YOUR name) []:EngineDevice
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
$

Sign the MQTT Engine Client CSR with the Engine

Sign the Server CA with the Root CA using the command below. This command will sign the CSR "serverCA.csr" with the Root CA certificate ‘ca.crt’ and RSA private key ‘ca.key’, creating a new X.509 certificate named ‘serverCA.crt’ valid for 3650 days (10 years). A "serverCA.srl" file will also be created containing the signed certificate's unique serial number. You will be required to enter the pass phrase associated with the private key file "ca.key".

Code Block

language	text

openssl x509 -req -in ca/server/serverCA.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out ca/server/serverCA.crt -days 3650

...

Generate 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.

Code Block

language	text

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 created in the previous step.

Code Block

language	text

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. The required fields are:

Country Name (2 letter code) []:

State or Province Name (full name) []:

Locality Name (eg, city) []:

Organization Name (eg, company) []:

Organizational Unit Name (eg, section) []: We set this as MQTT Engine CA

Common Name (eg, fully qualified host name) []: We set this as the FQDN of the Chariot server

Email Address []:

Extra attributes to be sent with the certificate request are:

A challenge password []: Any alpha-numeric phrase

Sign the MQTT Engine CA with the Root CA using the command below. This command will sign the CSR "engineCAengine.csr" with the Root CA certificate ‘ca.crt’ and Root CA's RSA private key ‘ca.key’, creating a new X.509 certificate named ‘engineCA‘engine.crt’ valid for 3650 365 days (10 years1 year). An "engineCA.srl" file will also be created containing the signed certificate's unique serial number. You will be You will be required to enter the pass phrase passphrase associated with the private key file "ca.key".
Code Block
language text
openssl x509 -req -in cacerts/engine/engineCAengine.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out cacerts/engine/engineCAengine.crt -days 3650365

Anchor

...

GenerateMQTTTransmissionClientCertificate

...

GenerateMQTTTransmissionClientCertificate
Generate

...

MQTT Transmission Client

...

certificate signed with the Root

...

CA’s private key

Generate a private key file in PKCS8 format (transmissionCAtransmission.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.
Code Block
language text
openssl genrsa -des3 -out cacerts/transmission/transmissionCAtransmission.key 20484096

Generate a Certificate Signing Request (CSR) for the MQTT Transmission CA using the command below. This command generates a new CSR named "transmissionCAtransmission.csr’ using the RSA private key "transmissionCAtransmission.key" and you will be required to enter the pass phrase created in the previous step.

Code Block

language	text

openssl req -new -key cacerts/transmission/transmissionCAtransmission.key -out cacerts/transmission/transmissionCAtransmission.csr

Note

There are a number of fields associated with the creation of the certificate. The required fields are:

Country Name (2 letter code) []:

State or Province Name (full name) []:

Locality Name (eg, city) []:

Organization Name (eg, company) []:

Organizational Unit Name (eg, section) []: We set this as MQTT Transmission CA

Common Name (eg, fully qualified host name) []: We set this as the FQDN of the Chariot server

Email Address []:

Extra attributes to be sent with the certificate request are:

A challenge password []: Any alpha-numeric phrase

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). An "transmissionCA.srl" file will also be created containing the signed certificate's unique serial number. You will be required to enter the pass phrase associated with the private key file "ca.key".

Code Block

language	text

openssl x509 -req -in ca/transmission/transmissionCA.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out ca/transmission/transmissionCA.crt -days 3650

You should have the following files created:

├── ca/

├── ca.crt

├── ca.key

├── ca.srl

├── engine/

│ ├── engineCA.crt

│ ├── engineCA.csr

│ ├── engineCA.key

│ └── engineCA.srl

├── server/

│ ├── serverCA.crt

│ ├── serverCA.csr

│ ├── serverCA.key

│ └── serverCA.srl

└── transmission/

├── transmissionCA.crt

├── transmissionCA.csr

├── transmissionCA.key

└── transmissionCA.srl

...

. Fill them out with your relevant details.

Code Block

language	bash
title	Example Transmission CSR Creation

$ openssl req -new -key certs/transmission/transmission.key -out certs/transmission/transmission.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:KS
Locality Name (eg, city) []:Stilwell
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cirrus Link Solutions
Organizational Unit Name (eg, section) []:Support
Common Name (e.g. server FQDN or YOUR name) []:TransmissionDevice1
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []: $

Sign the MQTT Transmission Client CSR with the Transmission CA using the command below. This command will sign the CSR "transmission.csr" with the Root CA certificate ‘ca.crt’ and Root CA's RSA private key ‘ca.key’, creating a new X.509 certificate named ‘transmission.crt’ valid for 365 days (1 year). You will be required to enter the passphrase associated with the private key file "transmission.key"

...

Generate private key in PKCS8 format (server.key) for the Chariot server using the command below.
Code Block
language text
openssl genrsax509 -req -outin certs/servertransmission/servertransmission.key 2048
******* Convert from PKCS8 format to PCKS1 until Chariot supports PKCS8 format *********
Code Block
language text
openssl rsa -in certs/server/servercsr -CA ca/ca.crt -CAkey ca/ca.key -traditionalCAcreateserial -out certs/servertransmission/server.keyopen
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
language text
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. The required fields are:
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []: We set this as Chariot
Common Name (eg, fully qualified host name) []: We set this as the FQDN of the Chariot server
Email Address []:
Extra attributes to be sent with the certificate request are:
A challenge password []: Any alpha-numeric phrase.
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
language text
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 365

...

Generate private key in PSCK8 format (engine.key) for MQTT Engine using the command below.

Code Block

language	text

openssl genrsa -out certs/engine/engine.key 2048

...

transmission.crt -days 365

We have now generated all the certificates and keys needed to setup MQTT Client certificate based authentication connections between Chariot and the MQTT Engine and MQTT Transmission modules:

chariotcerts/
├── ca/
│   ├── ca.crt
│   ├── ca.key
└── certs/
    ├── engine/
    │   ├── engine.crt
    │   ├── engine.csr
    │   └── engine.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

Client side configuration

Anchor
ServerSide
ServerSide
Server Side Configuration

Anchor
SetupSSLOnChariot
SetupSSLOnChariot
Setup SSL on Chariot

Navigate to CONFIGURATION > System > Certificates configuration and upload the files as shown below. Once uploaded, select the Setup SSL button. Use the certificate components created in Secure Chariot MQTT Server communication using SSL/TLS.

File Type	Where to get the file
CA Chain	Provided by your Certificate Authority
Private Key	The key you generated when creating your CSR to submit to your CA
Certificate	The server certificate provided by your Certificate Authority after you submitted your CSR to them

Image Added

Navigate to CONFIGURATION > MQTT Server configuration and Enable Secure as shown below. Select the Update button to save the configuration.

Image Added

Anchor
ChariotTruststore
ChariotTruststore
Update Chariot Truststore

By default Chariot comes with an empty truststore file clientcerts.jks which is located in the <chariot_install_dir>/security folder.

To view this file, run the command as shown below. You will be required to enter the keystore password and this can be found in the <chariot_install_dir>/conf/com.cirruslink.chariot.system configurationfile as the "trustStorePassword" parameter.

Code Block

language	text

...

keytool

...

-list -

...

v -

...

keystore <chariot_install_dir>/security/clientcerts.jks

You will see that the truststore contains no entries.

Use the following command to add the Root CA certificate to the truststore using the "trustStorePassword" when prompted.

When prompted Trust this certificate? [no]: respond "yes"

Code Block

language	text

keytool -importcert -file ca/ca.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias CACertificate

Use the following command to add the Engine client side certificate to the truststore using the "trustStorePassword" when prompted.

When prompted Trust this certificate? [no]: respond "yes"

Code Block

language	text

keytool -importcert -file certs/engine/engine.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias EngineDevice

Use the following command to add the Transmission client side certificate to the truststore using the "trustStorePassword" when prompted.

When prompted Trust this certificate? [no]: respond "yes"

Code Block

language	text

keytool -importcert -file certs/transmission/transmission.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias TransmissionDevice1

Once completed, viewing the file will now show three entries similar to below:

There are a number of fields associated with the creation of the certificate. The required fields are:

Country Name (2 letter code) []:

State or Province Name (full name) []:

Locality Name (eg, city) []:

Organization Name (eg, company) []:

Organizational Unit Name (eg, section) []: We set this as MQTT Engine

Common Name (eg, fully qualified host name) []: We set this as the FQDN of the Chariot server

Email Address []:

Extra attributes to be sent with the certificate request are:

A challenge password []: Any alpha-numeric phrase.

...

Code Block

language	text

...

Keystore

...

Generate private key in PKCS8 format (transmission.key) for MQTT Transmission using the command below.

Code Block

language	text

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

language	text

openssl req -new -key certs/transmission/transmission.key -out certs/transmission/transmission.csr

...

There are a number of fields associated with the creation of the certificate. The required fields are:

Country Name (2 letter code) []:

State or Province Name (full name) []:

Locality Name (eg, city) []:

Organization Name (eg, company) []:

Organizational Unit Name (eg, section) []: We set this as MQTT Transmission

Common Name (eg, fully qualified host name) []: We set this as the FQDN of the Chariot server

Email Address []:

Extra attributes to be sent with the certificate request are:

A challenge password []: Any alpha-numeric phrase.

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

language	text

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 365

We have now generated all the certificates and keys needed to setup SSL connections between Chariot and the MQTT Engine and MQTT Transmission modules:

├── ca/

│ ├── ca.crt

│ ├── ca.key

│ ├── ca.srl

│ ├── engine/

│ │ ├── engineCA.crt

│ │ ├── engineCA.csr

│ │ ├── engineCA.key

│ │ └── engineCA.srl

│ ├── server/

│ │ ├── serverCA.crt

│ │ ├── serverCA.csr

│ │ ├── serverCA.key

│ │ └── serverCA.srl

│ └── transmission/

│ ├── transmissionCA.crt

│ ├── transmissionCA.csr

│ ├── transmissionCA.key

│ └── transmissionCA.srl

└── 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

Enable SSL on Chariot and add server side certificates and keys (serverCA.crt, server.key, and server.crt)
Add Clients CA certificates (engineCA.crt and transmissionCA.crt) to the Chariot truststore
Set the ‘Clients Authentication Policy’ on Chariot to “required”

Client side configuration

Add the serverCA.crt, engine.key, and engine.crt to the ‘Chariot’ connection on the MQTT Engine side.
Add the serverCA.crt, transmission.key, and transmission.crt to the ‘Chariot’ connection on the MQTT Transmission side.

...

Setup SSL on Chariot

Navigate to CONFIGURATION > System > Certificates configuration and upload the files as shown below. Once uploaded, select the Setup SSL button.

Image Removed

Navigate to CONFIGURATION > MQTT Server configuration and Enable Secure as shown below:

Image Removed

Update Chariot Truststore

By default Chariot comes with an empty truststore file clientcerts.jks which is located in the <chariot_install_dir>/security folder.

...

Code Block

language	text

keytool -list -v -keystore <chariot_install_dir>/security/clientcerts.jks

You will see that the truststore contains no entries. Use the following commands to add the Engine and Transmission client side certificates to the truststore using the "trustStorePassword" when prompted:

Code Block

language	text

keytool -importcert -file ca/engine/engineCA.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias ca/engine/engineca

** When prompted Trust this certificate? [no]: respond "yes"***

keytool -importcert -file ca/transmission/transmissionCA.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias ca/transmission/transmissionca

** When prompted Trust this certificate? [no]: respond "yes"***

Once completed, viewing the file will now show two entries similar to below:

Code Block

language	text

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


type: PKCS12
Keystore provider: SUN

Your keystore contains 3 entries

Alias name: cacertificate
Creation date: Feb 7, 2024
Entry type: trustedCertEntry

Owner: CN=CLS Example Root CA, OU=Support, O=Cirrus Link Solutions, L=Stilwell, ST=KS, C=US
Issuer: CN=CLS Example Root CA, OU=Support, O=Cirrus Link Solutions, L=Stilwell, ST=KS, C=US
Serial number: 6f689c58c0f3e7177224c5868b75fcd51bcc2e0f
Valid from: Wed Feb 07 19:43:45 UTC 2024 until: Sat Feb 04 19:43:45 UTC 2034
Certificate fingerprints:
	 SHA1: 15:BC:A7:28:BE:15:D9:7F:E7:B0:1E:51:4E:A0:0F:57:58:C7:A3:2E
	 SHA256: 7A:1E:A0:D8:B5:4E:CB:BF:2D:A9:8D:E2:7F:E6:20:3C:B8:2C:11:4F:14:FF:AD:F6:A1:01:58:C0:37:B3:04:A7
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 4096-bit RSA key
Version: 3

*******************************************
******************************************* 

Alias name: enginedevice
Creation date: Feb 7, 2024
Entry type: trustedCertEntry

Owner: CN=EngineDevice, OU=Support, O=Cirrus Link Solutions, L=Stilwell, ST=KS, C=US
Issuer: CN=CLS Example Root CA, OU=Support, O=Cirrus Link Solutions, L=Stilwell, ST=KS, C=US
Serial number: 6f689c58c0f3e7177224c5868b75fcd51bcc2e0f
Valid from: Wed Feb 07 19:43:45 UTC 2024 until: Sat Feb 04 19:43:45 UTC 2034
Certificate fingerprints:
	 SHA1: 15:BC:A7:28:BE:15:D9:7F:E7:B0:1E:51:4E:A0:0F:57:58:C7:A3:2E
	 SHA256: 7A:1E:A0:D8:B5:4E:CB:BF:2D:A9:8D:E2:7F:E6:20:3C:B8:2C:11:4F:14:FF:AD:F6:A1:01:58:C0:37:B3:04:A7
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 4096-bit RSA key
Version: 3

*******************************************
*******************************************  

Alias name: transmissiondevice1
Creation date: Feb 7, 2024
Entry type: trustedCertEntry

Owner: CN=TransmissionDevice1, OU=Support, O=Cirrus Link Solutions, L=Stilwell, ST=KS, C=US
Issuer: CN=CLS Example Root CA, OU=Support, O=Cirrus Link Solutions, L=Stilwell, ST=KS, C=US
Serial number: 6f689c58c0f3e7177224c5868b75fcd51bcc2e11
Valid from: Wed Feb 07 19:52:48 UTC 2024 until: Thu Feb 06 19:52:48 UTC 2025
Certificate fingerprints:
	 SHA1: 60:7E:A5:6E:47:09:79:FB:A9:FE:24:DB:05:1E:09:54:24:48:19:BD
	 SHA256: 8A:C8:39:E1:50:8B:BF:35:25:43:C7:B4:66:60:02:1E:AF:4F:C4:11:32:B0:6D:FC:6D:6E:5D:A8:BE:FA:00:0B
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 4096-bit RSA key
Version: 3   

*******************************************
***********************************************
*******************************************


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


*******************************************
*******************************************

Tip
Keytool is part of the standard java distribution and is located in the bin sub-directory of your jdk installation directory. Chariot will always include a java distribution under the <chariot_install_dir>/lib/runtime

Update Chariot Clients Authentication Policy

...

Anchor
ChariotAuthenticationPolicy
ChariotAuthenticationPolicy
Update Chariot Clients Authentication Policy

Using a text editor, set the "clientAuthPolicy" to "required" in the <chariot_install_dir>/conf/com.cirruslink.chariot.server configurationfile.

Code Block

language	text

clientAuthPolicy="required"

Warning
You will now need to restart the Chariot service to pickup up the configuration changes

Anchor
ClientSide
ClientSide
Client Side Configuration

Anchor
MQTTEngineClientSide
MQTTEngineClientSide
MQTT Engine Client Side Configuration

Add the certificates to the MQTT Engine > Servers > Certificates configuration as shown below:

Friendly Name	Certificate Filename	File Description	File Location
EngineCertificate	engine.crt	MQTT Engine Certificate	chariotcerts/certs/engine
EngineKey	engine.key	MQTT Engine Private Key	chariotcarts/certs/engine

Image Added

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. Note the URL must use SSL. If a non-secure connection is specified here, the connection will not succeed.

Image Added

Anchor
MQTTTransmissionClientSide
MQTTTransmissionClientSide
MQTT Transmission Client Side Configuration

Add certificates to the MQTT Transmission > Servers > Certificates configuration as shown below:

Friendly Name	Certificate Filename	File Description	File Location
TransmissionCertificate	transmission.crt	MQTT Transmission Certificate	chariotcerts/certs/transmisson
TransmissionKey	transmission.key	MQTT Transmission Private Key	chariotcerts/certs/transmission

Image Added

Update the MQTT Transmission > Servers > Settings configuration to use the certificates as shown below. Click the Save Changes button to save the configuration. Note the URL must use SSL. If a non-secure connection is specified here, the connection will not succeed.

Image Added

Anchor
AnonymousClientConnections
AnonymousClientConnections
Anonymous Client Connections

Chariot MQTT Server still requires MQTT credentials to authenticate incoming client connections, even when using client certificates to set up a TLS/SSL session. If clients will not be sending an MQTT username and password, anonymous connections must be enabled.

To enable anonymous connections, navigate to the Configuration → MQTT Server → Configuration tab and set Allow AnonymousImage Added

By default, an anonymous client connection will be allowed to publish and subscribe on # unless the Anonymous MQTT Credentials has been selected.

This will allow you to select any of the configured MQTT Credentials, configured under Configuration → MQTT Credentials, and MQTT Chariot will use the Publish and Subscribe ACLs for that MQTT Credential for all anonymous connections.

Info
A Password will need to be configured for this MQTT Credential but will not be used by MQTT Chariot

Anchor
VerifyConnectivity
VerifyConnectivity
Verifying Connectivity

Engine

From the left hand menu bar, navigate to Config > MQTT Engine > Servers and note the Status as Connected.

Image Added

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.

Image Added

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.

Image Added

Clicking on the drop down will show the IDs of each client along with additional details:

Image Added

Code Block

language	text

clientAuthPolicy="required"

Warning
You will now need to restart the Chariot service to pickup up the configuration changes

...

Add the certificates to the MQTT Engine > Servers > Certificates configuration as shown below:

Image Removed

Update the MQTT Engine > Servers > Settings configuration to use the certificates as shown below and setting the URL to be ssl://FQDN:8883 where the FQDN is the Common Name associated with the certificates

Image Removed

...

Add 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:

...

On the Chariot MQTT server, navigate to STATUS > MQTT and you will see Active MQTT Clients: 3

*** If you do not see MQTT Transmission connected, verify that you have a Transmitter with a valid Sparkplug ID either through setting the Group and Edge ID or through the TagPath***

Contents

Cirrus Link Resources

Versions Compared

Old Version 66

New Version Current

Key

Prerequisites

Generating Certificates and Keys

Generating Certificates and Keys

Anchor
GenerateRootCACertificate
GenerateRootCACertificate
Generate Root CA certificate

Anchor
GenerateMQTTEngineClientCertificate
GenerateMQTTEngineClientCertificate
Generate MQTT Engine Client certificate signed with the Root CA’s private key

Anchor

GenerateMQTTTransmissionClientCertificate

GenerateMQTTTransmissionClientCertificate
Generate

MQTT Transmission Client

certificate signed with the Root

CA’s private key

Setting up SSL Connections Using Two-way Authentication

Anchor
ServerSide
ServerSide
Server Side Configuration

Anchor
SetupSSLOnChariot
SetupSSLOnChariot
Setup SSL on Chariot

Anchor
ChariotTruststore
ChariotTruststore
Update Chariot Truststore

Setting up SSL Connections Using Two-way Authentication

Setup SSL on Chariot

Update Chariot Truststore

Update Chariot Clients Authentication Policy

Anchor
ChariotAuthenticationPolicy
ChariotAuthenticationPolicy
Update Chariot Clients Authentication Policy

Anchor
ClientSide
ClientSide
Client Side Configuration

Anchor
MQTTEngineClientSide
MQTTEngineClientSide
MQTT Engine Client Side Configuration

Anchor
MQTTTransmissionClientSide
MQTTTransmissionClientSide
MQTT Transmission Client Side Configuration

Anchor
AnonymousClientConnections
AnonymousClientConnections
Anonymous Client Connections

Anchor
VerifyConnectivity
VerifyConnectivity
Verifying Connectivity

Engine

Transmission

Chariot

Contents

Cirrus Link Resources

Page History

Versions Compared

Old Version 66

New Version Current

Key

Prerequisites

Generating Certificates and Keys

Generating Certificates and Keys

AnchorGenerateRootCACertificateGenerateRootCACertificateGenerate Root CA certificate

AnchorGenerateMQTTEngineClientCertificateGenerateMQTTEngineClientCertificateGenerate MQTT Engine Client certificate signed with the Root CA’s private key

Anchor

GenerateMQTTTransmissionClientCertificate

GenerateMQTTTransmissionClientCertificateGenerate

MQTT Transmission Client

certificate signed with the Root

CA’s private key

Setting up SSL Connections Using Two-way Authentication

AnchorServerSideServerSideServer Side Configuration

AnchorSetupSSLOnChariotSetupSSLOnChariotSetup SSL on Chariot

AnchorChariotTruststoreChariotTruststoreUpdate Chariot Truststore

Setting up SSL Connections Using Two-way Authentication

Setup SSL on Chariot

Update Chariot Truststore

Update Chariot Clients Authentication Policy

AnchorChariotAuthenticationPolicyChariotAuthenticationPolicyUpdate Chariot Clients Authentication Policy

AnchorClientSideClientSideClient Side Configuration

AnchorMQTTEngineClientSideMQTTEngineClientSideMQTT Engine Client Side Configuration

AnchorMQTTTransmissionClientSideMQTTTransmissionClientSideMQTT Transmission Client Side Configuration

AnchorAnonymousClientConnectionsAnonymousClientConnectionsAnonymous Client Connections

AnchorVerifyConnectivityVerifyConnectivityVerifying Connectivity

Engine

Transmission

Chariot

Anchor
GenerateRootCACertificate
GenerateRootCACertificate
Generate Root CA certificate

Anchor
GenerateMQTTEngineClientCertificate
GenerateMQTTEngineClientCertificate
Generate MQTT Engine Client certificate signed with the Root CA’s private key

GenerateMQTTTransmissionClientCertificate
Generate

Anchor
ServerSide
ServerSide
Server Side Configuration

Anchor
SetupSSLOnChariot
SetupSSLOnChariot
Setup SSL on Chariot

Anchor
ChariotTruststore
ChariotTruststore
Update Chariot Truststore

Anchor
ChariotAuthenticationPolicy
ChariotAuthenticationPolicy
Update Chariot Clients Authentication Policy

Anchor
ClientSide
ClientSide
Client Side Configuration

Anchor
MQTTEngineClientSide
MQTTEngineClientSide
MQTT Engine Client Side Configuration

Anchor
MQTTTransmissionClientSide
MQTTTransmissionClientSide
MQTT Transmission Client Side Configuration

Anchor
AnonymousClientConnections
AnonymousClientConnections
Anonymous Client Connections

Anchor
VerifyConnectivity
VerifyConnectivity
Verifying Connectivity