Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

chariotcerts/
├── 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 signed certificates to lower-level CAs, such as the Server CA and Client (MQTT Engine and Transmission) CAsMQTT 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, respectivelyNote 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

...

Navigate to the ChariotCerts parent folder to run the commands below:

Anchor
GenerateRootCACertificate
GenerateRootCACertificate
Generate Root CA certificate

  1. Generate a private key file (ca.key) for the Root CA using the command below. You will be required may choose to enter a pass phrase passphrase to be associated with the ca.key file as well.

    Tip

    Make note of this pass phrase passphrase if you set one for the Root CA private key file (ca.key) as it will be used multiple times whilst creating the certificate hierarchy.  


    Code Block
    languagetext
    openssl genrsa -des3 -out ca/ca.key 20484096


  2. 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
    languagetext
    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.


    Code Block

...

  1. language

...

  1. bash

...

  1. title

...

  1. 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.
Tip

Make note of this pass phrase for the Server CA private key file (serverCA.key) as it will be used again whilst creating the certificate hierarchy. 

Code Block
languagetext
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 for the serverCA.key file created in the previous step.

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

...

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). You will be required to enter the pass phrase associated with the Root CA private key file "ca.key". 

Code Block
languagetext
openssl x509 -req -in ca/server/serverCA.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out ca/server/serverCA.crt -days 3650
  1. Example CA Creation
    $ openssl req -new -x509 -key ca/ca.key -days 3650 -out ca/ca.crt
    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

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

We are now going to repeat this process for the remaining certificates required in the certificate hierarchy.

...

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

    TipMake 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
    languagetext
    openssl genrsa -des3 -out cacerts/engine/engineCAengine.key 20484096


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

    Code Block
    languagetext
    openssl req -new -key cacerts/engine/engineCAengine.key -out cacerts/engine/engineCAengine.csr


    Note

    There are a number of fields associated with the creation of the certificate. Fill them out with your relevant details.

  3. 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
    languagetext
    openssl x509 -req -in ca/engine/engineCA.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out ca/engine/engineCA.crt -days 3650

...

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

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
languagetext
openssl x509 -req -in ca/transmission/transmissionCA.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out ca/transmission/transmissionCA.crt -days 3650

  1. Code Block
    languagebash
    titleExample 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 []:
    $


  2. Sign the MQTT Engine Client CSR with the Engine

...

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

...

    Generate private key in PKCS8 format (server.key) for the Chariot server using the command below.

    Code Block
    languagetext
    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
    languagetext
    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
  1. CA using the command below. This command will sign the CSR "

  2. server
  3. engine.csr" with the

  4. Server
  5. Root CA certificate

  6. ‘serverCA
  7. ‘ca.crt’ and Root CA's RSA private key

  8. ‘serverCA
  9. ‘ca.key’, creating a new X.509 certificate named

  10. ‘serverCA
  11. ‘engine.crt’ valid for

  12. 3650
  13. 365 days (

  14. 10 years
  15. 1 year). You will be required to enter the

  16. pass phrase
  17. passphrase associated with the private key file "

  18. serverCA
  19. ca.key".

    Code Block
    languagetext
    openssl x509 -req -in certs/
  20. server
  21. engine/
  22. server
  23. engine.csr -CA ca/
  24. server/serverCA
  25. ca.crt -CAkey ca/
  26. server/serverCA
  27. ca.key -CAcreateserial -out certs/
  28. server
  29. engine/
  30. server
  31. engine.crt -days 
  32. 3650
  33. 365


Anchor

...

GenerateMQTTTransmissionClientCertificate

...

GenerateMQTTTransmissionClientCertificate
Generate MQTT

...

Transmission Client certificate signed with the Root CA’s private key

  1. Generate private key in PSCK8 PKCS8 format (enginetransmission.key) for MQTT Engine Transmission using the command below.

    Code Block
    languagetext
    openssl genrsa -out certs/enginetransmission/enginetransmission.key 20484096


  2. Generate a Certificate Signing Request (CSR) for MQTT Engine Transmission using the command below. This command generates a new CSR named "enginetransmission.csr’ using the RSA private key "enginetransmission.key".

    Code Block
    languagetext
    openssl req -new -key certs/enginetransmission/enginetransmission.key -out certs/enginetransmission/enginetransmission.csr


    Note

    There are a number of fields associated with the creation of the certificate. Fill them out with your relevant details.

  3. 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
    languagetext
    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

...

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

Code Block
languagetext
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
languagetext
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.

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
languagetext
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

  1. Code Block
    languagebash
    titleExample 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 []: $


  2. 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".

    Code Block
    languagetext
    openssl x509 -req -in certs/transmission/transmission.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out certs/transmission/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

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

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/
   │   ├── serverengine.crt
   │   ├── serverengine.csr
   │   └── serverengine.key
   └── transmission/
       ├── transmission.crt
       ├── transmission.csr
       └── transmission.key

...

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
File NameFile LocationCA ChainserverCA.crtchariotcerts/ca/serverPrivate Keyserver.keychariotcerts/certs/serverCertificateserver.crtchariotcerts/certs/server

 Image Removed

Where to get the file
CA ChainProvided by your Certificate Authority
Private KeyThe you generated when creating your CSR to submit to your CA
CertificateThe server certificate provided by your Certificate Authority after you submitted your CSR to them

 Image Added

Image AddedImage Removed

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

Image Added

Anchor
ChariotTruststore
ChariotTruststore
Update Chariot Truststore

...

Code Block
languagetext
keytool -importcert -file ca/engine/engineCAengine.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias ca/engine/enginecaEngineDevice


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

...

Code Block
languagetext
keytool -importcert -file ca/transmission/transmissionCA.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias ca/transmission/transmissioncaTransmissionDevice1


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

Code Block
languagetext
Keystore type: PKCS12
Keystore provider: SUN

Your keystore contains 2 entries

Alias name: enginecaenginedevice
Creation date: MarFeb 17, 20232024
Entry type: trustedCertEntry

Owner: EMAILADDRESS=ilya.binshtok@cirrus-link.com, CN=MacBook-Pro.localEngineDevice, OU=MQTT Engine CASupport, O=Cirrus Link Solutions, L=Overland ParkStilwell, ST=KansasKS, C=US
Issuer: EMAILADDRESS=ilya.binshtok@cirrus-link.com, CN=MacBook-Pro.localCN=CLS Example Root CA, OU=CASupport, O=Cirrus Link Solutions, L=Overland ParkStilwell, ST=KansasKS, C=US
Serial number: b1d46c8c88db5c8e6f689c58c0f3e7177224c5868b75fcd51bcc2e0f
Valid from: Wed MarFeb 0107 1019:3743:0845 CSTUTC 20232024 until: Sat Feb 2604 1019:3743:0845 CSTUTC 20332034
Certificate fingerprints:
         	 SHA1: FE15:3BBC:A0A7:A128:2DBE:AF15:92D9:F37F:A1E7:3CB0:8D1E:7651:ED4E:8FA0:050F:4757:EE58:A1C7:59A3:E2
        2E
	 SHA256: 8C7A:431E:80A0:B8D8:14B5:904E:7DCB:EBBF:892D:69A9:588D:FAE2:767F:29E6:3D20:503C:8FB8:3D2C:8F11:7E4F:D514:8FFF:C9AD:7CF6:5BA1:9701:0E58:DCC0:0E37:E8B3:D604:3AA7
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 20484096-bit RSA key
Version: 1
3

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


Alias name: transmissioncatransmissiondevice1
Creation date: MarFeb 17, 20232024
Entry type: trustedCertEntry

Owner: EMAILADDRESS=ilya.binshtok@cirrus-link.com, CN=MacBook-Pro.localTransmissionDevice1, OU=MQTT Transmission CASupport, O=Cirrus Link Solutions, L=Overland ParkStilwell, ST=KansasKS, C=US
Issuer: EMAILADDRESS=ilya.binshtok@cirrus-link.com, CN=MacBook-Pro.localCN=CLS Example Root CA, OU=CASupport, O=Cirrus Link Solutions, L=Overland ParkStilwell, ST=KansasKS, C=US
Serial number: b1d46c8c88db5c8f6f689c58c0f3e7177224c5868b75fcd51bcc2e11
Valid from: Wed MarFeb 0107 1619:5052:3648 CSTUTC 20232024 until: SatThu Feb 2606 1619:5052:3648 CSTUTC 20332025
Certificate fingerprints:
         	 SHA1: 0160:FD7E:41A5:DF6E:AE47:CE09:2879:A4FB:16A9:F8FE:3E24:66DB:E705:711E:FE09:8854:2F24:9848:1B19:86
         BD
	 SHA256: 9F8A:BCC8:1D39:10E1:4350:9C8B:F7BF:BE35:D625:0743:58C7:E1B4:DD66:9D60:0902:0E1E:0DAF:014F:82C4:3711:DC32:8EB0:FA6D:9AFC:3B6D:466E:1A5D:98A8:1EBE:52FA:3900:AE0B
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 20484096-bit RSA key
Version: 3   1


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

...

Friendly Name

Certificate Filename

File Description

File Location

ChariotCA_Certificate

serverCA.crt

Chariot CA Certificate

chariotcerts/ca/server

EngineCertificate

engine.crt

MQTT Engine Certificate

chariotcerts/certs/engine

EngineKey

engine.key

MQTT Engine Private Key

chariotcarts/certs/engine

Image RemovedImage 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.Image Removedbutton 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

...

chariotcerts/ca/server
Friendly NameCertificate FilenameFile DescriptionFile LocationChariotCA_CertificateserverCA.crtChariot CA Certificate
TransmissionCertificatetransmission.crtMQTT Transmission Certificatechariotcerts/certs/transmisson
TransmissionKeytransmission.keyMQTT Transmission Private Keychariotcerts/certs/transmission

Image RemovedImage Added


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

Image Added

Anchor
VerifyConnectivity
VerifyConnectivity
Verifying Connectivity

...

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

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 Removed

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 Removed

Image Added

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

Image Added