Mosquitto plugin

A plugin was developed especially for the Mosquitto Message Broker to enable the definition of access rights between the individual TwinCAT ADS routers.
Please also note the system requirements for operating this plugin.

The plugin is delivered with the TwinCAT installation under TwinCAT 3.1 Build 4024. Build 4026 requires the installation of the corresponding package (TwinCAT.XAE.MqttPlugin). The plugin is installed in the following directory and can be referenced from there in the Mosquitto configuration.

\TwinCAT\AdsApi\TcMqttPlugin

The plugin is available in a 32-bit and a 64-bit version, depending on which version you use of the Mosquitto Message Broker. The plugin is then integrated into the configuration of the Mosquitto Message Broker as follows: 

auth_plugin <Path>TcMqttPlugin.dll
auth_opt_xml_file <Path>MyACL.xml

The MyACL.xml file contains the access configuration to the broker itself, as well as the configuration of the communication between the connected TwinCAT ADS routers. This configuration is explained in more detail in the following section.

Configuration

The plugin offers the option of configuring virtual AMS networks. To do this, specify which device can access which other device for each target device. In contrast to the classic ADS routes, these connections are directional: A target therefore does not also have the right to access the source.

<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>EngineeringStation</Name>
    </User>
    <User>
      <Name>CX-12345</Name>
      <Access>EngineeringStation</Access>
    </User>
    <User>
      <Name>CX-56789</Name>
      <Access>EngineeringStation</Access>
    </User>
  </Ams>
</TcMqttAclConfig>

The name of the Ams network is defined within an <Ams> node. It is used in the MQTT topics employed for the identification of the networks. Individual <User> elements describe the devices. These elements have a <Name> attribute that describes the MQTT identity with which the connection was established. The identity can be transferred via various TLS mechanisms, e.g. via the TLS-PSK Identity or the CommonName (CN) of a client certificate. Our samples here show possible configuration variants.

Access-authorized devices are defined via the <Access> element. In the sample above, the "EngineeringStation" identity has access to two CX devices, but the CX devices do not have access to the "EngineeringStation" or to each other.

Mosquitto plugin 1:

The configuration file is reloaded cyclically so that a restart of the broker is not necessary.

Restrictions with regard to the AmsNetId to be registered

With this configuration each validly connected device can assume an arbitrary AmsNetId and thus an identity from the point of view of ADS. This can be further restricted as required:

<User>
  <Name>CX-56789</Name>
  <Access>EngineeringStation</Access>
  <NetId>192.168.56.1.1.1</NetId>
</User>

As soon as at least one NetId is specified, only one NetId can be registered from this list. An alternative solution would be to enter the NetId in the CommonName (CN) of the client certificate.