ebicsclient 1.3.3__tar.gz → 1.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebicsclient
-Version: 1.3.3
+Version: 1.4.0
 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
@@ -124,8 +124,9 @@ validated live against Zürcher Kantonalbank (ZKB).
 **What it provides today:**
 
 - **Key ceremony** — INI/HIA/HPB with X.509 key transmission (self-signed *mit Schlüsseln* or
-  CA-issued *mit Zertifikaten*), the printable initialisation letter (HTML/PDF), and bank-key
-  **pinning** across sessions
+  CA-issued *mit Zertifikaten*), the printable EBICS 3.0 initialisation letters (INI + HIA,
+  HTML/PDF, carrying the certificates and their SHA-256 DER fingerprints per spec 4.4.1.2.3),
+  and bank-key **pinning** across sessions
 - **Read** — statement/report downloads with parsers into typed models: **camt.053** end-of-day
   statements, **camt.052** intraday reports, **camt.054** booking advices (incl. QRR/SCOR/LSV),
   and **pain.002** payment status reports
@@ -237,8 +238,12 @@ a real bank statement.
 - [x] Authentication signature (inclusive Canonical XML 1.0 + RSA-SHA256)
 - [x] HTTPS transport (TLS 1.2 floor, certifi fallback via the optional `tls` extra)
 - [x] INI/HIA/HPB handshake
-- [x] X.509 key transmission: **mit Schlüsseln** (self-signed) and **mit Zertifikaten** (CA certs)
-- [x] Initialisation letter (HTML, or PDF via the optional `pdf` extra)
+- [x] X.509 key transmission: **mit Schlüsseln** (self-signed, deterministic certificates) and
+      **mit Zertifikaten** (CA certs)
+- [x] Initialisation letters (INI + HIA) with certificate SHA-256 DER fingerprints per the
+      EBICS 3.0 spec (HTML, or PDF via the optional `pdf` extra)
+- [ ] Production activation on the printed letters (in progress — the pre-1.4.0 letter carried
+      the EBICS 2.x public-key hash, which banks no longer match; see the 1.4.0 notes)
 - [x] Bank-key pinning across sessions (`hpb(pinned=...)`)
 
 **Milestone 2 — Read** (validated live on ZKB)

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

@@ -6,8 +6,9 @@ validated live against Zürcher Kantonalbank (ZKB).
 **What it provides today:**
 
 - **Key ceremony** — INI/HIA/HPB with X.509 key transmission (self-signed *mit Schlüsseln* or
-  CA-issued *mit Zertifikaten*), the printable initialisation letter (HTML/PDF), and bank-key
-  **pinning** across sessions
+  CA-issued *mit Zertifikaten*), the printable EBICS 3.0 initialisation letters (INI + HIA,
+  HTML/PDF, carrying the certificates and their SHA-256 DER fingerprints per spec 4.4.1.2.3),
+  and bank-key **pinning** across sessions
 - **Read** — statement/report downloads with parsers into typed models: **camt.053** end-of-day
   statements, **camt.052** intraday reports, **camt.054** booking advices (incl. QRR/SCOR/LSV),
   and **pain.002** payment status reports
@@ -119,8 +120,12 @@ a real bank statement.
 - [x] Authentication signature (inclusive Canonical XML 1.0 + RSA-SHA256)
 - [x] HTTPS transport (TLS 1.2 floor, certifi fallback via the optional `tls` extra)
 - [x] INI/HIA/HPB handshake
-- [x] X.509 key transmission: **mit Schlüsseln** (self-signed) and **mit Zertifikaten** (CA certs)
-- [x] Initialisation letter (HTML, or PDF via the optional `pdf` extra)
+- [x] X.509 key transmission: **mit Schlüsseln** (self-signed, deterministic certificates) and
+      **mit Zertifikaten** (CA certs)
+- [x] Initialisation letters (INI + HIA) with certificate SHA-256 DER fingerprints per the
+      EBICS 3.0 spec (HTML, or PDF via the optional `pdf` extra)
+- [ ] Production activation on the printed letters (in progress — the pre-1.4.0 letter carried
+      the EBICS 2.x public-key hash, which banks no longer match; see the 1.4.0 notes)
 - [x] Bank-key pinning across sessions (`hpb(pinned=...)`)
 
 **Milestone 2 — Read** (validated live on ZKB)

{ebicsclient-1.3.3 → ebicsclient-1.4.0}/docs/05-zkb-onboarding.md

@@ -12,11 +12,17 @@ activation PIN**.
 1. **Generate** your three RSA keypairs (A006 sig, X002 auth, E002 enc) → encrypted keyring.
 2. **INI** — send your signature public key (`ebicsUnsecuredRequest`, order type `INI`).
 3. **HIA** — send your authentication + encryption public keys (order type `HIA`).
-4. **Initialisierungsbriefe** — `make_ini_letter()` renders the letter (covering all three keys) as
-   **printable HTML** by default (no dependency) or as **PDF** with the optional `pdf` extra; `AUTO`
-   picks PDF when that extra is installed, else HTML. It contains the SHA-256 hashes of *your* public
-   keys. **Sign it by hand (legally valid signature)** and mail to ZKB Kompetenzcenter Services. ZKB
-   verifies the signature against documents on file, then activates and confirms your access. See
+4. **Initialisierungsbriefe** — `make_ini_letter()` renders **both** EBICS 3.0 letters (the INI
+   letter with the A006 signature certificate; the HIA letter with the X002 and E002 certificates,
+   on its own page) as **printable HTML** by default (no dependency) or as **PDF** with the optional
+   `pdf` extra; `AUTO` picks PDF when that extra is installed, else HTML. Per the EBICS 3.0 spec
+   (section 4.4.1.2.3) each letter shows the certificate in PEM **and the SHA-256 hash of its DER
+   encoding** in uppercase hex — *not* the EBICS 2.x public-key (`exponent modulus`) hash; the bank
+   compares those fingerprints against the certificates it received over INI/HIA. The default
+   self-signed certificates are **deterministic**, so the letter always reproduces exactly the
+   certificates the requests transmitted, from the keyring alone. **Sign each page by hand (legally
+   valid signature)** and mail to ZKB Kompetenzcenter Services. ZKB verifies the signature against
+   documents on file, then activates and confirms your access. See
    [doc 07](07-handshake-testing.md) for the end-to-end test walkthrough.
 5. **HPB** — download ZKB's public keys and **verify them against the hashes printed on p.2 of the
    Bankparameterdaten letter** (in `../local/`).
@@ -48,3 +54,14 @@ Contact: **support.epayment@zkb.ch / +41 44 293 99 15** (Kompetenzcenter Service
 
 - Confirm **plain keys** ("mit Schlüsseln") are fine for download-only — assume yes, proceed.
 - Profile **T** (no distributed signature) — irrelevant since download-only.
+
+## Production watch-item: `BankPubKeyDigests` hash format
+
+The EBICS 3.0 spec (section 5.5.1.1) defines the `BankPubKeyDigests` values in requests as the
+SHA-256 over the bank **certificate's DER** — but this client sends the EBICS 2.x public-key
+(`exponent modulus`) digest, and the ZKB **test platform accepted that in every live
+transaction** (downloads and uploads). ZKB's published Bankparameterdaten hashes are also
+public-key hashes, so HPB pinning stays in the `e m` format. If ZKB **production** ever rejects
+requests with `EBICS_BANK_PUBKEY_UPDATE_REQUIRED` despite fresh HPB keys, this mismatch is the
+first suspect: the fix is to retain the bank *certificates* from the HPB response and send
+their DER SHA-256 fingerprints instead.

{ebicsclient-1.3.3 → ebicsclient-1.4.0}/docs/11-certificate-profiles.md

@@ -6,7 +6,14 @@ subscriber's certificate comes from and how the bank's certificate is trusted:
 
 - **mit Schlüsseln** (key-based) — the certificate is **self-signed** by the key it carries.
   Identity is established out of band: the signed initialisation letter, or online activation.
-  This is the default and what the ZKB validation used.
+  This is the default and what the ZKB validation used. The self-signed certificates are
+  **deterministic** (fixed validity 2020-01-01 → 9999-12-31, key-derived serial, deterministic
+  PKCS#1 v1.5 signature): regenerating one for the same key yields **byte-identical DER**. This
+  matters because the EBICS 3.0 initialisation letters print the SHA-256 hash of the DER-encoded
+  certificate (spec section 4.4.1.2.3) and the bank compares it against the certificate INI/HIA
+  transmitted — determinism lets any later session reproduce that certificate from the keyring
+  alone, without persisting certificates. (The Swiss Market Practice Guidelines section 6.1
+  explicitly allow unlimited certificate validity.)
 - **mit Zertifikaten** (certificate-based) — the certificate is **issued by a CA the bank
   trusts**, and the bank validates the chain. Common at German and French banks.
 

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

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

{ebicsclient-1.3.3 → ebicsclient-1.4.0}/src/ebicsclient/__init__.py

@@ -39,6 +39,7 @@ from ebicsclient.errors import (
 from ebicsclient.keys import (
     CertificateUsage,
     bank_key_hashes,
+    certificate_fingerprint,
     deserialize_keyring,
     generate_keyring,
     generate_self_signed_certificate,
@@ -139,6 +140,7 @@ __all__ = [
     "User",
     "__version__",
     "bank_key_hashes",
+    "certificate_fingerprint",
     "deserialize_keyring",
     "generate_keyring",
     "generate_self_signed_certificate",

{ebicsclient-1.3.3 → ebicsclient-1.4.0}/src/ebicsclient/client.py

@@ -93,18 +93,22 @@ class Client:
         output_format: OutputFormat = OutputFormat.AUTO,
         branding: str = "ebicsClient",
     ) -> Letter:
-        """Render the initialisation letter to print, sign, and send to the bank.
+        """Render the initialisation letters (INI and HIA) to print, sign, and send.
 
-        The letter carries the subscriber's public-key hashes so the bank can verify, out
-        of band, the keys it received electronically over INI and HIA.
+        The letters carry the subscriber's certificates and their SHA-256 DER
+        fingerprints (EBICS 3.0 spec, section 4.4.1.2.3) so the bank can verify, out of
+        band, the certificates it received electronically over INI and HIA. They are
+        rendered from this client's certificate provider, so the printed fingerprints
+        match the certificates :meth:`ini` and :meth:`hia` transmitted.
 
         Args:
             output_format: The output format. ``AUTO`` renders PDF when the optional
                 ``pdf`` extra is installed, otherwise HTML.
-            branding: A name shown in the letter's footer; defaults to ``"ebicsClient"``.
+            branding: A name shown in the letters' footer; defaults to ``"ebicsClient"``.
 
         Returns:
-            The rendered letter (format, media type, and content bytes).
+            The rendered letters (format, media type, and content bytes) — the INI
+            letter and the HIA letter, each on its own page.
 
         Raises:
             MissingDependencyError: PDF output was requested without the ``pdf`` extra.
@@ -113,6 +117,7 @@ class Client:
             self._bank,
             self._user,
             self._keyring,
+            certificate_provider=self._certificate_provider,
             output_format=output_format,
             branding=branding,
         )

{ebicsclient-1.3.3 → ebicsclient-1.4.0}/src/ebicsclient/keys.py

@@ -38,9 +38,19 @@ _PUBLIC_EXPONENT = 65537
 _KEYRING_FORMAT_VERSION = 1
 _KEY_FIELDS = ("signature", "authentication", "encryption")
 
-# Self-signed certificates for the key-based ("mit Schlüsseln") profile are long-lived;
-# the bank only extracts the public key from them.
-_CERTIFICATE_VALIDITY_DAYS = 365 * 10
+# Self-signed certificates for the key-based ("mit Schlüsseln") profile are DETERMINISTIC:
+# regenerating one for the same key always yields byte-identical DER. That matters because
+# EBICS 3.0 initialisation letters carry the SHA-256 hash of the DER-encoded certificate
+# (EBICS 3.0 spec, section 4.4.1.2.3), and the bank compares it against the certificate it
+# received over INI/HIA — so the letter must be able to reproduce that exact certificate
+# from the keyring alone, in any later session. Determinism comes from fixed validity
+# dates, a serial derived from the key, and RSA PKCS#1 v1.5 signing (which is itself
+# deterministic). The Swiss Market Practice Guidelines EBICS 3.0 (section 6.1) explicitly
+# allow any validity value including unlimited (9999-12-31).
+_CERTIFICATE_NOT_BEFORE = datetime.datetime(2020, 1, 1, tzinfo=datetime.UTC)
+_CERTIFICATE_NOT_AFTER = datetime.datetime(9999, 12, 31, 23, 59, 59, tzinfo=datetime.UTC)
+# RFC 5280 caps serial numbers at 20 octets; 16 digest bytes stay comfortably below.
+_CERTIFICATE_SERIAL_BYTES = 16
 
 
 def _require_passphrase(passphrase: object) -> None:
@@ -109,13 +119,20 @@ def _key_usage(usage: CertificateUsage) -> x509.KeyUsage:
 def generate_self_signed_certificate(
     private_key: rsa.RSAPrivateKey, common_name: str, usage: CertificateUsage
 ) -> x509.Certificate:
-    """Generate a self-signed X.509 certificate carrying an EBICS public key.
+    """Generate a deterministic self-signed X.509 certificate carrying an EBICS public key.
 
     EBICS 3.0 (H005) transmits public keys as X.509 certificates (``ds:X509Data``). In the
     key-based ("mit Schlüsseln") profile the certificate is self-signed by the very key it
     carries, and the bank extracts the public key from it. The bank *does* validate the
     certificate's Key Usage against its EBICS role, so it is set from ``usage``.
 
+    The certificate is **deterministic**: the same key, name, and usage always produce
+    byte-identical DER (fixed validity, key-derived serial, deterministic PKCS#1 v1.5
+    signature). The EBICS 3.0 initialisation letters carry the SHA-256 hash of this DER
+    (see :func:`certificate_fingerprint`), and the bank compares it against the certificate
+    delivered over INI/HIA — determinism lets the letter reproduce that certificate from
+    the keyring alone, without persisting certificates.
+
     Args:
         private_key: The key pair to certify; its public half is embedded and it self-signs.
         common_name: The subject/issuer common name (e.g. the subscriber's User ID).
@@ -125,20 +142,55 @@ def generate_self_signed_certificate(
         The self-signed certificate.
     """
     name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, common_name)])
-    now = datetime.datetime.now(datetime.UTC)
     return (
         x509.CertificateBuilder()
         .subject_name(name)
         .issuer_name(name)
         .public_key(private_key.public_key())
-        .serial_number(x509.random_serial_number())
-        .not_valid_before(now - datetime.timedelta(days=1))
-        .not_valid_after(now + datetime.timedelta(days=_CERTIFICATE_VALIDITY_DAYS))
+        .serial_number(_deterministic_serial(private_key.public_key(), common_name, usage))
+        .not_valid_before(_CERTIFICATE_NOT_BEFORE)
+        .not_valid_after(_CERTIFICATE_NOT_AFTER)
         .add_extension(_key_usage(usage), critical=True)
         .sign(private_key, hashes.SHA256())
     )
 
 
+def _deterministic_serial(
+    public_key: rsa.RSAPublicKey, common_name: str, usage: CertificateUsage
+) -> int:
+    # A serial derived from the certified key (plus name and role) keeps regeneration
+    # byte-identical while staying unique per certificate. RFC 5280 requires a positive
+    # serial of at most 20 octets; 16 digest bytes always satisfy both (`or 1` covers the
+    # astronomically unlikely all-zero digest).
+    digest = hashlib.sha256(
+        b"|".join(
+            (
+                _fingerprint_data(public_key.public_numbers()),
+                common_name.encode("utf-8"),
+                usage.value.encode("ascii"),
+            )
+        )
+    ).digest()
+    return int.from_bytes(digest[:_CERTIFICATE_SERIAL_BYTES], "big") or 1
+
+
+def certificate_fingerprint(certificate: x509.Certificate) -> bytes:
+    """Compute the SHA-256 fingerprint of a certificate's DER encoding.
+
+    This is the hash the EBICS 3.0 initialisation letters print (spec section 4.4.1.2.3):
+    the SHA-256 of the certificate in DER binary format, shown as uppercase hexadecimal.
+    The bank compares it against the certificate received over INI/HIA before activating
+    the subscriber.
+
+    Args:
+        certificate: The certificate to fingerprint.
+
+    Returns:
+        The 32-byte SHA-256 digest of the DER-encoded certificate.
+    """
+    return certificate.fingerprint(hashes.SHA256())
+
+
 def bank_key_hashes(bank_keys: BankKeys) -> BankKeyHashes:
     """Compute the pinning hashes for a bank's public keys.