ebicsclient 1.3.1__tar.gz → 1.3.3__tar.gz

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebicsclient
-Version: 1.3.1
+Version: 1.3.3
 Summary: Pure-Python client for the EBICS 3.0 (H005) banking protocol
 Project-URL: Homepage, https://github.com/schulluk/ebicsclient
 Project-URL: Repository, https://github.com/schulluk/ebicsclient
@@ -189,6 +189,17 @@ transaction_id = client.upload(PAIN_001, pain001_bytes)
 The **certificate-based ("mit Zertifikaten")** profile is a constructor option — see
 [docs/11-certificate-profiles.md](docs/11-certificate-profiles.md).
 
+> ### ⚠️ Loading EBICS identifiers from a config file? Quote them.
+>
+> EBICS IDs **can** carry leading zeros (a real Partner ID may look like `00123456`), and
+> ISO message versions look like `"08"`. Unquoted in YAML/JSON/TOML these parse as **numbers** —
+> the wrong type *and* silently stripped of their zeros (PyYAML even reads all-octal-digit
+> values as octal). Since 1.3.1 the library rejects non-string values immediately with an
+> explanatory error, but the correct fix is always **quoting the value in your config**
+> (`partner_id: "00123456"`, `message_version: "08"`) — never wrapping the parsed number in
+> `str()`, which would keep the wrong, zero-stripped identifier and talk to the bank as the
+> wrong subscriber. The same applies to digits-only keyring passphrases.
+
 ## Documentation index
 
 | Doc | Contents |

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/README.md

@@ -71,6 +71,17 @@ transaction_id = client.upload(PAIN_001, pain001_bytes)
 The **certificate-based ("mit Zertifikaten")** profile is a constructor option — see
 [docs/11-certificate-profiles.md](docs/11-certificate-profiles.md).
 
+> ### ⚠️ Loading EBICS identifiers from a config file? Quote them.
+>
+> EBICS IDs **can** carry leading zeros (a real Partner ID may look like `00123456`), and
+> ISO message versions look like `"08"`. Unquoted in YAML/JSON/TOML these parse as **numbers** —
+> the wrong type *and* silently stripped of their zeros (PyYAML even reads all-octal-digit
+> values as octal). Since 1.3.1 the library rejects non-string values immediately with an
+> explanatory error, but the correct fix is always **quoting the value in your config**
+> (`partner_id: "00123456"`, `message_version: "08"`) — never wrapping the parsed number in
+> `str()`, which would keep the wrong, zero-stripped identifier and talk to the bank as the
+> wrong subscriber. The same applies to digits-only keyring passphrases.
+
 ## Documentation index
 
 | Doc | Contents |

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/docs/06-engineering-conventions.md

@@ -91,6 +91,14 @@ specific return code on `ReturnCodeError`).
 - **Gathering** those values from env vars / a vault / Django settings is the **consumer's** job, never the
   library's. Explicit config is auditable; silent environment reads are a surprise and a leakage footgun on a
   money-moving codebase.
+- **Validate at the public boundary, with errors that teach the fix.** Every caller-supplied value is
+  type-checked where it enters the library (dataclass `__post_init__`, first line of a public function) —
+  never allowed to drift into `lxml`/`cryptography` and die there as a cryptic C-extension error. Learned
+  from the field: EBICS identifiers **can** carry leading zeros (`"00123456"`) and versions look like `"08"`;
+  unquoted in a consumer's YAML/JSON config they arrive as *numbers* — wrong type **and** silently
+  zero-stripped. The error message must therefore say "quote the value in your configuration", because the
+  obvious caller "fix" (`str(...)`) would keep a wrong, zero-stripped identifier and address the wrong
+  subscriber. See the README's quoting warning and `tests/test_input_validation.py`.
 
 ## Security (banking client — non-negotiable)
 

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ebicsclient"
-version = "1.3.1"
+version = "1.3.3"
 description = "Pure-Python client for the EBICS 3.0 (H005) banking protocol"
 readme = "README.md"
 requires-python = ">=3.11"

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/src/ebicsclient/crypto.py

@@ -34,6 +34,16 @@ from ebicsclient.errors import CryptoError
 # EBICS order-data encryption uses a 128-bit AES transaction key.
 _TRANSACTION_KEY_BYTES = 16
 
+# Ceiling on the inflated size of a single order-data stream. Downloaded order data is
+# deflate-compressed by the bank, and a hostile or compromised endpoint could send a highly
+# compressible "decompression bomb" that inflates to many gigabytes and exhausts memory
+# (the response AuthSignature covers the transaction envelope, not the encrypted payload, so
+# TLS is the only integrity guard on this byte stream). 512 MiB is far above any real EBICS
+# download while still bounding the blast radius; raise it only with a concrete need.
+_MAX_INFLATED_BYTES = 512 * 1024 * 1024
+# Inflate in bounded steps so a single decompress() call can never allocate without limit.
+_INFLATE_CHUNK_BYTES = 1024 * 1024
+
 # XML-DSig algorithm identifiers used by EBICS.
 _DS_NAMESPACE = "http://www.w3.org/2000/09/xmldsig#"
 _INCLUSIVE_C14N = "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
@@ -149,12 +159,49 @@ def decrypt_order_data(
     try:
         decryptor = Cipher(algorithms.AES(symmetric_key), modes.CBC(_NULL_IV)).decryptor()
         compressed = decryptor.update(encrypted_order_data) + decryptor.finalize()
-        # The plaintext is a DEFLATE stream followed by block padding (not PKCS#7). Inflate
-        # it and let the decompressor stop at the end of the stream, ignoring the padding.
-        decompressor = zlib.decompressobj()
-        return decompressor.decompress(compressed) + decompressor.flush()
-    except (ValueError, zlib.error) as error:
+    except ValueError as error:
+        raise CryptoError("Could not decrypt the EBICS order data") from error
+    # The plaintext is a DEFLATE stream followed by block padding (not PKCS#7). Inflate it
+    # with a hard output ceiling: the decompressor stops at the end of the stream (ignoring
+    # the padding), and a decompression bomb is rejected rather than exhausting memory.
+    return _inflate_bounded(compressed, _MAX_INFLATED_BYTES)
+
+
+def _inflate_bounded(compressed: bytes, limit: int) -> bytes:
+    """Inflate a DEFLATE stream, refusing to produce more than ``limit`` bytes.
+
+    Args:
+        compressed: The DEFLATE-compressed bytes (trailing non-DEFLATE padding is ignored).
+        limit: The maximum number of inflated bytes to allow before failing closed.
+
+    Returns:
+        The inflated bytes.
+
+    Raises:
+        CryptoError: the stream is not valid DEFLATE data, or it inflates past ``limit``.
+    """
+    decompressor = zlib.decompressobj()
+    output = bytearray()
+    chunk = compressed
+    try:
+        while chunk and not decompressor.eof:
+            output += decompressor.decompress(chunk, _INFLATE_CHUNK_BYTES)
+            if len(output) > limit:
+                raise CryptoError(
+                    f"EBICS order data inflates past the {limit}-byte safety limit — "
+                    f"refusing a possible decompression bomb"
+                )
+            # unconsumed_tail holds input deferred because the output cap was hit; feed it back.
+            chunk = decompressor.unconsumed_tail
+        output += decompressor.flush()
+    except zlib.error as error:
         raise CryptoError("Could not decrypt the EBICS order data") from error
+    if len(output) > limit:
+        raise CryptoError(
+            f"EBICS order data inflates past the {limit}-byte safety limit — "
+            f"refusing a possible decompression bomb"
+        )
+    return bytes(output)
 
 
 def new_transaction_key() -> bytes:

ebicsclient-1.3.3/src/ebicsclient/formats/container.py

@@ -0,0 +1,67 @@
+"""Container handling shared by the message-format parsers.
+
+EBICS download order data arrives either as a single XML document or as a ZIP container
+holding several (one per message). Every format parser accepts both, so the splitting
+logic lives here once.
+"""
+
+import io
+import zipfile
+
+from ebicsclient.errors import MessageFormatError
+
+_ZIP_MAGIC = b"PK\x03\x04"
+
+# Bounds on a downloaded ZIP container. The bank's response AuthSignature covers the
+# transaction envelope, not this encrypted-then-inflated payload, so a hostile or
+# compromised endpoint could ship a "ZIP bomb" — a tiny archive that expands to gigabytes,
+# or one with an absurd number of entries — to exhaust the client's memory. These caps are
+# far above any real EBICS delivery (many daily statements per file) while bounding the
+# blast radius; raise them only with a concrete need.
+_MAX_TOTAL_UNCOMPRESSED_BYTES = 512 * 1024 * 1024
+_MAX_ENTRIES = 10_000
+
+
+def extract_documents(order_data: bytes) -> list[bytes]:
+    """Split raw order data into its individual XML documents.
+
+    Args:
+        order_data: The raw order-data bytes a download returned — a single XML document
+            or a ZIP container of them.
+
+    Returns:
+        The contained documents; for a ZIP, in entry-name order (stable and reproducible),
+        otherwise the input as a single-element list.
+
+    Raises:
+        MessageFormatError: the data looks like a ZIP but cannot be read, holds more than
+            ``_MAX_ENTRIES`` entries, or inflates past ``_MAX_TOTAL_UNCOMPRESSED_BYTES``
+            (a possible decompression bomb).
+    """
+    if not order_data.startswith(_ZIP_MAGIC):
+        return [order_data]
+    try:
+        with zipfile.ZipFile(io.BytesIO(order_data)) as archive:
+            names = sorted(archive.namelist())
+            if len(names) > _MAX_ENTRIES:
+                raise MessageFormatError(
+                    f"ZIP container holds {len(names)} entries, over the {_MAX_ENTRIES} "
+                    f"limit — refusing a possible decompression bomb"
+                )
+            return [_read_bounded(archive, name) for name in names]
+    except (zipfile.BadZipFile, OSError) as error:
+        raise MessageFormatError("Order data is not a readable ZIP container") from error
+
+
+def _read_bounded(archive: zipfile.ZipFile, name: str) -> bytes:
+    # Decompress lazily and stop one byte past the ceiling, so a member whose header lies
+    # about its size still cannot inflate without bound. The cap is applied per entry; a
+    # container of many just-under-cap members is still bounded by _MAX_ENTRIES.
+    with archive.open(name) as entry:
+        data = entry.read(_MAX_TOTAL_UNCOMPRESSED_BYTES + 1)
+    if len(data) > _MAX_TOTAL_UNCOMPRESSED_BYTES:
+        raise MessageFormatError(
+            f"ZIP entry {name!r} inflates past the {_MAX_TOTAL_UNCOMPRESSED_BYTES}-byte "
+            f"safety limit — refusing a possible decompression bomb"
+        )
+    return data

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/src/ebicsclient/models.py

@@ -13,7 +13,7 @@ from cryptography.hazmat.primitives.asymmetric import rsa
 
 
 def _require_identifier(field_name: str, value: object) -> None:
-    # EBICS identifiers frequently carry leading zeros (e.g. a Partner ID of "00705443").
+    # EBICS identifiers can carry leading zeros (e.g. a Partner ID of "00123456").
     # Loaded from an unquoted YAML/JSON/TOML config value they arrive as numbers — the wrong
     # type AND silently stripped of their zeros (PyYAML even reads all-octal-digit values as
     # octal). Failing here, with the fix in the message, beats a cryptic TypeError four

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/src/ebicsclient/protocol/h005.py

@@ -90,6 +90,10 @@ _KNOWN_RETURN_CODES = {
     "091210": "EBICS_X509_WRONG_KEY_USAGE",  # observed live
 }
 _NONCE_BYTES = 16  # 128-bit nonce, rendered as uppercase hex
+# EBICS H005 mandates RSA keys of at least 2048 bits. Reject a bank key below that floor
+# rather than trust it: a weak modulus delivered over a compromised HPB (the response is
+# unsigned by design, guarded only by TLS and out-of-band hash/pinning) must not be used.
+_MINIMUM_BANK_KEY_BITS = 2048
 _SHA256_ALGORITHM = "http://www.w3.org/2001/04/xmlenc#sha256"
 _PHASE_INITIALISATION = "Initialisation"
 _PHASE_TRANSFER = "Transfer"
@@ -957,13 +961,20 @@ def _public_key_from_info(
     # in case a bank sends the legacy representation.
     certificate = info.findtext(f".//{{{_DS}}}X509Certificate")
     if certificate is not None:
-        return _public_key_from_certificate(certificate, info_tag, usage, verifier)
-    if verifier is not None:
+        public_key = _public_key_from_certificate(certificate, info_tag, usage, verifier)
+    elif verifier is not None:
         # A verifier was required but the bank sent a bare key with no certificate to check.
         raise ProtocolError(
             f"HPB response <{info_tag}> carries no certificate to verify"
         )
-    return _public_key_from_rsa_key_value(info, info_tag)
+    else:
+        public_key = _public_key_from_rsa_key_value(info, info_tag)
+    if public_key.key_size < _MINIMUM_BANK_KEY_BITS:
+        raise ProtocolError(
+            f"HPB response <{info_tag}> carries a {public_key.key_size}-bit RSA key, below "
+            f"the EBICS minimum of {_MINIMUM_BANK_KEY_BITS} bits — refusing to trust it"
+        )
+    return public_key
 
 
 def _public_key_from_certificate(

ebicsclient-1.3.3/tests/test_container.py

@@ -0,0 +1,62 @@
+"""Tests for ebicsclient.formats.container: order-data splitting and bomb defences.
+
+Download order data arrives as a single XML document or a ZIP of them. The container
+layer both splits it and bounds decompression, because the encrypted-then-inflated payload
+is not covered by the bank's response signature — a hostile or compromised endpoint could
+ship a ZIP bomb, and the client must fail closed rather than exhaust memory.
+"""
+
+import io
+import zipfile
+
+import pytest
+
+from ebicsclient.errors import MessageFormatError
+from ebicsclient.formats import container
+
+
+def _zip(entries: dict[str, bytes]) -> bytes:
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as archive:
+        for name, data in entries.items():
+            archive.writestr(name, data)
+    return buffer.getvalue()
+
+
+def test_a_single_document_is_returned_as_is() -> None:
+    document = b"<Document>not a zip</Document>"
+    assert container.extract_documents(document) == [document]
+
+
+def test_zip_entries_are_returned_in_entry_name_order() -> None:
+    archive = _zip({"b.xml": b"<B/>", "a.xml": b"<A/>"})
+    assert container.extract_documents(archive) == [b"<A/>", b"<B/>"]
+
+
+def test_an_unreadable_zip_raises_message_format_error() -> None:
+    # Starts with the ZIP magic but is truncated garbage.
+    with pytest.raises(MessageFormatError, match="not a readable ZIP"):
+        container.extract_documents(b"PK\x03\x04broken")
+
+
+def test_a_zip_entry_over_the_limit_is_refused(monkeypatch: pytest.MonkeyPatch) -> None:
+    # A small archive whose single entry inflates past the cap must be rejected. Lower the
+    # ceiling so the test stays fast and does not allocate hundreds of megabytes.
+    monkeypatch.setattr(container, "_MAX_TOTAL_UNCOMPRESSED_BYTES", 1024)
+    archive = _zip({"bomb.xml": b"\x00" * 4096})  # highly compressible, well over 1 KiB inflated
+    with pytest.raises(MessageFormatError, match="decompression bomb"):
+        container.extract_documents(archive)
+
+
+def test_a_zip_with_too_many_entries_is_refused(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(container, "_MAX_ENTRIES", 3)
+    archive = _zip({f"{index}.xml": b"<X/>" for index in range(4)})
+    with pytest.raises(MessageFormatError, match="over the 3 limit"):
+        container.extract_documents(archive)
+
+
+def test_a_zip_entry_at_the_limit_is_allowed(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(container, "_MAX_TOTAL_UNCOMPRESSED_BYTES", 4096)
+    payload = b"A" * 4096
+    archive = _zip({"ok.xml": payload})
+    assert container.extract_documents(archive) == [payload]

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/tests/test_crypto.py

@@ -137,3 +137,24 @@ def test_decrypt_order_data_round_trips(keyring: Keyring) -> None:
 def test_decrypt_order_data_rejects_an_unrecoverable_transaction_key(keyring: Keyring) -> None:
     with pytest.raises(CryptoError):
         crypto.decrypt_order_data(keyring.encryption, b"not a valid RSA ciphertext", b"")
+
+
+def test_decrypt_order_data_refuses_a_decompression_bomb(keyring: Keyring) -> None:
+    # A tiny, highly compressible stream that inflates past the safety ceiling must be
+    # rejected rather than exhausting memory — the bank's response signature does not cover
+    # this payload, so TLS is the only integrity guard and a hostile endpoint could send it.
+    bomb = b"\x00" * (crypto._MAX_INFLATED_BYTES + 1)
+    transaction_key, encrypted = encrypt_order_data(keyring.encryption.public_key(), bomb)
+    with pytest.raises(CryptoError, match="decompression bomb"):
+        crypto.decrypt_order_data(keyring.encryption, transaction_key, encrypted)
+
+
+def test_inflate_bounded_allows_data_up_to_the_limit() -> None:
+    # Inflating to exactly the limit is fine; only exceeding it fails. This also exercises
+    # the multi-chunk path (the payload is far larger than one inflate chunk).
+    import zlib
+
+    payload = b"A" * (4 * 1024 * 1024)
+    assert crypto._inflate_bounded(zlib.compress(payload), len(payload)) == payload
+    with pytest.raises(CryptoError, match="decompression bomb"):
+        crypto._inflate_bounded(zlib.compress(payload), len(payload) - 1)

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/tests/test_h005.py

@@ -161,6 +161,18 @@ def test_parse_hpb_response_raises_on_a_non_ok_return_code(keyring: Keyring) ->
         h005.parse_hpb_response(_ERROR_RESPONSE, keyring)
 
 
+def test_parse_hpb_response_rejects_a_bank_key_below_the_minimum_size(keyring: Keyring) -> None:
+    # The HPB response is unsigned by design (guarded only by TLS and out-of-band hashes), so
+    # a weak modulus from a compromised endpoint must be refused, not trusted. Build a bank
+    # keyring with a 1024-bit key — Keyring checks the type, not the size, so this is possible.
+    weak = rsa.generate_private_key(public_exponent=65537, key_size=1024)
+    strong = keys.generate_keyring()
+    bank_keyring = Keyring(signature=strong.signature, authentication=weak, encryption=weak)
+    response = make_hpb_response(keyring, bank_keyring)
+    with pytest.raises(ProtocolError, match="1024-bit RSA key, below the EBICS minimum"):
+        h005.parse_hpb_response(response, keyring)
+
+
 def test_ini_request_embeds_a_ca_issued_certificate_from_the_provider(
     bank: Bank, user: User, keyring: Keyring
 ) -> None:

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/tests/test_input_validation.py

@@ -5,7 +5,7 @@ value from an unquoted YAML/JSON config entry) slipping deep into a C extension
 surfacing as a cryptic error — as happened live with a numeric ``user_id`` reaching
 ``x509.NameAttribute`` (``TypeError: value argument must be a str``). Every boundary must
 fail immediately, with a message that teaches the fix. EBICS identifiers with leading
-zeros (``"00705443"``) also *lose their zeros* when parsed as numbers, so the messages
+zeros (``"00123456"``) also *lose their zeros* when parsed as numbers, so the messages
 point at quoting the config value, never at wrapping it in ``str()``.
 """
 
@@ -40,9 +40,9 @@ def keyring() -> Keyring:
 
 
 def test_user_rejects_a_numeric_id_with_a_teaching_message() -> None:
-    # The exact bug report: ZKB IDs like "00705443" unquoted in config arrive as ints.
+    # The exact bug report: ZKB IDs like "00123456" unquoted in config arrive as ints.
     with pytest.raises(TypeError) as caught:
-        User(partner_id="00705443", user_id=705443)  # type: ignore[arg-type]
+        User(partner_id="00123456", user_id=123456)  # type: ignore[arg-type]
     message = str(caught.value)
     assert "user_id must be a str" in message
     assert "int" in message
@@ -173,6 +173,6 @@ def test_the_original_bug_now_fails_at_construction_not_in_cryptography() -> Non
     # Regression for the live report: with a numeric user_id the failure must happen at
     # User(...) with our message — never reach x509.NameAttribute inside cryptography.
     with pytest.raises(TypeError) as caught:
-        User(partner_id=705443, user_id=705443)  # type: ignore[arg-type]
+        User(partner_id=123456, user_id=123456)  # type: ignore[arg-type]
     assert "value argument must be a str" not in str(caught.value)
     assert "leading zeros" in str(caught.value)

{ebicsclient-1.3.1 → ebicsclient-1.3.3}/uv.lock

@@ -281,7 +281,7 @@ wheels = [
 
 [[package]]
 name = "ebicsclient"
-version = "1.3.1"
+version = "1.3.3"
 source = { editable = "." }
 dependencies = [
     { name = "cryptography" },

ebicsclient-1.3.1/src/ebicsclient/formats/container.py

@@ -1,36 +0,0 @@
-"""Container handling shared by the message-format parsers.
-
-EBICS download order data arrives either as a single XML document or as a ZIP container
-holding several (one per message). Every format parser accepts both, so the splitting
-logic lives here once.
-"""
-
-import io
-import zipfile
-
-from ebicsclient.errors import MessageFormatError
-
-_ZIP_MAGIC = b"PK\x03\x04"
-
-
-def extract_documents(order_data: bytes) -> list[bytes]:
-    """Split raw order data into its individual XML documents.
-
-    Args:
-        order_data: The raw order-data bytes a download returned — a single XML document
-            or a ZIP container of them.
-
-    Returns:
-        The contained documents; for a ZIP, in entry-name order (stable and reproducible),
-        otherwise the input as a single-element list.
-
-    Raises:
-        MessageFormatError: the data looks like a ZIP but cannot be read.
-    """
-    if not order_data.startswith(_ZIP_MAGIC):
-        return [order_data]
-    try:
-        with zipfile.ZipFile(io.BytesIO(order_data)) as archive:
-            return [archive.read(name) for name in sorted(archive.namelist())]
-    except (zipfile.BadZipFile, OSError) as error:
-        raise MessageFormatError("Order data is not a readable ZIP container") from error