s7commplus 0.2.0__tar.gz → 0.3.0__tar.gz

{s7commplus-0.2.0/s7commplus.egg-info → s7commplus-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s7commplus
-Version: 0.2.0
+Version: 0.3.0
 Summary: Pure Python S7CommPlus client and server emulator for Siemens S7-1200/1500 PLCs
 Author-email: Gijs Molenaar <gijsmolenaar@gmail.com>
 License-Expression: MIT
@@ -28,7 +28,7 @@ Requires-Dist: cryptography>=41
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
-Requires-Dist: pytest-bdd<9,>=8.1; extra == "test"
+Requires-Dist: pytest-bdd<10,>=9; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
 Requires-Dist: hypothesis; extra == "test"
 Requires-Dist: mypy; extra == "test"
@@ -45,8 +45,8 @@ Dynamic: license-file
 Pure-Python S7CommPlus communication for Siemens S7-1200 and S7-1500 PLCs.
 It supports S7CommPlus V1, V2 (TLS), and V3; synchronous and asyncio clients;
 and a server emulator for testing. Both clients support legacy V1 SessionKey
-authentication, validated on a real S7-1200 (sync and async clients) and an
-S7-1500 (sync client); PLCSIM support is so far emulator-tested.
+authentication, validated on a real S7-1200 (sync and async clients), an
+S7-1500 (sync client), and S7-PLCSIM Advanced (sync and async clients).
 
 ## Installation
 
@@ -93,6 +93,15 @@ device_family("6ES7 512-1DK01-0AB0")  # 's7-1500-sp'
 variants, software controllers and PLCSIM; classic S7-300/400 is out of
 scope). `python tools/check_devices_table.py` validates its shape.
 
+Installing the package also installs a `s7commplus` command-line tool:
+
+```console
+s7commplus browse --host 192.168.1.10
+s7commplus read --host 192.168.1.10 DB1.Motor.Speed
+```
+
+See the command-line interface guide in the documentation.
+
 ## Development
 
 Cloning the repository is only necessary for developing or testing

{s7commplus-0.2.0 → s7commplus-0.3.0}/README.md

@@ -3,8 +3,8 @@
 Pure-Python S7CommPlus communication for Siemens S7-1200 and S7-1500 PLCs.
 It supports S7CommPlus V1, V2 (TLS), and V3; synchronous and asyncio clients;
 and a server emulator for testing. Both clients support legacy V1 SessionKey
-authentication, validated on a real S7-1200 (sync and async clients) and an
-S7-1500 (sync client); PLCSIM support is so far emulator-tested.
+authentication, validated on a real S7-1200 (sync and async clients), an
+S7-1500 (sync client), and S7-PLCSIM Advanced (sync and async clients).
 
 ## Installation
 
@@ -51,6 +51,15 @@ device_family("6ES7 512-1DK01-0AB0")  # 's7-1500-sp'
 variants, software controllers and PLCSIM; classic S7-300/400 is out of
 scope). `python tools/check_devices_table.py` validates its shape.
 
+Installing the package also installs a `s7commplus` command-line tool:
+
+```console
+s7commplus browse --host 192.168.1.10
+s7commplus read --host 192.168.1.10 DB1.Motor.Speed
+```
+
+See the command-line interface guide in the documentation.
+
 ## Development
 
 Cloning the repository is only necessary for developing or testing

{s7commplus-0.2.0 → s7commplus-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s7commplus"
-version = "0.2.0"
+version = "0.3.0"
 description = "Pure Python S7CommPlus client and server emulator for Siemens S7-1200/1500 PLCs"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,8 +27,11 @@ classifiers = [
 ]
 dependencies = ["cryptography>=41"]
 
+[project.scripts]
+s7commplus = "s7commplus.cli:main"
+
 [project.optional-dependencies]
-test = ["pytest", "pytest-asyncio", "pytest-bdd>=8.1,<9", "pytest-cov", "hypothesis", "mypy", "ruff"]
+test = ["pytest", "pytest-asyncio", "pytest-bdd>=9,<10", "pytest-cov", "hypothesis", "mypy", "ruff"]
 docs = ["sphinx>=7.2", "furo>=2024.8.6"]
 analysis = ["z3-solver>=4.13,<5"]
 
@@ -70,6 +73,13 @@ markers = [
     "write: real-PLC scenario that changes and restores scratch data",
     "plc_write: existing real-PLC test that modifies scratch data",
     "administrative: disruptive real-PLC scenario requiring separate opt-in",
+    "symbolic: real-PLC scenario that browses or addresses tags by name",
+    "subscription: real-PLC scenario using data change subscriptions",
+    "alarm: real-PLC scenario using the alarm snapshot or alarm subscriptions",
+    "cpu_state: real-PLC scenario reading the CPU operating state",
+    "tls: real-PLC scenario that needs --plc-use-tls",
+    "password: real-PLC scenario that needs the S7COMMPLUS_TEST_PASSWORD environment variable",
+    "pending: real-PLC scenario for an API from an open pull request; skipped until it is merged",
 ]
 
 [tool.mypy]

{s7commplus-0.2.0 → s7commplus-0.3.0}/s7commplus/__init__.py

@@ -16,7 +16,7 @@ Usage::
 from .async_client import AsyncSubscriptionQueue
 from .async_client import S7CommPlusAsyncClient as AsyncClient
 from .alarm import Alarm, AlarmNotification, AlarmText, LanguageId
-from .blob_decompressor import decompress_blob, find_and_decompress
+from .blob_decompressor import PresetStream, decompress_blob, find_and_decompress, iter_preset_headers, iter_preset_streams
 from .catalog import ArrayDimension, SymbolCatalog, SymbolicTag, TagResult
 from .client import DBWriteItem, SymbolicReadItem
 from .client import S7CommPlusClient as Client
@@ -36,6 +36,7 @@ from .tag_browser import (
     datablocks_from_explore,
     tags_from_explore,
 )
+from .zlib_dicts import PresetIdentity
 
 __all__ = [
     "Alarm",
@@ -52,6 +53,8 @@ __all__ = [
     "ExploreDataBlock",
     "LanguageId",
     "Member",
+    "PresetIdentity",
+    "PresetStream",
     "S7CommPlusConnection",
     "Server",
     "SubscriptionItem",
@@ -71,5 +74,7 @@ __all__ = [
     "device_family",
     "device_name",
     "find_and_decompress",
+    "iter_preset_headers",
+    "iter_preset_streams",
     "tags_from_explore",
 ]

{s7commplus-0.2.0 → s7commplus-0.3.0}/s7commplus/_fragment_hmac.py

@@ -1,9 +1,18 @@
 """Verify legacy S7-1500 V3 fragments without discarding integrity checks.
 
-Older PLCs finalize, then reuse, both SHA-256 states of HMAC for each
-fragment. Finalization mutates the chaining state but does not increase the
-message byte count. hashlib deliberately cannot resume a finalized digest,
-so the small SHA-256 continuation below handles this wire compatibility case.
+A multi-fragment V3 response chains its fragments with HMAC-SHA256, but the
+PLCs do not agree on the continuation dialect. Real S7-1200/1500 firmware
+finalize, then reuse, both SHA-256 states of HMAC for each fragment
+(*state-resume*); finalization mutates the chaining state but does not
+increase the message byte count, and hashlib deliberately cannot resume a
+finalized digest, so the small SHA-256 continuation below handles that wire
+compatibility case. PLCSIM Advanced clears the HMAC key each time instead and
+chains *feed-forward*: each later fragment's digest is a fresh HMAC over the
+previous fragment's digest followed by this fragment's data,
+``HMAC(key, digest_{n-1} || fragment_n)``. A response may also carry plain,
+independent per-fragment HMACs. The dialect is fixed for the whole response
+and is detected from the second fragment; a mismatch afterwards is rejected.
+
 Each verifier is scoped to exactly one reassembled response.
 
 This module is private, and is used only by the opt-in legacy S7-1500
@@ -139,10 +148,11 @@ def _continue_sha256(digest: bytes, data: bytes, total: int) -> bytes:
 class FragmentHMACVerifier:
     """Authenticate fragments belonging to one V3 response.
 
-    The first fragment must have a standard HMAC. The second chooses between
-    independent fragment HMACs and the legacy finalized-state continuation.
-    The chosen mode cannot change within a response. Return application data
-    only after comparing the full digest in constant time.
+    The first fragment must always carry a standard HMAC. The second picks the
+    continuation dialect among independent fragments, the state-resume
+    continuation, and the feed-forward chain, and the choice is then fixed for
+    the rest of the response. Return application data only after comparing the
+    full digest in constant time.
 
     Construct a fresh verifier per response; never share it between sessions.
     """
@@ -155,15 +165,18 @@ class FragmentHMACVerifier:
         self._outer: bytes | None = None
         self._inner_count = 64
         self._outer_count = 64
-        self._mode: Literal["independent", "legacy"] | None = None
+        # The previous fragment's received digest, for the feed-forward dialect.
+        self._last = b""
+        self._mode: Literal["independent", "legacy", "feed-forward"] | None = None
 
     def verify(self, protected: bytes) -> bytes:
         if not protected or protected[0] != 32 or len(protected) < 33:
             raise S7IntegrityError("Invalid V3 HMAC prefix")
         received = protected[1:33]
         data = protected[33:]
-        independent = hmac.new(self._key, data, hashlib.sha256).digest()
+
         if self._inner is None:
+            independent = hmac.new(self._key, data, hashlib.sha256).digest()
             if not hmac.compare_digest(received, independent):
                 raise S7IntegrityError("Invalid V3 HMAC")
             ipad = bytes(value ^ 0x36 for value in self._key.ljust(64, b"\0"))
@@ -171,22 +184,49 @@ class FragmentHMACVerifier:
             self._outer = independent
             self._inner_count += len(data)
             self._outer_count += 32
+            self._last = received
             return data
 
-        if self._mode != "legacy" and hmac.compare_digest(received, independent):
-            self._mode = "independent"
-            return data
         if self._mode == "independent":
-            raise S7IntegrityError("Invalid V3 HMAC")
+            independent = hmac.new(self._key, data, hashlib.sha256).digest()
+            if not hmac.compare_digest(received, independent):
+                raise S7IntegrityError("Invalid V3 continuation HMAC")
+            self._last = received
+            return data
+
+        if self._mode == "feed-forward":
+            expected = hmac.new(self._key, self._last + data, hashlib.sha256).digest()
+            if not hmac.compare_digest(received, expected):
+                raise S7IntegrityError("Invalid V3 continuation HMAC")
+            self._last = received
+            return data
 
         assert self._outer is not None
         inner_count = self._inner_count + len(data)
         outer_count = self._outer_count + 32
         inner = _continue_sha256(self._inner, data, inner_count)
         outer = _continue_sha256(self._outer, inner, outer_count)
-        if not hmac.compare_digest(received, outer):
+
+        if self._mode == "legacy":
+            if not hmac.compare_digest(received, outer):
+                raise S7IntegrityError("Invalid V3 continuation HMAC")
+            self._inner, self._outer = inner, outer
+            self._inner_count, self._outer_count = inner_count, outer_count
+            self._last = received
+            return data
+
+        # Second fragment: detect the dialect and fix it for the rest of the response.
+        independent = hmac.new(self._key, data, hashlib.sha256).digest()
+        feed_forward = hmac.new(self._key, self._last + data, hashlib.sha256).digest()
+        if hmac.compare_digest(received, independent):
+            self._mode = "independent"
+        elif hmac.compare_digest(received, outer):
+            self._mode = "legacy"
+            self._inner, self._outer = inner, outer
+            self._inner_count, self._outer_count = inner_count, outer_count
+        elif hmac.compare_digest(received, feed_forward):
+            self._mode = "feed-forward"
+        else:
             raise S7IntegrityError("Invalid V3 continuation HMAC")
-        self._mode = "legacy"
-        self._inner, self._outer = inner, outer
-        self._inner_count, self._outer_count = inner_count, outer_count
+        self._last = received
         return data

{s7commplus-0.2.0 → s7commplus-0.3.0}/s7commplus/alarm.py

@@ -9,7 +9,7 @@ from dataclasses import dataclass, field
 from enum import IntEnum
 from typing import Any
 
-from .codec import encode_object_qualifier
+from .codec import encode_object_qualifier, parse_or_raise_for_return_value
 from .protocol import DataType, ElementID, Ids, Opcode
 from .vlq import decode_int32_vlq, decode_int64_vlq, decode_uint32_vlq, decode_uint64_vlq, encode_uint32_vlq
 
@@ -488,10 +488,12 @@ def _alarm_from_object(obj: _Object, language_ids: set[LanguageId | int] | None)
 
 
 def parse_alarm_explore_response(response: bytes, language_ids: Sequence[LanguageId | int] | None = None) -> list[Alarm]:
-    """Parse the payload returned by an alarm-subsystem EXPLORE request."""
-    return_value, offset = _read_vlq64(response, 0)
-    if return_value != 0:
-        raise RuntimeError(f"Alarm browse failed: PLC returned {return_value:#x}")
+    """Parse the payload returned by an alarm-subsystem EXPLORE request.
+
+    Raises:
+        S7ReturnValueError: If the ReturnValue is non-zero.
+    """
+    offset = parse_or_raise_for_return_value(response, "Alarm browse")
     if offset + 4 > len(response):
         raise ValueError("Alarm browse response is truncated")
     offset += 4  # ExploreId