session_auth: add derive_key_id (8-byte SHA-256 fingerprint)

Second slice of the HarpoS7 port (refs #717). Adds the small SHA-256
fingerprinting function that computes the symmetric/public key id
fields embedded in the SecurityKeyEncryptedKey blob.

The function is just `SHA-256(key[:24] + b"DERIVE")[:8]` — well-defined
in HarpoS7's `KeyExtensions.DeriveKeyId`. We verify byte-correctness in
two ways:

  1. The three test vectors HarpoS7 ships in `KeyExtensionsTests.cs`
     (a 64-byte PlcSim key plus two repeating-byte cases).
  2. A self-consistency check: every bundled public key, when run
     through `derive_key_id`, must produce the LE byte-reversal of
     the BE-display hex it's keyed on. This catches both algorithm
     bugs and key-byte transcription errors in #b44792d.

@xBiggs's PLC fingerprint `01:BD426B091F08731A` round-trips correctly,
so once the next slices land we can compute exactly the
publickeychecksum / symmetrickeychecksum the PLC expects to see.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: gijzelaerr

s7/session_auth/__init__.py

@@ -30,12 +30,15 @@
     get_public_key,
     parse_fingerprint,
 )
+from .utils import KEY_ID_LENGTH, derive_key_id
 
 __all__ = [
     "KeyFamily",
+    "KEY_ID_LENGTH",
     "PUBLIC_KEY_LENGTH_REAL_PLC",
     "PUBLIC_KEY_LENGTH_PLCSIM",
     "UnknownPublicKeyError",
+    "derive_key_id",
     "get_public_key",
     "parse_fingerprint",
 ]

s7/session_auth/utils.py

@@ -0,0 +1,42 @@
+"""Shared low-level helpers used across the session-auth subpackage.
+
+Ported from HarpoS7 (MIT) — specifically ``HarpoS7.Utilities.Extensions.KeyExtensions``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+# The fingerprint Siemens uses to identify a public or symmetric key.
+# Length matches the publickeychecksum / symmetrickeychecksum fields in
+# the SecurityKeyEncryptedKey blob (see Wireshark s7comm-plus dissector).
+KEY_ID_LENGTH = 8
+
+_KEY_PART_LENGTH = 24
+_DERIVE_KEY_ID_MAGIC = b"DERIVE"
+
+
+def derive_key_id(key: bytes) -> bytes:
+    """Compute the 8-byte key fingerprint used in the encrypted key blob.
+
+    HarpoS7 calls this ``DeriveKeyId``. It is SHA-256 over the first 24
+    bytes of the key concatenated with the literal ASCII string
+    ``"DERIVE"``, truncated to the first 8 bytes of the digest.
+
+    Args:
+        key: At least 24 bytes of key material — a public key or a
+            session symmetric key. Only the leading 24 bytes are used;
+            longer keys are silently truncated, matching upstream.
+
+    Returns:
+        8 bytes. Read as a little-endian uint64, this equals the value
+        the PLC advertises in its ``ObjectVariableTypeName`` attribute
+        (id 233) for that key.
+
+    Raises:
+        ValueError: If the key is shorter than 24 bytes.
+    """
+    if len(key) < _KEY_PART_LENGTH:
+        raise ValueError(f"key must be at least {_KEY_PART_LENGTH} bytes, got {len(key)}")
+    digest = hashlib.sha256(key[:_KEY_PART_LENGTH] + _DERIVE_KEY_ID_MAGIC).digest()
+    return digest[:KEY_ID_LENGTH]

tests/test_session_auth.py

@@ -59,16 +59,12 @@ def test_xbiggs_s7_1200(self) -> None:
         # The fingerprint @xBiggs's PLC advertises in #710. Verify the
         # bytes match HarpoS7's BD426B091F08731A.bin verbatim.
         key = get_public_key("01:BD426B091F08731A")
-        assert key == bytes.fromhex(
-            "e0e1f04a5ca3f90148178689bd0c930ab9db867b4f0ab109623959aa32316b7880ed1b4f9a9b189f"
-        )
+        assert key == bytes.fromhex("e0e1f04a5ca3f90148178689bd0c930ab9db867b4f0ab109623959aa32316b7880ed1b4f9a9b189f")
         assert len(key) == PUBLIC_KEY_LENGTH_REAL_PLC
 
     def test_known_s7_1500_key(self) -> None:
         key = get_public_key("00:181B7B0847D11694")
-        assert key == bytes.fromhex(
-            "8456a26996122216c921c571ff11e0befafdb1d70b5d4bc8390f5b0cc273ec142a03f2a04e6f1593"
-        )
+        assert key == bytes.fromhex("8456a26996122216c921c571ff11e0befafdb1d70b5d4bc8390f5b0cc273ec142a03f2a04e6f1593")
 
     def test_known_plcsim_key(self) -> None:
         key = get_public_key("03:09013727CCBFBF3C")

tests/test_session_auth_utils.py

@@ -0,0 +1,81 @@
+"""Tests for the session-auth low-level helpers.
+
+The ``derive_key_id`` test vectors are reproduced verbatim from
+HarpoS7's ``HarpoS7.Utilities.Tests/Extensions/KeyExtensionsTests.cs``,
+which in turn was generated from the proprietary algorithm in
+Siemens' ``OMSp_core_managed.dll``. Matching them gives us strong
+ground-truth coverage that our port is byte-correct.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from s7.session_auth import KEY_ID_LENGTH, derive_key_id, get_public_key, parse_fingerprint
+from s7.session_auth.keys import _PUBLIC_KEYS
+
+
+class TestDeriveKeyId:
+    def test_harpos7_vector_64_byte_key(self) -> None:
+        # First TestCase from HarpoS7 KeyExtensionsTests — a 64-byte
+        # PlcSim key (5A9B6B015F48D284 in family 3).
+        key = bytes.fromhex(
+            "eca6d799ddf03eaadd16b5d7245331e426c9e6ba8997877a"
+            "7394f3286532a6b053e4229818085223432483fba4d5c43b"
+            "d6c354c10febc903908ed271697f39e9"
+        )
+        assert derive_key_id(key) == bytes.fromhex("84d2485f016b9b5a")
+
+    def test_harpos7_vector_repeating_11(self) -> None:
+        # Second TestCase from HarpoS7 — 24 bytes of 0x11.
+        key = b"\x11" * 24
+        assert derive_key_id(key) == bytes.fromhex("06ddcee4adaec77a")
+
+    def test_harpos7_vector_repeating_44(self) -> None:
+        # Third TestCase from HarpoS7 — 24 bytes of 0x44.
+        key = b"\x44" * 24
+        assert derive_key_id(key) == bytes.fromhex("06d0ef4b10626822")
+
+    def test_returns_eight_bytes(self) -> None:
+        assert len(derive_key_id(b"\x00" * 32)) == KEY_ID_LENGTH
+
+    def test_only_first_24_bytes_used(self) -> None:
+        # Bytes past offset 24 must not affect the output.
+        base = b"A" * 24
+        assert derive_key_id(base + b"X" * 100) == derive_key_id(base + b"Y" * 100)
+
+    def test_short_key_rejected(self) -> None:
+        with pytest.raises(ValueError, match="at least 24 bytes"):
+            derive_key_id(b"\x00" * 23)
+
+
+class TestKeyIdMatchesAdvertisedFingerprint:
+    """Self-verifies: every bundled public key, when run through
+    ``derive_key_id``, must produce the fingerprint it's keyed on.
+
+    The fingerprint string is the big-endian hex display of the same
+    8 bytes ``derive_key_id`` produces (in little-endian byte order).
+    """
+
+    def test_xbiggs_s7_1200_key(self) -> None:
+        # The headline case: the PLC fingerprint @xBiggs reports in
+        # #710 must round-trip through our key store + derive_key_id.
+        key = get_public_key("01:BD426B091F08731A")
+        assert derive_key_id(key) == bytes.fromhex("1A73081F096B42BD")
+
+    def test_all_bundled_keys_round_trip(self) -> None:
+        for (family, key_id), key in _PUBLIC_KEYS.items():
+            expected_id_bytes = bytes.fromhex(key_id)[::-1]  # BE display → LE bytes
+            assert derive_key_id(key) == expected_id_bytes, f"derive_key_id mismatch for {family.name}/{key_id}"
+
+    def test_full_fingerprint_string_round_trip(self) -> None:
+        # End-to-end: parse the fingerprint string, look up the key,
+        # derive its id, and confirm the id reconstructs the original
+        # post-colon hex.
+        fp = "01:BD426B091F08731A"
+        family, key_id = parse_fingerprint(fp)
+        del family  # not asserted here
+        key = get_public_key(fp)
+        derived_le = derive_key_id(key)
+        derived_be_hex = derived_le[::-1].hex().upper()
+        assert derived_be_hex == key_id