TLS

The TCP transport with a TLS layer on top, authenticated with certificates. Everything a driver sends is encrypted in transit; nothing about the protocol above changes, so any driver that supports tcp and declares tls can be switched over by changing the transport code alone.

Transport syntax

{IP address or hostname}[:{port}]

The port is not switched to a secure default for you. A protocol whose plain-text default is 502 still defaults to 502 here - name the TLS port explicitly if the device listens elsewhere.

Example

modbus-tcp:tls://192.168.1.100:802?tls.trust-store=/etc/plc4x/truststore.p12&tls.trust-store-password=secret

Name

Type

Default Value

Required

Description

Name

TLS

Code

tls

Maven Dependency

<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-transports-tls</artifactId>
  <version>1.1.0</version>
</dependency>

Config options:

tls.verify

BOOLEAN

true

tls.ignore-common-name

BOOLEAN

false

Accept a server certificate issued for a different host than the one connected to

tls.trust-store

STRING

Key store of certificates to trust, instead of the JVM’s public authorities

tls.trust-store-password

STRING

Password of the trust store named by tls.trust-store

tls.trust-store-type

STRING

PKCS12

Type of the trust store named by tls.trust-store

tls.version

STRING

TLS protocol version (e.g., 'TLSv1.2', 'TLSv1.3'). If not set, uses TLS 1.3 with fallback to TLS 1.2.

tls.keystore

STRING

Path to keystore (PKCS12/JKS) containing the client certificate and private key for mutual TLS.

tls.keystore-password

STRING

Password for the client keystore.

tls.keystore-type

STRING

Keystore type (e.g., 'PKCS12', 'JKS'). Defaults to PKCS12.

tls.log-session-keys

BOOLEAN

false

Log TLS session keys to the audit log in SSLKEYLOGFILE format for Wireshark decryption.

tls.connect-timeout-ms

INT

5000

Connection timeout in milliseconds.

tls.read-timeout-ms

INT

Socket read timeout in milliseconds. 0 means no timeout.

tls.write-timeout-ms

INT

Socket write timeout in milliseconds. 0 means no timeout.

tls.no-delay

BOOLEAN

true

Enable TCP_NODELAY (disable Nagle’s algorithm).

tls.keep-alive

BOOLEAN

false

Enable SO_KEEPALIVE.

tls.send-buffer-size

INT

81920

Send buffer size in bytes. 0 uses system default.

tls.receive-buffer-size

INT

81920

Receive buffer size in bytes. 0 uses system default.

tls.local-address

STRING

Local address to bind to (optional). If not set, uses default.

tls.local-port

INT

Local port to bind to (optional). 0 uses ephemeral port.

The socket options below the TLS-specific ones are inherited from the TCP transport.

Certificates

By default the JVM’s own list of public certificate authorities is used, which is rarely what a plant network wants. Point tls.trust-store at a keystore holding the certificates you are willing to trust instead, and tls.keystore at your own certificate and private key when the device asks the client to authenticate as well (mutual TLS).

tls.verify=false turns TLS into encryption without authentication - it stops eavesdropping but not an attacker who can redirect your traffic. tls.ignore-common-name=true is the narrower escape hatch for the common case of a device whose certificate was issued for a name it is no longer reachable under. Both exist for bringing a line up; neither belongs in a running plant.