ADS-over-MQTT with TLS and X.509 certificates

In this section an example is introduced showing the configuration of ADS-over-MQTT with PSK and X.509 certificates. The individual steps to realize the communication interface are:

TwinCAT 3.1 build 4022.0 or higher is installed on system 1 as the XAE version and on system 2 as the XAR version.

1. Generate the certificates for secure communication via TLS. To do this, use the program OpenSSL, which you can download from https://www.openssl.org/source/ and then install.
Notice With a Windows operating system the path to the OpenSSL configuration file must be set as an environment variable. Do this using the command line program of an x64 system with the following command: set OPENSSL_CONF=C:\OpenSSL-Win64\bin\openssl.cfg
On completion of the installation, execute the Windows command line program. The generation of the CA certificate (Certificate Authority) begins. The entry of a pass phrase is thereby demanded. Enter it and remember it and enter further information for the CA. The corresponding command for the generation of the CA certificate is:

openssl req –new –x509 –days 60 –extensions v3_ca –keyout C:\TwinCAT\3.1\CustomConfig\Certificates\CA.key –out C:\TwinCAT\3.1\CustomConfig\Certificates\CA.crt

The result should look like this in the command line program:
ADS-over-MQTT with TLS and X.509 certificates 1:

2. Generate the broker certificate. It is important here to use as the CN (Common Name) the host name or the IP address of the system on which the Mosquitto Message Broker is to be operated. Also, it must be ensured that the system is reachable via the IP address or the host name of the client. The following commands must be executed in the command line program to generate the broker certificates:
Creating the certificate:

openssl genrsa –out C:\TwinCAT\3.1\CustomConfig\Certificates\broker.key 2048

Creating the Certificate Signing Request:

openssl req –out C:\TwinCAT\3.1\CustomConfig\Certificates\broker.csr –key C:\TwinCAT\3.1\CustomConfig\Certificates\broker.key –new

Signing of the CSR by the previously created CA, for which the password is required that was specified when creating the CA:

openssl x509 –req –in C:\TwinCAT\3.1\CustomConfig\Certificates\broker.csr –CA C:\TwinCAT\3.1\CustomConfig\Certificates\CA.crt –CAkey C:\TwinCAT\3.1\CustomConfig\Certificates\CA.key –CAcreateserial –out C:\TwinCAT\3.1\CustomConfig\Certificates\broker.crt -days 60

The result should look like this in the command line program:
ADS-over-MQTT with TLS and X.509 certificates 2:

3. Generate the two client certificates for the TwinCAT XAE and TwinCAT XAR. The OpenSSL commands for this are specified below.
Generating the XAE certificate:

openssl genrsa –out C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAE.key 2048

Creating the CSR:

openssl req –out C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAE.csr –key C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAE.key –new

Signing of the CSR by the previously created CA, for which the password is required that was specified when creating the CA:

openssl x509 –req –in C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAE.csr –CA C:\TwinCAT\3.1\CustomConfig\Certificates\CA.crt –CAkey C:\TwinCAT\3.1\CustomConfig\Certificates\CA.key –CAcreateserial –out C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAE.crt –days 60

Generating the XAR certificate:

openssl genrsa –out C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAR.key 2048

Creating the CSR:

openssl req –out C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAR.csr –key C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAR.key –new

Signing of the CSR by the previously created CA, for which the password is required that was specified when creating the CA:

openssl x509 –req –in C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAR.csr –CA C:\TwinCAT\3.1\CustomConfig\Certificates\CA.crt –CAkey C:\TwinCAT\3.1\CustomConfig\Certificates\CA.key –CAcreateserial –out C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAR.crt –days 60

The result should look like this in the command line program:
TwinCAT XAE:
ADS-over-MQTT with TLS and X.509 certificates 3:

TwinCAT XAR:
ADS-over-MQTT with TLS and X.509 certificates 4:

4. Install the Mosquitto Broker after generating the certificates. Download it from https://mosquitto.org/download/ and install it on the appropriate system.

5. Following the installation of the Mosquitto Broker, create the configuration file mosquitto_TLS.conf for it for the use of TLS with certificates. Choose the Mosquitto installation folder (default: C:\Program Files (x86)\mosquitto) as the storage location. The configuration file should contain the following entries:

port 8883
allow_anonymous false
require_certificate true
use_identity_as_username true
cafile C:\TwinCAT\3.1\CustomConfig\Certificates\CA.crt
certfile C:\TwinCAT\3.1\CustomConfig\Certificates\broker.crt
keyfile C:\TwinCAT\3.1\CustomConfig\Certificates\broker.key
auth_plugin C:\TwinCAT\AdsApi\TcMqttPlugin\TcMqttPlugin.dll
auth_opt_xml_file C:\TwinCAT\AdsApi\TcMqttPlugin\ACL.xml

6. Now start the Mosquitto Message Broker via the Windows command line program. To do this, switch to the Mosquitto installation directory and execute the command listed below. With this command, -v causes the output of the messages that are sent or rejected by the broker. This option is particularly useful during tests.
mosquitto –c mosquitto_TLS.conf –v

The subsequent result should look like this:
ADS-over-MQTT with TLS and X.509 certificates 5:

7. Next, create the ACL.xml for the Mosquitto in which the access rights of the clients are defined. Store it in the directory C:\TwinCAT\AdsApi\TcMqttPlugin\. Make the following entries in the ACL.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<TcMqttAclConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="C:\TwinCAT\3.1\Config\Modules\TcMqttAclConfig.xsd">
<Ams>
    <Topic>VirtualAmsNetwork1</Topic>
    <User>
        <Name>TwinCAT_XAE</Name>
    </User>
    <User>
        <Name>TwinCAT_XAR</Name>
        <Access>TwinCAT_XAE</Access>
    </User>
</Ams>
</TcMqttAclConfig>

8. Now configure the TwinCAT XAE and TwinCAT XAR for ADS-over-MQTT. To do this, create a folder with the name "Routes" on both systems in the directory C:\TwinCAT\3.x\Target\ in which you then generate a file with the name "MyRoute.xml" (the file name is arbitrary). The contents of the file from the TwinCAT XAE are shown below. Adapt the paths for the TwinCAT XAR in the <Cert> and <Key> fields accordingly. It is important that the same entry is always made in the <Address> field as for the CN of the Mosquitto Broker certificate.

<?xml version="1.0" encoding="ISO-8859-1"?>
<TcConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.beckhoff.com/schemas/2015/12/TcConfig">
<RemoteConnections>
    <Mqtt>
        <Address Port="8883">192.168.1.8</Address>
        <Topic>VirtualAmsNetwork1</Topic>
        <Tls>
            <Ca>C:\TwinCAT\3.1\CustomConfig\Certificates\CA.crt</Ca>
            <Cert>C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAE.crt</Cert>
            <Key>C:\TwinCAT\3.1\CustomConfig\Certificates\TwinCAT_XAE.key</Key>
        </Tls>
    </Mqtt>
</RemoteConnections>
</TcConfig>

9. Re-initialize the TwinCAT router in each case so that the stored configuration of ADS-over-MQTT becomes effective for the TwinCAT systems. This is done by switching from RUN mode to CONFIG mode or from CONFIG mode to CONFIG mode again.

Finally, check whether a connection can be established from the XAE to the XAR. If so, the outputs of the Mosquitto Message Broker should look like this:
ADS-over-MQTT with TLS and X.509 certificates 6:

ADS-over-MQTT with TLS and X.509 certificates 6:

ADS-over-MQTT with certificate-based TLS has thus been successfully set up for TwinCAT XAE and XAR.