Configure Transport Layer Security (TLS)

A TLS connection between a Modbus adapter and server uses Transport Layer Security (TLS) to protect the communication between the adapter and a Modbus server through TCP/IP. Normally, Modbus/TCP does not use encryption and has no authentication, which leaves it open to interception. TLS protects this communication by providing encryption, data integrity, and authentication.

Note: TLS is disabled by default for each device in the adapter’s data source configuration. We recommend confirming that your Modbus device supports TLS prior to attempting configure it.

To use a TLS connection to a Modbus server, follow these best practices:

• Set the minTlsVersion Parameter to 1.2 or 1.3 in the Device configuration.

• Specify the ServerCertificate, as well as the ClientCertificate and ClientPrivateKey, which are common to the adapter component.

• Set the ServerCertificateDnsName parameter to the subject name of the server's certificate.

The ClientPrivateKeyPassword parameter can be set when the client private key is encrypted. The adapter protects this value when it is configured through a REST call. The adapter creates a secret and references it by ID in the data source configuration.

In most cases, use a root CA certificate as the ServerCertificate. If you wish to use a self-signed certificate, the certificateValidationMode parameter can be set to SelfSigned.

Certificates must be in PEM-encoded X.509 format. Private keys must be in PEM-encoded PKCS#1 or PKCS#8 format when unencrypted, and PKCS#8v2 when encrypted.

TLS certificates can be referenced by filename or relative path when placed in the adapter component’s Certificates directory. Alternatively, an absolute path to the certificate can be used. See Certificates for further information.

Data source example with TLS

{

"Devices": [

{

"id": "Device1_TLS",

"ipAddress": "127.0.0.1",

"port": 802,

"minTlsVersion": "1.3",

"serverCertificate": "ca_cert.pem",

"serverCertificateDnsName": "aveva.com"

},

{

"id": "Device2",

"ipAddress": "127.0.0.2",

"port": 502

},

{

"id": "Device3_TLS",

"ipAddress": "127.0.0.3",

"port": 802,

"minTlsVersion": "1.2",

"serverCertificate": "server_selfsigned.pem",

"certificateValidationMode": "SelfSigned "

}

],

"clientCertificate": "client_cert.pem",

"clientPrivateKey": "client_key.pem",

“clientPrivateKeyPassword”: “password”

}

Client certificates

You must supply a pre-generated client certificate along with a private key. The client certificate should include an x.509v3 extension with the object identifier (OID0 1.3.6.1.4.1.50316.802.1, which contains the user authorization role encoded as an ASN1:UTF8String.

Additionally, you must provide a pre-generated client certificate and private key. The client certificate must have an x.509v3 extension with the OID 1.3.6.1.4.1.50316.802.1 containing the user authorization role as an ASN1:UTF8String. If this extension does not exist or is invalid, the adapter logs a warning message but still attempts to connect and collect data from the configured devices.

You are responsible for understanding the authorization model of your Modbus servers and ensuring that the client certificate contains the appropriate role.

Note: Only a single client certificate can be referenced in an adapter component’s data source configuration. If you need to use different client certificates across your devices, separate client certificates and relevant devices must be placed in a different adapter component.

Certificate validation

The adapter performs validation of the server’s presented certificate during the TLS connection handshake. This validation differs depending on whether CertificateValidationMode is configured to AuthorityBased or SelfSigned.

The AuthorityBased validation is the default setting. In this mode, the adapter checks the presented chain of certificates and verifies that the root certificate of the chain aligns with the configured ServerCertificate. The adapter validates the chain and end entity certificate according to RFC 5280. ServerCertificateDnsName must be set in this mode to enable subject name validation.

Alternatively, SelfSigned mode checks for the following:

• A single certificate is presented

• It s a byte-for-byte match of ServerCertificate

• The Time fields on the certificate are valid.

ServerCertificateDnsName is not required because byte-for-byte comparison indirectly verifies the name.

Troubleshoot failed connections

Activating Debug-level logging for both the adapter component and the system allows detailed connection information to be accessed. If the connection or TLS handshake fails, refer to the debug-level logs for additional information.

The adapter logs a warning message when the configured client certificate is missing an authorization role. Additionally, when the configured certificates are not found, they are included in the log.