Add IEncryptionProvider interface and TLS/Legacy encryption support

- Create IEncryptionProvider interface abstracting the security layer
- Create TlsEncryptionProvider wrapping existing OpenSSL/TLS behavior (default)
- Create LegacyEncryptionProvider using HarpoS7 for older firmware
- Add HarpoS7 as git submodule for legacy encryption support
- Add new Connect() overload accepting IEncryptionProvider parameter
- Update S7CommPlusConnection to use provider for InitSSL, channel activation, security overhead, and legitimation secrets
- Backward compatible: existing Connect(address, password, ...) uses TLS by default

Co-authored-by: jogibear9988 <364896+jogibear9988@users.noreply.github.com>

Author: Copilot

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "libs/HarpoS7"]
+	path = libs/HarpoS7
+	url = https://github.com/bonk-dev/HarpoS7.git

libs/HarpoS7

@@ -0,0 +1,65 @@
+#region License
+/******************************************************************************
+ * S7CommPlusDriver
+ * 
+ * Copyright (C) 2023 Thomas Wiens, th.wiens@gmx.de
+ *
+ * This file is part of S7CommPlusDriver.
+ *
+ * S7CommPlusDriver is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ /****************************************************************************/
+#endregion
+
+namespace S7CommPlusDriver.Encryption
+{
+    /// <summary>
+    /// Abstraction for the security/encryption layer used during S7CommPlus communication.
+    /// Two implementations exist:
+    /// - TlsEncryptionProvider: For newer PLC firmware using TLS 1.3 (OpenSSL)
+    /// - LegacyEncryptionProvider: For older PLC firmware using Siemens proprietary encryption (HarpoS7)
+    /// </summary>
+    public interface IEncryptionProvider
+    {
+        /// <summary>
+        /// Whether the InitSSL request/response protocol step is needed before activation.
+        /// TLS requires the InitSSL handshake; legacy encryption does not.
+        /// </summary>
+        bool RequiresInitSsl { get; }
+
+        /// <summary>
+        /// Activate the security channel on the given S7Client.
+        /// For TLS: Initializes OpenSSL and performs the TLS 1.3 handshake.
+        /// For Legacy: No-op at this stage (authentication happens later during CreateObject processing).
+        /// </summary>
+        /// <param name="client">The S7Client to activate encryption on</param>
+        /// <returns>0 on success, error code on failure</returns>
+        int ActivateChannel(S7Client client);
+
+        /// <summary>
+        /// Deactivate the security channel and release resources.
+        /// For TLS: Deactivates TLS on the S7Client.
+        /// For Legacy: Clears session key material.
+        /// </summary>
+        /// <param name="client">The S7Client to deactivate encryption on</param>
+        void DeactivateChannel(S7Client client);
+
+        /// <summary>
+        /// Get the secret used for password legitimation.
+        /// For TLS: Returns the OMS exporter secret from SSL_export_keying_material.
+        /// For Legacy: Returns null (legacy legitimation uses a different mechanism).
+        /// </summary>
+        /// <param name="client">The S7Client to get the secret from</param>
+        /// <returns>The secret bytes, or null if not applicable</returns>
+        byte[] GetSecretForLegitimation(S7Client client);
+
+        /// <summary>
+        /// Additional overhead per PDU from the security layer, used for fragmentation calculation.
+        /// For TLS: 22 bytes (5 byte TLS header + 17 byte GCM authentication tag).
+        /// For Legacy: 0 bytes (no TLS encryption overhead).
+        /// </summary>
+        int SecurityOverheadPerPdu { get; }
+    }
+}

src/S7CommPlusDriver/Encryption/IEncryptionProvider.cs

@@ -0,0 +1,235 @@
+#region License
+/******************************************************************************
+ * S7CommPlusDriver
+ * 
+ * Copyright (C) 2023 Thomas Wiens, th.wiens@gmx.de
+ *
+ * This file is part of S7CommPlusDriver.
+ *
+ * S7CommPlusDriver is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ /****************************************************************************/
+#endregion
+
+#if !NET6_0
+
+using System;
+using System.Text;
+using HarpoS7;
+using HarpoS7.Auth;
+using HarpoS7.Keys;
+using HarpoS7.PublicKeys.Impl;
+using HarpoS7.Utilities.Auth;
+using HarpoS7.Utilities.Extensions;
+using HarpoS7.Extensions;
+
+namespace S7CommPlusDriver.Encryption
+{
+    /// <summary>
+    /// Legacy encryption provider for older PLC firmware that uses Siemens proprietary
+    /// challenge-based authentication (pre-TLS, implemented by HarpoS7).
+    /// 
+    /// With legacy encryption:
+    /// - No TLS/SSL is used for data encryption
+    /// - Authentication is done via challenge-response using HarpoS7
+    /// - Each packet includes an HMAC-SHA256 integrity digest
+    /// - The session key is derived from the authentication handshake
+    /// </summary>
+    public class LegacyEncryptionProvider : IEncryptionProvider
+    {
+        private byte[] m_sessionKey;
+        private byte[] m_publicKey;
+        private EPublicKeyFamily m_publicKeyFamily;
+        private bool m_authenticated;
+
+        /// <summary>
+        /// Legacy encryption does not use the InitSSL protocol step.
+        /// </summary>
+        public bool RequiresInitSsl => false;
+
+        /// <summary>
+        /// No TLS overhead with legacy encryption. Data is sent unencrypted with integrity digests.
+        /// </summary>
+        public int SecurityOverheadPerPdu => 0;
+
+        /// <summary>
+        /// The session key derived from the HarpoS7 authentication handshake.
+        /// Available after <see cref="ProcessChallengeResponse"/> completes successfully.
+        /// </summary>
+        public byte[] SessionKey => m_sessionKey;
+
+        /// <summary>
+        /// Whether legacy authentication has been completed successfully.
+        /// </summary>
+        public bool IsAuthenticated => m_authenticated;
+
+        /// <summary>
+        /// The public key family determined from the PLC fingerprint.
+        /// </summary>
+        public EPublicKeyFamily PublicKeyFamily => m_publicKeyFamily;
+
+        /// <summary>
+        /// No-op for legacy encryption. The security channel is established
+        /// during the CreateObject response processing via <see cref="ProcessChallengeResponse"/>.
+        /// </summary>
+        public int ActivateChannel(S7Client client)
+        {
+            // Legacy encryption doesn't activate TLS - authentication happens later
+            return 0;
+        }
+
+        /// <summary>
+        /// Clears session key material.
+        /// </summary>
+        public void DeactivateChannel(S7Client client)
+        {
+            if (m_sessionKey != null)
+            {
+                Array.Clear(m_sessionKey, 0, m_sessionKey.Length);
+                m_sessionKey = null;
+            }
+            m_authenticated = false;
+        }
+
+        /// <summary>
+        /// Returns null for legacy encryption. Legacy legitimation uses the HarpoS7
+        /// <see cref="LegitimateScheme"/> directly with the session key.
+        /// </summary>
+        public byte[] GetSecretForLegitimation(S7Client client)
+        {
+            return null;
+        }
+
+        /// <summary>
+        /// Processes the challenge received from the PLC during the CreateObject response.
+        /// Performs the HarpoS7 authentication and produces the encrypted key blob
+        /// and session key.
+        /// </summary>
+        /// <param name="challenge">The 20-byte challenge received from the PLC</param>
+        /// <param name="fingerprint">The public key fingerprint string from the PLC (e.g., "00:181B7B0847D11694")</param>
+        /// <param name="keyBlob">Output: The encrypted key blob to send back to the PLC</param>
+        /// <returns>0 on success, error code on failure</returns>
+        public int ProcessChallengeResponse(byte[] challenge, string fingerprint, out byte[] keyBlob)
+        {
+            keyBlob = null;
+
+            try
+            {
+                // Determine public key family from fingerprint
+                m_publicKeyFamily = fingerprint.ToPublicKeyFamily();
+
+                // Look up the public key from the default key store
+                var store = new DefaultPublicKeyStore();
+                m_publicKey = new byte[store.GetPublicKeyLength(fingerprint)];
+                store.ReadPublicKey(m_publicKey.AsSpan(), fingerprint);
+
+                // Determine blob length based on family
+                int blobLength = (m_publicKeyFamily == EPublicKeyFamily.PlcSim)
+                    ? CommonConstants.EncryptedBlobLengthPlcSim
+                    : CommonConstants.EncryptedBlobLengthRealPlc;
+
+                keyBlob = new byte[blobLength];
+                m_sessionKey = new byte[Constants.SessionKeyLength];
+
+                // Perform HarpoS7 authentication
+                LegacyAuthenticationScheme.Authenticate(
+                    keyBlob.AsSpan(),
+                    m_sessionKey.AsSpan(),
+                    challenge.AsSpan(),
+                    m_publicKey.AsSpan(),
+                    m_publicKeyFamily);
+
+                m_authenticated = true;
+                return 0;
+            }
+            catch (Exception ex)
+            {
+                Console.WriteLine("LegacyEncryptionProvider - ProcessChallengeResponse: Error: " + ex.Message);
+                return S7Consts.errCliAccessDenied;
+            }
+        }
+
+        /// <summary>
+        /// Derives the key ID from the public key for the SetMultiVariables authentication request.
+        /// </summary>
+        /// <returns>8-byte public key ID</returns>
+        public byte[] GetPublicKeyId()
+        {
+            if (m_publicKey == null) return null;
+            var pubKeyId = new byte[Constants.KeyIdLength];
+            m_publicKey.DeriveKeyId(pubKeyId);
+            return pubKeyId;
+        }
+
+        /// <summary>
+        /// Derives the key ID from the session key for the SetMultiVariables authentication request.
+        /// </summary>
+        /// <returns>8-byte session key ID</returns>
+        public byte[] GetSessionKeyId()
+        {
+            if (m_sessionKey == null) return null;
+            var sessionKeyId = new byte[Constants.KeyIdLength];
+            m_sessionKey.DeriveKeyId(sessionKeyId);
+            return sessionKeyId;
+        }
+
+        /// <summary>
+        /// Calculates the HMAC-SHA256 packet integrity digest for a given packet payload.
+        /// This must be included with every packet in legacy authentication mode.
+        /// </summary>
+        /// <param name="packetData">The S7CommPlus packet data (without header/trailer)</param>
+        /// <returns>32-byte HMAC-SHA256 digest</returns>
+        public byte[] CalculatePacketDigest(byte[] packetData)
+        {
+            if (m_sessionKey == null)
+                throw new InvalidOperationException("Session key not available. Authenticate first.");
+
+            var digest = new byte[HarpoS7.Integrity.HarpoPacketDigest.DigestLength];
+            HarpoS7.Integrity.HarpoPacketDigest.CalculateDigest(
+                digest.AsSpan(),
+                packetData.AsSpan(),
+                m_sessionKey.AsSpan());
+            return digest;
+        }
+
+        /// <summary>
+        /// Solves the legitimation challenge for password-protected PLCs in legacy mode.
+        /// </summary>
+        /// <param name="challenge">The legitimation challenge from the PLC (20 bytes)</param>
+        /// <param name="password">The access password</param>
+        /// <returns>The solved legitimation blob to send back to the PLC</returns>
+        public byte[] SolveLegitimationChallenge(byte[] challenge, string password)
+        {
+            if (m_sessionKey == null || m_publicKey == null)
+                throw new InvalidOperationException("Session not authenticated. Call ProcessChallengeResponse first.");
+
+            if (m_publicKeyFamily == EPublicKeyFamily.PlcSim)
+            {
+                var blobData = new byte[CommonConstants.EncryptedLegitimationBlobLengthPlcSim];
+                LegitimateScheme.SolveLegitimateChallengePlcSim(
+                    blobData.AsSpan(),
+                    challenge.AsSpan(),
+                    m_publicKey.AsSpan(),
+                    m_sessionKey.AsSpan(),
+                    password);
+                return blobData;
+            }
+            else
+            {
+                var blobData = new byte[CommonConstants.EncryptedLegitimationBlobLengthRealPlc];
+                LegitimateScheme.SolveLegitimateChallengeRealPlc(
+                    blobData.AsSpan(),
+                    challenge.AsSpan(),
+                    m_publicKey.AsSpan(),
+                    m_publicKeyFamily,
+                    m_sessionKey.AsSpan(),
+                    password);
+                return blobData;
+            }
+        }
+    }
+}
+
+#endif

src/S7CommPlusDriver/Encryption/LegacyEncryptionProvider.cs

@@ -0,0 +1,59 @@
+#region License
+/******************************************************************************
+ * S7CommPlusDriver
+ * 
+ * Copyright (C) 2023 Thomas Wiens, th.wiens@gmx.de
+ *
+ * This file is part of S7CommPlusDriver.
+ *
+ * S7CommPlusDriver is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ /****************************************************************************/
+#endregion
+
+namespace S7CommPlusDriver.Encryption
+{
+    /// <summary>
+    /// TLS 1.3 encryption provider for newer PLC firmware.
+    /// This wraps the existing OpenSSL/TLS behavior and is the default provider.
+    /// </summary>
+    public class TlsEncryptionProvider : IEncryptionProvider
+    {
+        /// <summary>
+        /// TLS requires the InitSSL request/response handshake step.
+        /// </summary>
+        public bool RequiresInitSsl => true;
+
+        /// <summary>
+        /// TLS overhead per PDU: 5 byte TLS header + 17 byte GCM authentication tag.
+        /// </summary>
+        public int SecurityOverheadPerPdu => 5 + 17;
+
+        /// <summary>
+        /// Activates TLS 1.3 on the S7Client via OpenSSL.
+        /// </summary>
+        public int ActivateChannel(S7Client client)
+        {
+            return client.SslActivate();
+        }
+
+        /// <summary>
+        /// Deactivates TLS on the S7Client.
+        /// </summary>
+        public void DeactivateChannel(S7Client client)
+        {
+            client.SslDeactivate();
+        }
+
+        /// <summary>
+        /// Returns the OMS exporter secret derived from TLS key material export.
+        /// This is used for password legitimation on newer firmware.
+        /// </summary>
+        public byte[] GetSecretForLegitimation(S7Client client)
+        {
+            return client.getOMSExporterSecret();
+        }
+    }
+}

src/S7CommPlusDriver/Encryption/TlsEncryptionProvider.cs

@@ -1,4 +1,5 @@
-using S7CommPlusDriver.Legitimation;
+using S7CommPlusDriver.Encryption;
+using S7CommPlusDriver.Legitimation;
 using System;
 using System.Collections.Generic;
 using System.IO;
@@ -160,8 +161,8 @@ private int legitimateNew(string password, string username = "")
             byte[] challengeResponse;
             if (omsSecret == null || omsSecret.Length != 32)
             {
-                // Create oms exporter secret
-                omsSecret = m_client.getOMSExporterSecret();
+                // Get secret from encryption provider
+                omsSecret = m_encryptionProvider.GetSecretForLegitimation(m_client);
             }
             // Roll key
             byte[] key = LegitimationCrypto.sha256(omsSecret);