[Feat]: 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());
             }
         });