You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 66 Next »

This document describes how to configure Server and Client authentication when setting secure (SSL) connections between Chariot, MQTT Engine and MQTT Transmission.

Prerequisites

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 CAs. When the Root CA issues a CA certificate to a lower-level CA, it signs the certificate with its private key, which allows clients to verify the authenticity of the CA certificate 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

Generate Root CA certificate signed with the Root CA

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

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

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

    openssl req -new -x509 -key ca/ca.key -days 3650 -out ca/ca.crt

    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 Server CA certificate signed with the Root CA

  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.

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

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

    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

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

    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 MQTT Engine Client CA certificate signed with the Root CA

  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. 

    openssl genrsa -des3 -out ca/engine/engineCA.key 2048

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

    openssl req -new -key ca/engine/engineCA.key -out ca/engine/engineCA.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 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

  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). An "engineCA.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".

    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 MQTT Transmission Client CA certificate signed with the Root CA

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

    openssl genrsa -des3 -out ca/transmission/transmissionCA.key 2048

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

    openssl req -new -key ca/transmission/transmissionCA.key -out ca/transmission/transmissionCA.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 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

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

    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


Generate Server certificate signed with Server CA private key

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

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

    ******* Convert from PKCS8 format to PCKS1 until Chariot supports PKCS8 format *********

    openssl rsa -in certs/server/server.key -traditional -out certs/server/server.keyopen

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

    openssl req -new -key certs/server/server.key -out certs/server/server.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 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.

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

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

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

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

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

    openssl req -new -key certs/engine/engine.key -out certs/engine/engine.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 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.

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

    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 365

Generate MQTT Transmission Client certificate signed with the Transmission CA’s private key

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

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

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

    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.

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

    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. 

Server Side Configuration

Setup SSL on Chariot

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

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 configuration file as the "trustStorePassword" parameter.

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:

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:

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


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

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

clientAuthPolicy="required"


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

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 where the FQDN is the Common Name associated with the certificates

MQTT Transmission Client Side Configuration

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

Friendly NameCertificate FilenameFile Description
ChariotCA_CertificateserverCA.crtChariot CA Certificate
TransmissionCertificatetransmission.crtMQTT Transmission Certificate
TransmissionKeytransmission.keyMQTT Transmission Private Key

Update the MQTT Transmission > Servers > Settings configuration to use the certificates as shown below:

Configuration FieldSetting
URLssl://FQDN:8883 where the FQDN is the Common Name associated with the certificates
CA Certificate FileChariotCA_Certificate
Client Certificate FileTransmissionCertificate
Client Private Key FileTransmissionKey


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



  • No labels

New to MQTT? Start Here!