[Feature Request]: Secure ADS with Beckhoff ADS PLC

[UserwithnoUsername]

What happened?

Setup or own a Beckhoff/BSD PLC. For Testing you can Download the .iso from Official Beckhoff Website. Setup in Combination with VirtualBox with the following Script in Linux. Load a sample Beckhoff Project with TWINCat

#!/usr/bin/env bash
#
#  create_tcbsd_vm.sh
#  Erstellt eine VirtualBox-VM für TwinCAT BSD unter Linux/macOS
#  (getestet mit VirtualBox ≥ 6.1)
#

set -euo pipefail

# ‑-- Standardwerte ‑--------------------------------------
TCBSD_ISO_DEFAULT="TCBSD-x64-14-203719.iso"
VBOX_PATH_DEFAULT="$(command -v VBoxManage || true)"

# ‑-- Hilfsfunktionen ‑------------------------------------
usage() {
  cat <<EOF
Verwendung: $0 -n <VM-Name> [-i <TwinCAT-ISO>] [-p <Pfad zu VBoxManage>]

  -n   Name der Virtuellen Maschine (erforderlich)
  -i   TwinCAT-BSD-Abbild (ISO/IMG); Standard: ${TCBSD_ISO_DEFAULT}
  -p   Pfad zu VBoxManage;            Standard: automatisch ermittelt

Beispiel:
  $0 -n TcBSD-VM
EOF
  exit 1
}

ask_yes_no() {
  local prompt="$1"
  read -rp "$prompt [Y/N] " answer
  [[ "${answer^^}" == "Y" ]]
}

err() { echo "Fehler: $*" >&2; exit 1; }

# ‑-- Argumente auswerten ‑------------------------------
VM_NAME=""
TCBSD_ISO="$TCBSD_ISO_DEFAULT"
VBOX_PATH="$VBOX_PATH_DEFAULT"

while getopts ":n:i:p:h" opt; do
  case "$opt" in
    n) VM_NAME="$OPTARG" ;;
    i) TCBSD_ISO="$OPTARG" ;;
    p) VBOX_PATH="$OPTARG" ;;
    h|*) usage ;;
  esac
done

[[ -z "$VM_NAME" ]] && usage
[[ -z "$VBOX_PATH" ]] && err "VBoxManage konnte nicht gefunden werden. Geben Sie den Pfad mit -p an."

WORK_DIR="$(pwd)"
VMDIR="${WORK_DIR}/${VM_NAME}"
INSTALLER_VDI="${VMDIR}/TcBSD_installer.vdi"
RUNTIME_VHD="${VMDIR}/TcBSD.vhd"

echo "Arbeitsverzeichnis:  $WORK_DIR"
echo "VM-Name:             $VM_NAME"
echo "TwinCAT-Abbild:      $TCBSD_ISO"
echo "VBoxManage:          $VBOX_PATH"
echo

# ‑-- VirtualBox prüfen / ggf. installieren ‑-------------
if [[ ! -x "$VBOX_PATH" ]]; then
  echo "VirtualBox wurde nicht gefunden: $VBOX_PATH"
  if ask_yes_no "Möchten Sie VirtualBox jetzt installieren?"; then
    if command -v apt-get &>/dev/null; then
      sudo apt-get update
      sudo apt-get install virtualbox
    elif command -v dnf &>/dev/null; then
      sudo dnf install VirtualBox
    else
      err "Automatische Installation wird auf diesem System nicht unterstützt."
    fi
    VBOX_PATH="$(command -v VBoxManage)"
  else
    err "Abbruch: Bitte VirtualBox manuell installieren."
  fi
fi

# ‑-- ISO-Datei vorhanden? ‑------------------------------
if [[ ! -f "$TCBSD_ISO" ]]; then
  echo "TwinCAT-ISO $TCBSD_ISO nicht gefunden."
  echo "Bitte von der Beckhoff-Website herunterladen und ins aktuelle Verzeichnis kopieren."
  echo "Download-Seite wird geöffnet …"
  xdg-open "https://www.beckhoff.com/de-de/produkte/ipc/software-and-tools/operating-systems/c9900-s60x-cxxxxx-0185.html" &>/dev/null || true
  exit 1
fi

# ‑-- VM anlegen ‑----------------------------------------
echo "Erstelle Virtuelle Maschine '$VM_NAME' …"
"$VBOX_PATH" createvm        --name "$VM_NAME" \
                             --basefolder "$WORK_DIR" \
                             --ostype FreeBSD_64 --register

"$VBOX_PATH" modifyvm "$VM_NAME" \
        --memory 1024 --vram 128 \
        --acpi on   --hpet on \
        --graphicscontroller vmsvga \
        --firmware efi64

# ‑-- Abbild konvertieren ‑------------------------------
echo "Konvertiere Installations-Abbild → VDI …"
mkdir -p "$VMDIR"
"$VBOX_PATH" convertfromraw --format VDI "$TCBSD_ISO" "$INSTALLER_VDI"

# ‑-- SATA-Controller & Medien einrichten ‑---------------
echo "Erstelle SATA-Controller …"
"$VBOX_PATH" storagectl "$VM_NAME" \
        --name SATA --add sata --controller IntelAhci \
        --hostiocache on --bootable on

echo "Binde Installer-VDI an Port 1 …"
"$VBOX_PATH" storageattach "$VM_NAME" \
        --storagectl SATA --port 1 --device 0 --type hdd --medium "$INSTALLER_VDI"

echo "Erstelle leere System-Festplatte (4 GiB VHD) …"
"$VBOX_PATH" createmedium --filename "$RUNTIME_VHD" --size 4096 --format VHD

echo "Binde System-Festplatte an Port 0 …"
"$VBOX_PATH" storageattach "$VM_NAME" \
        --storagectl SATA --port 0 --device 0 --type hdd --medium "$RUNTIME_VHD"

# ‑-- VM starten ‑---------------------------------------
echo
echo "Starte die VM – folgen Sie den TwinCAT-BSD-Installationsschritten."
"$VBOX_PATH" startvm "$VM_NAME" --type gui

echo "Fertig."

Run Example Code:

import org.apache.plc4x.java.api.PlcConnection;
import org.apache.plc4x.java.api.PlcDriverManager;
import org.apache.plc4x.java.api.authentication.PlcUsernamePasswordAuthentication;
import org.apache.plc4x.java.api.messages.PlcReadRequest;
import org.apache.plc4x.java.api.messages.PlcReadResponse;

import java.util.concurrent.TimeUnit;

public class AdsDemo {
    public static void main(String[] args) throws Exception {

        String connectionString =
                "ads:tcp://192.168.1.120:8016?" +
                        "target-ams-net-id=192.168.1.120.1.1&target-ams-port=851&" +
                        "source-ams-net-id=192.168.1.233.1.1&source-ams-port=32905";

        PlcUsernamePasswordAuthentication authentication = new PlcUsernamePasswordAuthentication("Administrator", "2");
        try (PlcConnection plcConnection = PlcDriverManager.getDefault().getConnectionManager().getConnection(connectionString, authentication)) {

            // Build a read request (PLC4J-0.12 uses addTag; addItem also works)
            PlcReadRequest readReq = plcConnection.readRequestBuilder()
                    .addTagAddress("nbool", "MAIN.nbool")   // or %MX0.0:BOOL
                    .addTagAddress("nint", "MAIN.nCounter")
                    .build();

            PlcReadResponse resp = readReq.execute().get(3, TimeUnit.SECONDS);
            boolean flag = resp.getBoolean("nbool");
            System.out.println("MAIN.nbool = " + flag);
            int counter = resp.getInteger("nint");
            System.out.println("MAIN.nCounter = " + counter);
        }

    }
}

Route gets Created:

Error During Runtime if unsecure Port is disabled in firewall like its default for the BSD version of Twincat.

For further Information simply Ask.

with regards

Version

v0.12.0

Programming Languages

• plc4c
• plc4go
• plc4j
• plc4net
• plc4py

Protocols

• AB-Ethernet
• ADS /AMS
• BACnet/IP
• C-Bus
• CANopen
• EtherNet/IP
• Firmata
• IEC-69870
• KNXnet/IP
• Modbus
• OPC-UA
• Profinet
• S7
• S7-light

[chrisdutz]

I would rather call this a feature request. Supporting secure communication, definitely needs implementation on the client side. It's definitely nothing that works without changes. Didn't even know that exists til now.

[UserwithnoUsername]

Should i close this Issue and Recreate it as an Feature or will you rename the Issue?

For further Information:
German Beckhoff Secure ADS

Englisch

The Port Used is 8016

With Regards and thank you for the fast reply!

[chrisdutz]

Let me try if I can rename it.

[chrisdutz]

However, the problem will be implementing it. I will most probably have a look at it, but I have stopped fixing bugs and implementing features for free.

Are you willing to donate for me to address this, or will you wait for someone else to do it for you? The other alternative would be you implement it, then I'll be happy to act as your mentor.

[UserwithnoUsername]

Main Reason to add this was that no other Library at the moment has the capabilities to make use of Secure ADS.

I think i will first Try to fix that Issue on my own. But i am only able to add it to the Java Version, because it´s my Primary Programming Language.

If i understand it right .mspec is a Templating language which gives the Ability to Create "base" classes for each of the contained languages.

So i think i start with Comparing Connection Building with Wireshark for the Secure Connection with TwinCAT and the Connection buildup in plc4x

In the Configuration Settings i should switch depending on the Port 48898 or 8016. So i need to add the SSL Handling without a more Complex Configuration file?

All the Classes in the generated folder should be Only Changed over the .mspec File

In the Path plc4j/drivers/org/apache/plc4x/java/ads/ i can test out my changes to fix this issue? Without my edited parts get Overridden by Code generation?

Just for my Information. I just want to try out some stuff with the TwinCAT/BSD Version to learn some new stuff. Which amount has to be donated that you will address the Issue? I read a lot of your Interviews and i understand your PoV.

Best Regards Thomas

[chrisdutz]

Generally, I would say you'd be on the right track. However, observing tls secured connection via wireshark will not help unless you can provide the session key.

However, I had a gut feeling that Beckhoff might have done something more sensible than Siemens with s7comm Pluss, where they mixed in the tls in the middle between multiple layers of the protocol.

Beckhoff seems to simply use tls secured tcp and tunnel ordinary ads via that.

In theory you wouldn't need to adjust anything in the mspec. Also, should the protocol code most probably not need changing.

I could imagine implementing a new transport should be enough.

With that something like ads:tls-tcp://hostname... Could be enough.

A quick check showed me that netty generally has this available.

But regarding your other questions: yes you were correct. Mspec -> src/main/generated
src/main/Java is not automatically updated. If you need to change the mspec in a way that breaks implementations in other languages, you would create a new version of the mspec and use that. This way we don't have to disable drivers in other languages til someone has the time to fix things.

Hope that helps as a starting point. If you have questions, feel free to ask. I'm always happy to help that way.

I guess I'd implement it for something round 600€ (assuming my research during the first coffee of the morning wasn't compketely wrong 😂)

[chrisdutz]

Here some links:
https://download.beckhoff.com/download/document/automation/twincat3/Secure_ADS_EN.pdf
"Secure ADS is an additional transport channel from the point of view of the ADS protocol. Precisely the
same ADS commands are transmitted via a secure connection as via other communication protocols."

[chrisdutz]

Another approach, might be not to implement a new transport, but a second driver class, which generally only adds one more layer to the stack. (Or leave it at one, but add a configuration option).

This code is just ChatGPT made-up stuff, but the part here it adds the sslCtx.newHandler looks legit and it pretty much in-line with what I saw elsewhere.

SslContext sslCtx = SslContextBuilder
    .forClient()
    .trustManager(new File("your-truststore.crt")) // or use InsecureTrustManagerFactory.INSTANCE for testing
    .build();

Bootstrap bootstrap = new Bootstrap();
bootstrap.group(group)
         .channel(NioSocketChannel.class)
         .handler(new ChannelInitializer<SocketChannel>() {
             @Override
             public void initChannel(SocketChannel ch) {
                 ChannelPipeline p = ch.pipeline();
                 p.addLast(sslCtx.newHandler(ch.alloc(), "remote-ip", 8016));
                 p.addLast(new AdsFrameDecoder());  // Your ADS parser/decoder
                 p.addLast(new AdsClientHandler());
             }
         });

[UserwithnoUsername]

Update:

My Current State is adding the Code at the AdsProtocolLogic. Especial because I want to use the PlcUsernamePasswordAuthentication for the the PSK Exchange. Later on i also can split it on a own Transport. But currently u can Configure it like this:

        //NONE
        String connectionString2 =
            "ads:tcp://192.168.1.104:48898?" +
                "target-ams-net-id=192.168.1.104.1.1&target-ams-port=851&" +
                "source-ams-net-id=192.168.1.233.1.1&source-ams-port=32905&" +
                "tls-encryption=NONE";

        // TLS = PSK (Pre-Shared Key)
        String connectionStringPsk =
            "ads:tcp://192.168.1.104:48898?" +
                "target-ams-net-id=192.168.1.104.1.1&target-ams-port=851&" +
                "source-ams-net-id=192.168.1.233.1.1&source-ams-port=32905&" +
                "tls-encryption=PSK&";

        // TLS = SSC (certificate-based) – existing example
        String connectionStringCert =
            "ads:tcp://192.168.1.104:8016?" +
                "target-ams-net-id=192.168.1.104.1.1&target-ams-port=851&" +
                "source-ams-net-id=192.168.1.233.1.1&source-ams-port=32905&" +
                "tls-encryption=SSC&" +
                "ca-file=/opt/certs/ca.crt&" +
                "cert-file=/opt/certs/client.crt&" +
                "key-file=/opt/certs/client.key";

Feel free to look at the Implementation in my Fork.
Fork

All Code is Cited from the Testing Main in all Exceptions are there also as Comment:
src/main/java/org/apache/plc4x/Main.java

Now during the Test and Tryouts i had the following Errors / Issues:

On Linux i can add a Route with but the reading part throws the following Error Message:

Entry

try (PlcConnection plcConnection = PlcDriverManager.getDefault().getConnectionManager().getConnection(connectionString, authentication))

Result

            Error connecting to the PLC: java.util.concurrent.ExecutionException: org.apache.plc4x.java.api.exceptions.PlcIoException: Connection terminated by remote
            [plc4x-tm-thread-1] INFO org.apache.plc4x.java.spi.transaction.RequestTransactionManager - Got an error executing transaction
            io.netty.channel.StacklessClosedChannelException
            	at io.netty.channel.AbstractChannel$AbstractUnsafe.write(Object, ChannelPromise)(Unknown Source)
            [pool-2-thread-1] WARN io.netty.channel.AbstractChannelHandlerContext - Failed to submit an exceptionCaught() event.
            java.util.concurrent.RejectedExecutionException: event executor terminated
            	at io.netty.util.concurrent.SingleThreadEventExecutor.reject(SingleThreadEventExecutor.java:934)
            	at io.netty.util.concurrent.SingleThreadEventExecutor.offerTask(SingleThreadEventExecutor.java:353)
            	at io.netty.util.concurrent.SingleThreadEventExecutor.addTask(SingleThreadEventExecutor.java:346)
            	at io.netty.util.concurrent.SingleThreadEventExecutor.execute(SingleThreadEventExecutor.java:836)
            	at io.netty.util.concurrent.SingleThreadEventExecutor.execute0(SingleThreadEventExecutor.java:827)
            	at io.netty.util.concurrent.SingleThreadEventExecutor.execute(SingleThreadEventExecutor.java:817)
            	at io.netty.channel.AbstractChannelHandlerContext.invokeExceptionCaught(AbstractChannelHandlerContext.java:328)
            	at io.netty.channel.DefaultChannelPipeline.fireExceptionCaught(DefaultChannelPipeline.java:856)
            	at org.apache.plc4x.java.ads.protocol.AdsProtocolLogic.lambda$2(AdsProtocolLogic.java:227)
            	at org.apache.plc4x.java.spi.Plc4xNettyWrapper.lambda$8(Plc4xNettyWrapper.java:273)
            	at org.apache.plc4x.java.spi.netty.NettyHashTimerTimeoutManager.lambda$0(NettyHashTimerTimeoutManager.java:55)
            	at io.netty.util.HashedWheelTimer$HashedWheelTimeout.run(HashedWheelTimer.java:713)
            	at io.netty.util.concurrent.ImmediateExecutor.execute(ImmediateExecutor.java:34)
            	at io.netty.util.HashedWheelTimer$HashedWheelTimeout.expire(HashedWheelTimer.java:701)
            	at io.netty.util.HashedWheelTimer$HashedWheelBucket.expireTimeouts(HashedWheelTimer.java:788)
            	at io.netty.util.HashedWheelTimer$Worker.run(HashedWheelTimer.java:501)
            	at java.base/java.lang.Thread.run(Thread.java:1583)
            [pool-2-thread-1] WARN io.netty.channel.AbstractChannelHandlerContext - The exceptionCaught() event that was failed to submit was:
            java.util.concurrent.TimeoutException
            	at org.apache.plc4x.java.spi.netty.NettyHashTimerTimeoutManager.lambda$0(NettyHashTimerTimeoutManager.java:54)
            	at io.netty.util.HashedWheelTimer$HashedWheelTimeout.run(HashedWheelTimer.java:713)
            	at io.netty.util.concurrent.ImmediateExecutor.execute(ImmediateExecutor.java:34)
            	at io.netty.util.HashedWheelTimer$HashedWheelTimeout.expire(HashedWheelTimer.java:701)
            	at io.netty.util.HashedWheelTimer$HashedWheelBucket.expireTimeouts(HashedWheelTimer.java:788)
            	at io.netty.util.HashedWheelTimer$Worker.run(HashedWheelTimer.java:501)
            	at java.base/java.lang.Thread.run(Thread.java:1583)

After running the Command with Authentication i have a route which works if i leave the authentication Empty. Like On the following

Entry

try (PlcConnection plcConnection = PlcDriverManager.getDefault().getConnectionManager().getConnection(connectionString, authentication))
Result:

            [nioEventLoopGroup-3-1] INFO org.apache.plc4x.java.spi.codegen.fields.FieldReaderReserved - Expected constant value 0 but got 4 for reserved field reserved.
            [nioEventLoopGroup-3-1] INFO org.apache.plc4x.java.spi.codegen.fields.FieldReaderReserved - Expected constant value 0 but got 4 for reserved field reserved.
            [nioEventLoopGroup-3-1] INFO org.apache.plc4x.java.spi.codegen.fields.FieldReaderReserved - Expected constant value 0 but got 4 for reserved field reserved.
            [nioEventLoopGroup-3-1] INFO org.apache.plc4x.java.spi.codegen.fields.FieldReaderReserved - Expected constant value 0 but got 4 for reserved field reserved.
            MAIN.nbool = false
            MAIN.nCounter = 1253

I get the right results

That´s just my current findings. About the Library in general but now go further to the Tls Implementation. My first Test will be the SSC because this is per default active. PSK will be following up because i have already added it to my test Setup.

Currently I add the SSC like this in the AdsProtocolLogic:

        if (configuration != null && configuration.getTls() != null && configuration.getTls() != TLS.NONE) {
            try {

                SslContextBuilder builder = SslContextBuilder.forClient();


                switch (configuration.getTls()) {
                    case SSC:
                        File ca   = new File(configuration.getCaFile());
                        File cert = new File(configuration.getCertFile());
                        File key  = new File(configuration.getKeyFile());
                        //Todo Exchange this with the LINE below when running
                        builder.trustManager(ca)
                            .keyManager(cert, key);
                        SslContext sslCtx = builder
                            .protocols("TLSv1.2")
                            .ciphers(Collections.singletonList("TLS_DHE_RSA_WITH_AES_256_CBC_SHA256"), SupportedCipherSuiteFilter.INSTANCE)
                            .trustManager(InsecureTrustManagerFactory.INSTANCE)
                            .build();


                        //eng.setEnabledProtocols(new String[]{"TLSv1.2"});
                        SslHandler sslHandler = sslCtx.newHandler(context.getChannel().alloc(), "PLC4J", 8016);
                        context.getChannel().pipeline().addFirst("ssl", sslHandler);
                        break;

Which adds the route. But the Connection is Dropped before Application Data is send:

Npcap: PLC4J npcap:

Original Beckhoff add Route npcap:

Currently i try do decrypt the SSL Connection but mitmproxy hasn´t worked and Beckhoff is not using any Library like OpenSSL which has the SSLKEYLOGFILE Environment Variable for decrypting the Message Protocol.

So i have the following Questions:

• How can we guarantee a Request with Username and Password receiving also Values?

TLS Related

• Do you have any Idea how to decrypt the Twincat TLS or can u ask someone if the Connection needs to be handled otherwise when using TLSv1.2.
• Especially i will need the Encryption sequence when i want to add the PSK. Because with PSK you don´t have any Username and Password Combination
• Do you have any further Ideas what i can try further?

I try to add in the Weekend some Information for my first Impressions about plc4x How to seed community engagement? because i have fallen during my Job sometimes over this library and in the end i always decided for another library, for different reasons. Maybe it´s even Interesting why Peoples don´t use it?

I am glad to hear some feedback!

Regards Thomas

[chrisdutz]

Hi Thomas,

That's great progress!

If you could create a pull request from your fork, that simplifies reviewing what you did quite a lot.

I think the main problem is that for setting up the routes and using the psk you would need two types of Auth to pass to the connect method. The way I initially set it up is only using one (which still makes sense)

I know using the username and password for setting up the routes actually is just a hack, because I didn't want people to put the username and password in clear text in any connection strings.

However, a more correct way, would be to add properties to the connection string and use them for the route setup and use the psk stuff in the connection method for real security.

After all... The route setup should be an edge case. Using it with every connection, especially in combination with psk makes little sense: you want to establish a secure connection and the first thing you do, is send username and password in clear text over the wire, which anyone could use to log in and change the plc.

Thinking about it.... I would even say that it's fine to use the one or the other.

[chrisdutz]

I'm not sure, but I could imagine that it should be possible to implement some sort of man-in-the-middle thing, where you start a process and configure it to relay all information to the ads device. If you then connect to that instead of the plc, it should initialize a secure connection on both sides, but you have access to the unencrypted data on your intermediate, which you could log?

And we're always interested in feedback on things we could do better. That feedback would be very welcome.