Instructions for creating key pairs and certificates for use with AUTOSOL Edge products. Prerequisite:
OpenSSL is installed and in your system PATH.
For Debian Linux, you may check to see if openssl is installed and on your PATH using the which command:
$ openssl which
Where the expected output is the file path where openssl is installed. Example:
$ which openssl/usr/bin/openssl
If openssl is not installed, you will see nothing. The most straightforward way to install openssl in Debian is by using the package manager:
sudo apt-get update && sudo apt-get install openssl
Once openssl is installed you can create your certificate chain.
How you create your certificate chain depends on your desired security posture. There are two options:
TLS with Server Certificate Authentication
TLS with Server and Client Certificate Authentication
Steps for Creating Certificates for Server Authentication
For this step, the server (the broker) authenticates to the client with a certificate before the TLS connection is established. The client does not authenticate to the broker with a certificate, but may do so through other means (password, etc.).
The outputs for this process are:
ca.key file - to be kept private to (this) system that generated it.
ca.pem file - public certificate authority (self signed) certificate, to be distributed.
server.key file - to be kept private to where the MQTT broker (the TLS server) resides.
server.pem file - public server certificate, to be distributed to the MQTT broker.
One or more server certificates can be created, one for each MQTT broker. The server certificate contains the IP or hostname of that server. During TLS session establishment, the TLS client (eACM-MQTT, Bridge, Edge Manager, etc.) will compare the IP or hostname that it is connecting to with the CN (Common Name) presented by the server certificate. If there is a match, the TLS client will attempt to connect to the server. If not, the TLS client will drop the connection and regard it as unverified and untrusted. You may choose to break this rule by unchecking the “Verify Certificate” box (not recommended).
Leaving the “Verify Certificate” box unchecked may expose your TLS client to Man-in-the-Middle attacks. You have an encrypted connection, but have not proven to whom you are connected.
The inputs for this process are:
Hostname or IP of your MQTT broker’s server, to be used in the CN of the server certificate
Password for ca.key (optional)
Password for server.key (optional)
The exact steps in this process can be varied according to your needs. What follows is an example.
Create the key pair (ca.key) used by your certificate authority. To protect it with a password (you will be prompted):
openssl genrsa -aes256 -out ca.key
To create ca.key without a password:
openssl genrsa -out ca.key 2048
Create the self signed certificate authority certificate (ca.pem). If you used a password when creating ca.key, you will be prompted for it.
openssl req -new -x509 -days 3650 -extensions v3_ca -key ca.key -out ca.pem -subj "/C=US/ST=Texas/O=THIS_COMPANY INC/CN=John Smith/emailAddress=johnsmith@gmail.com" --outform PEM
Create the key pair (server.key) used by your broker.
It is important to note that this step can (and probably should) take place where broker is installed and kept private there.
To protect it with a password (you will be prompted):
openssl genrsa -aes256 -out server.key
To create server.key without a password:
openssl genrsa -out server.key 2048
Create the certificate signing request for the server (the broker), server.csr. If you created ca.key on a different machine, you will need to copy server.csr to that machine.
If you protected server.key with a password, you will be prompted.
In this example, you will need to substitute 10.3.0.11 with the IP or hostname of your broker’s server for TLS verification to work correctly.
openssl req -out server.csr -key server.key -new -subj "/C=US/ST=Texas/O=THIS_COMPANY INC/CN=10.3.0.11/emailAddress=johnsmith@gmail.com" --outform PEM
The server certificate’s CN field should match the hostname or IP of the MQTT broker.
Create the server certificate (server.pem). The step must take place where you have your ca.key. The server.csr and ca.pem files are also required. If you used a password when creating your ca.key, you will be prompted for it.
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out server.pem -days 3650 --outform PEM
Configuration
You now have all the files required to configure your client and server (broker) for TLS authentication.
You will need to provide ca.pem to both your client and server.
You will need to provide server.key and server.pem to your server.
Client
In older versions of eACM, you must copy (scp) your ca.pem to the host where eACM is installed and reference the path to it in your TLS Settings object (MQTT app) or the Broker 1/2 tab of your Node object (Edge Manager). Assign ca.pem to the CA File property of the object.
In newer versions of eACM, you can upload your ca.pem using the TLS Settings object form or Node object form. Assign ca.pem to the CA File property of the object.
Server (Broker)
The broker configuration will be different for each broker. Example for mosquitto:
per_listener_settings true listener 8883 allow_anonymous false require_certificate false certfile C:\Users\myuser\Documents\certs\server.pem keyfile C:\Users\myuser\Documents\certs\server.key cafile C:\Users\myuser\Documents\certs\ca.pem password_file C:\Users\myuser\Documents\mosquitto\user-passwd.txt
Steps for Creating Certificates for Client Authentication
For this step, the client (the eACM MQTT app, Bridge, Edge Manager, etc.) authenticates to the server with a certificate before the TLS connection is fully established. This takes place after the server has authenticated to to the client with its own (server) certificate.
All of the steps above under “Steps for Creating Certificates for Server Authentication” must be completed first before proceeding.
Create one key pair and one certificate for each uniquely identifiable client desired.
Whether you create one client certificate to share among your MQTT clients -or- each MQTT client has its own certificate is dictated by your organization’s IT security posture.
Repeat this process for each key pair and client certificate that your logistics and security posture dictate.
The outputs for this process are:
client.key - to be kept private to the MQTT client(s) that use the key pair for authentication
client.pem - public client certificate used for authenticating to the server (the MQTT broker)
The inputs for this process are:
Password for client.key
Common Name (CN) to identify your client certificate (optional). MQTT brokers can be configured to authenticate using the CN in the Subject field.
Create client.key. You will be prompted for a password.
openssl genrsa -aes256 -out client.key
Create the certificate signing request for the client (the MQTT client), client.csr. If you created ca.key on a different machine, you will need to copy client.csr to that machine.
You will be prompted for the password used when creating client.key.
If your broker is configured to authenticate based on the CN section of the Subject field, substitute MyEACM for something else that meaningfully identifies that particular MQTT client or its permissions role on the broker.
openssl req -out client.csr -key client.key -new -subj "/C=US/ST=Texas/O=THIS_COMPANY INC/CN=MyEACM/emailAddress=johnsmith@gmail.com" --outform PEM
Create the client certificate (client.pem). The step must take place where you have your ca.key. The client.csr and ca.pem files are also required. If you used a password when creating your ca.key, you will be prompted for it.
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out client.pem -days 3650 --outform PEM
Configuration
You now have all the files required to configure your client and server (broker) for TLS authentication with both server authentication and client authentication.
You will need to provide ca.pem to both your client and server.
You will need to provide server.key and server.pem to your server.
You will need to provide client.key and client.pem to each client. The client will also need to be provided with the password used to encrypt its client.key.
Client
In older versions of eACM, you must copy (scp) your ca.pem, client.key and client.pem to the host where eACM is installed and reference the path to it in your TLS Settings object (MQTT app) or the Broker 1/2 tab of your Node object (Edge Manager).
In newer versions of eACM, you can upload your ca.pem, client.key and client.pem using the TLS Settings object form or Node object form.
Assign ca.pem to the CA File property of the object.
Assign client.key to the Client Private Key property of the object.
Assign client.pem to the Client Certificate property of the object.
Assign the password used to encrypt client.key to Private Key Password.
Server (Broker)
The broker configuration will be different for each broker. Example for mosquitto:
per_listener_settings true listener 8883 allow_anonymous false require_certificate true certfile C:\Users\myuser\Documents\certs\server.pem keyfile C:\Users\myuser\Documents\certs\server.key cafile C:\Users\myuser\Documents\certs\ca.pem use_identity_as_username true acl_file C:\Users\myuser\Documents\mosquitto\acl_8883.txt
Where acl_8883.txt may contain by example:
user MyEACM topic read STATE/+ topic readwrite spBv1.0/# user SparkplugViewer topic read STATE/+ topic read spBv1.0/# user HMI topic readwrite STATE/+ topic readwrite spBv1.0/#
What to do when authentication fails
When the MQTT client (eACM, Edge Manager or Bridge) fail to connect to the broker the first thing to do is to enable logging on your MQTT broker. Then compare the broker logging in the context of logging from eACM.
The most commonly encountered error is that the connection (almost succeeded) and fails whenever the server authenticates to the client. The client will then drop the connection to the broker at the last minute. This is almost always a symptom of the broker’s certificate CN field not including the IP or hostname of the broker. A shortcut to resolving this scenario is unchecking the Verify Certificate box in eACM. The connection will still be encrypted in this case. However, since the client has not proven it is connected to what it expects to be the right broker … any username or password it provides can be sent to that (possibly) impersonating broker.
Search the log for OpenSSL errors in order to deduce the source of the failure.
If you are using mosquitto you may do so by editing mosquitto.conf. Example:
log_dest file C:\Users\myuser\Documents\mosquitto\mosquitto.log log_type error log_type warning log_type notice log_type information log_timestamp true log_timestamp_format %Y-%m-%dT%H:%M:%S