bonk-dev / harpos7

HarpoS7 is a C# library for authenticating sessions in the S7 Comm Plus protocol, supporting both legacy challenge (TIA Portal V16 and older) and TLS authentication (TIA Portal V17 and newer).

HarpoS7 is a C# library designed to authenticate sessions in the S7 Comm Plus protocol. It supports both legacy challenge authentication (found in projects made using TIA Portal V16 and older) and the more recent TLS authentication introduced in project made using TIA Portal V17 and newer.

HarpoS7 is intended for integration into other libraries and frameworks rather than as a standalone tool for end users.

Features

• Fully managed
• Supports challenge-based authentication (pre-V17 TIA portal)
• Supports TLS authentication (post-V17 TIA portal)
• Supports legitimation (password authorization) - requires testing

Tested on

• S7-PLCSIM V16 (PLC: S7-1200)
• S7-PLCSIM V18 (PLC: S7-1500)

Getting started

For a comprehensive example of how to use HarpoS7, explore the HarpoS7.PoC project included in the repository.

This project provides a hands-on demonstration of how to integrate HarpoS7 into a sample application. Follow the example code and comments to fully understand how to use the library.

Public keys

If you are not using the S7-1200 provided by PLCSIM V16, you must extract the corresponding public keys used by your selected PLC.

You can use the HarpoS7.KeyDumper.Cli utility to dump public keys from a TIA Portal installation.

TODO: Add a guide

Legacy auth sample

In order to authenticate a legacy session (challenge-based):

// The "input" buffers - you have to load/fill them yourselves
// The "output" buffers - the library fills them

// Input - challenge received from the PLC (20 bytes long)
var challenge = new byte[20];

// Input - public key used by the PLC (loaded from local storage, 
// can be identified by the fingerprint sent by the PLC)
var publicKey = new byte[64];

// Output - "Encrypted key" which you send back to the PLC (216 bytes long)
var keyBlob = new byte[Constants.FinalBlobDataLength];

// Output - Session key used later on to calculate packet integrity hashes (24 bytes long)
var sessionKey = new byte[Constants.SessionKeyLength];

LegacyAuthenticationScheme.Authenticate(
    keyBlob.AsSpan(),
    sessionKey.AsSpan(),
    challenge.AsSpan(),
    publicKey.AsSpan());

In order to calculate a packet digest (these are used to prevent tampering):

// Input - your packet data (without the S7-Header and S7-Trailer)
var data = new byte[dataLength];

// Input - session key (output from LegacyAuthenticationScheme.Authenticate)
var sessionKey = new byte[Constants.SessionKeyLength];

// Output - the packet data digest, usually placed in the S7-header
var digestBuffer = new byte[HarpoPacketDigest.DigestLength];

HarpoPacketDigest.CalculateDigest(digestBuffer.AsSpan(), data, sessionKey);

TLS auth

It is important to note that although TLS authentication is present in HarpoS7, it should be treated as a proof of concept rather than a ready-to-use solution.

The reason is that the implementation is simply the built-in SslStream wrapped around a primitive CotpStream.

Legitimation

It is possible to authorize with a password against a password-protected PLC. Keep in mind that this feature had even less testing than the authentication part.

In order to authorize with a password you need to firstly obtain a valid session (using TLS or legacy auth scheme). Then you need to get a legitimation challenge using a GetVarSubStreamed request (use Wireshark to know how). Finally you can pass everything down to the SolveLegitimateChallenge function.

Code:

using HarpoS7.Auth;

var blobData = new byte[LegitimateScheme.OutputBlobDataLength];
LegitimateScheme.SolveLegitimateChallenge(
    blobData, // OUT - send this with SetVarSubStreamed
    challenge, // IN - get this with GetVarSubStreamed
    publicKey, // IN - get this from a local storage by matching the fingerprint sent by the PLC
    sessionKey, // IN - generated by LegacyAuthenticationScheme.Authenticate (TODO: check TLS)
    "password"); // IN - password required by the PLC

Credits

• Thomas_v2, Wireshark dissector plugin - a Wireshark plugin used for dissecting S7-Comm Plus packets.
• Cheng Lei, Li Donghong, Ma Liang, The spear to break the security wall of S7CommPlus - a document describing the S7-Comm Plus protocol
• Ghidra Software Reverse Engineering Framework - "Ghidra is a software reverse engineering (SRE) framework created and maintained by the National Security Agency Research Directorate."

harpos7's Issues

Using HarpoS7 with 6ES7511-1AK02-0AB0

Found your project and love it!
I wanted to ask if you plan on doing the encryption for physical SPS.

I'm currently trying to run HarpoS7 with a 6ES7511-1AK02-0AB0 myself and keep getting stuck at the SetMultivarsRequest.
So far i figured almost all offsets out which differ.
I'm using the publickey "S1500" and using TIA V16 for my project.
The bloblength on my side is 180 and the publickey is 40 bytes long.

I added a Zip with two wiresharkdump:

• TIAV16ConnectionDump
• MyHarpoDump
  Wiresharkdump.zip

Do you maybe have an idea what else would i would have to change that it would work?
I could also share my project if you're interested.

Combine Informations

Hi,

I'm working also on a driver, which is only supporting TLS (using OpenSSL). But I've done most of the high level stuff (low level is in rough shape). Maybe we can combine it? I would be willing to change the license from LPGL to a more freely one.