cryptnox-id-cli 1.0.2__py3-none-any.whl

cryptnox_id_cli/transport/pcsc.py

@@ -0,0 +1,351 @@
+"""pyscard wrapper: passive reader status, Cryptnox/ACS-first selection, and a CardSession
+that handles 6Cxx/61xx chaining and writes a redacted APDU transcript."""
+
+from __future__ import annotations
+
+import contextlib
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, TextIO
+
+from cryptnox_id_cli.secrets.redaction import Redactor
+from cryptnox_id_cli.transport.apdu import APDU, Response
+from cryptnox_id_cli.transport.elevation import looks_like_no_access
+from cryptnox_id_cli.transport.errors import (
+    CardAccessDeniedError,
+    NoCardError,
+    NoReadersError,
+    ReaderNotFoundError,
+    TransportError,
+)
+
+#: Substrings that identify the project's own readers: the Cryptnox-branded units
+#: ("CryptnoxCR" contact, "Cryptnox NFC" contactless) and the ACS readers they are
+#: based on. Selection prefers these so we never auto-target another project's card.
+PREFERRED_HINTS = ("Cryptnox", "ACS", "ACR39")
+
+
+@dataclass(frozen=True)
+class ReaderInfo:
+    index: int
+    name: str
+    present: bool
+    atr: bytes
+
+    @property
+    def atr_hex(self) -> str:
+        return self.atr.hex().upper()
+
+    @property
+    def is_preferred(self) -> bool:
+        return any(h.lower() in self.name.lower() for h in PREFERRED_HINTS)
+
+
+class RawConnection(Protocol):
+    """Minimal card-connection interface (satisfied by pyscard and the test mock)."""
+
+    def transmit(self, apdu: list[int]) -> tuple[list[int], int, int]: ...
+    def get_atr(self) -> bytes: ...
+    def disconnect(self) -> None: ...
+
+
+# --------------------------------------------------------------------------- #
+# Reader enumeration (passive — no card session, no APDU)                      #
+# --------------------------------------------------------------------------- #
+def reader_states() -> list[ReaderInfo]:
+    """List readers with card-present + ATR, passively via SCardGetStatusChange.
+
+    This does NOT open a card session or transmit anything — safe for readers that
+    hold other projects' cards.
+    """
+    try:
+        from smartcard.scard import (
+            SCARD_S_SUCCESS,
+            SCARD_SCOPE_USER,
+            SCARD_STATE_PRESENT,
+            SCARD_STATE_UNAWARE,
+            SCardEstablishContext,
+            SCardGetStatusChange,
+            SCardListReaders,
+            SCardReleaseContext,
+        )
+    except ImportError as exc:  # pragma: no cover - pyscard always present at runtime
+        raise TransportError(f"pyscard unavailable: {exc}") from exc
+
+    hresult, hcontext = SCardEstablishContext(SCARD_SCOPE_USER)
+    if hresult != SCARD_S_SUCCESS:
+        raise TransportError(
+            "Cannot reach the PC/SC service. On Windows ensure 'Smart Card' (SCardSvr) "
+            "is running; on Linux start pcscd."
+        )
+    try:
+        hresult, names = SCardListReaders(hcontext, [])
+        if hresult != SCARD_S_SUCCESS or not names:
+            return []
+        states = [(name, SCARD_STATE_UNAWARE) for name in names]
+        hresult, new_states = SCardGetStatusChange(hcontext, 0, states)
+        infos: list[ReaderInfo] = []
+        for index, entry in enumerate(new_states):
+            name, event_state, atr = entry
+            present = bool(event_state & SCARD_STATE_PRESENT)
+            infos.append(ReaderInfo(index, name, present, bytes(atr)))
+        return infos
+    finally:
+        SCardReleaseContext(hcontext)
+
+
+def list_reader_names() -> list[str]:
+    try:
+        from smartcard.System import readers as _readers
+    except ImportError as exc:  # pragma: no cover
+        raise TransportError(f"pyscard unavailable: {exc}") from exc
+    try:
+        return [str(r) for r in _readers()]
+    except Exception as exc:  # pragma: no cover - defensive
+        raise TransportError(f"Cannot list readers: {exc}") from exc
+
+
+def _listing(infos: list[ReaderInfo]) -> str:
+    return ", ".join(f"[{r.index}] {r.name}" for r in infos)
+
+
+def select_reader(infos: list[ReaderInfo], preference: str | None) -> str:
+    """Resolve a reader name from a reader list + an optional ``--reader`` preference.
+
+    Pure (no PC/SC calls) so it is unit-testable. ``--reader`` accepts an index or a
+    case-insensitive name substring; an ambiguous substring is an error, never a
+    silent first-match. With no preference it prefers the single Cryptnox/ACS reader
+    that has a card, and REFUSES TO GUESS when several do (e.g. a contact + a
+    contactless reader both loaded) — the caller must disambiguate with ``--reader``.
+    """
+    if not infos:
+        raise NoReadersError("No PC/SC readers found.")
+    if preference is not None:
+        pref = preference.strip()
+        if pref.isdigit():
+            match = next((r for r in infos if r.index == int(pref)), None)
+            if match is not None:
+                return match.name
+            raise ReaderNotFoundError(f"No reader at index {pref} (found {len(infos)}).")
+        matches = [r for r in infos if pref.lower() in r.name.lower()]
+        if len(matches) == 1:
+            return matches[0].name
+        if not matches:
+            raise ReaderNotFoundError(
+                f"No reader matching {preference!r}. Available: {_listing(infos)}"
+            )
+        raise ReaderNotFoundError(f"Reader {preference!r} is ambiguous: {_listing(matches)}")
+    # No preference: prefer a Cryptnox/ACS reader that actually has a card.
+    preferred = [r for r in infos if r.is_preferred]
+    with_card = [r for r in preferred if r.present]
+    if len(with_card) == 1:
+        return with_card[0].name
+    if len(with_card) > 1:
+        raise ReaderNotFoundError(
+            "Multiple Cryptnox/ACS readers have a card; pass --reader <index|name> to "
+            "choose (e.g. PICC for contactless, ICC for contact). "
+            f"Candidates: {_listing(with_card)}"
+        )
+    if len(preferred) == 1:
+        return preferred[0].name  # present but cardless -> let the session report NoCard
+    if preferred:
+        raise ReaderNotFoundError(
+            "Multiple Cryptnox/ACS readers found (none with a card); pass --reader. "
+            f"{_listing(preferred)}"
+        )
+    if len(infos) == 1:
+        return infos[0].name
+    raise ReaderNotFoundError(
+        "Multiple readers found and no Cryptnox/ACS reader detected. "
+        f"Pass --reader <name|index>. Available: {_listing(infos)}"
+    )
+
+
+def pick_reader(preference: str | None) -> str:
+    """Resolve a reader name from ``--reader`` (index or substring), else Cryptnox/ACS-with-card."""
+    return select_reader(reader_states(), preference)
+
+
+#: Reader-name tokens that mark a contactless (PICC/NFC) interface. Vendor names are
+#: free-form, so this is evidence, not proof - `is_contactless_interface` also looks at
+#: the ATR before claiming contactless.
+_CONTACTLESS_NAME_TOKENS = frozenset({"picc", "contactless", "nfc", "cl"})
+#: Model numbers fold the marker into the token ("OMNIKEY 5422CL") - digits then "cl".
+_MODEL_CL_RE = re.compile(r"\d+cl")
+
+
+def is_contactless_interface(reader_name: str | None, atr: bytes | None) -> bool:
+    """Best-effort: is this session on a contactless (ISO 14443 / PICC) interface?
+
+    Two independent signals, either suffices:
+
+    * the reader name advertises a PICC/CL/NFC interface (e.g. ``ACS ACR1552 1S CL
+      Reader PICC 0``, ``OMNIKEY 5422CL``) - matched on whole name tokens, so ``SCL011``
+      alone does not count while its ``Contactless`` suffix does, or
+    * the ATR follows the PC/SC v2 Part 3 contactless construction ``3B 8x 80 01 …``,
+      which readers synthesise for ISO 14443 cards (a wired card answers with its own
+      ATR instead - e.g. the D600's ``3B FA 13 …``).
+
+    False means "no evidence of contactless", not "proven contact" - callers should
+    phrase contact-side advice accordingly.
+    """
+    if reader_name:
+        tokens = re.split(r"[^a-z0-9]+", reader_name.lower())
+        if any(t in _CONTACTLESS_NAME_TOKENS or _MODEL_CL_RE.fullmatch(t) for t in tokens):
+            return True
+    return (
+        atr is not None
+        and len(atr) >= 4
+        and atr[0] == 0x3B
+        and (atr[1] & 0xF0) == 0x80
+        and atr[2] == 0x80
+        and atr[3] == 0x01
+    )
+
+
+class PCSCConnection:
+    """Adapts a pyscard connection to :class:`RawConnection`, mapping exceptions."""
+
+    def __init__(self, conn: object) -> None:
+        self._conn = conn
+
+    def transmit(self, apdu: list[int]) -> tuple[list[int], int, int]:
+        from smartcard.Exceptions import CardConnectionException
+
+        try:
+            data, sw1, sw2 = self._conn.transmit(apdu)  # type: ignore[attr-defined]
+            return list(data), sw1, sw2
+        except CardConnectionException as exc:
+            if looks_like_no_access(exc):
+                raise CardAccessDeniedError(
+                    str(exc), hresult=getattr(exc, "hresult", None)
+                ) from exc
+            raise TransportError(f"APDU transmit failed: {exc}") from exc
+
+    def get_atr(self) -> bytes:
+        return bytes(self._conn.getATR())  # type: ignore[attr-defined]
+
+    def disconnect(self) -> None:
+        with contextlib.suppress(Exception):  # pragma: no cover - best effort
+            self._conn.disconnect()  # type: ignore[attr-defined]
+
+
+def connect(reader_name: str) -> PCSCConnection:
+    """Open a card connection on ``reader_name`` (tries default then T1/T0)."""
+    from smartcard.CardConnection import CardConnection
+    from smartcard.Exceptions import CardConnectionException, NoCardException
+    from smartcard.System import readers as _readers
+
+    target = next((r for r in _readers() if str(r) == reader_name), None)
+    if target is None:
+        raise ReaderNotFoundError(f"Reader not found: {reader_name}")
+    conn = target.createConnection()
+    try:
+        conn.connect()
+        return PCSCConnection(conn)
+    except NoCardException as exc:
+        raise NoCardError(f"No card present in reader {reader_name!r}.") from exc
+    except CardConnectionException as exc:
+        if looks_like_no_access(exc):
+            raise CardAccessDeniedError(str(exc), hresult=getattr(exc, "hresult", None)) from exc
+        for proto in (CardConnection.T1_protocol, CardConnection.T0_protocol):
+            try:
+                conn.connect(proto)
+                return PCSCConnection(conn)
+            except Exception:  # noqa: S112 - try next protocol
+                continue
+        raise TransportError(f"Cannot connect to card in {reader_name!r}: {exc}") from exc
+
+
+class CardSession:
+    """High-level APDU exchange with chaining and a redacted transcript."""
+
+    def __init__(
+        self,
+        conn: RawConnection,
+        *,
+        redactor: Redactor | None = None,
+        apdu_log: TextIO | None = None,
+        trace: Callable[[str], None] | None = None,
+        reader_name: str | None = None,
+    ) -> None:
+        self._conn = conn
+        self._redactor = redactor or Redactor()
+        self._log = apdu_log
+        self._trace = trace
+        #: Name of the PC/SC reader this session runs on, when known. Diagnostic only
+        #: (interface heuristics); never used to route APDUs.
+        self.reader_name = reader_name
+
+    @property
+    def redactor(self) -> Redactor:
+        return self._redactor
+
+    @property
+    def atr(self) -> bytes:
+        return self._conn.get_atr()
+
+    def _emit(self, line: str) -> None:
+        if self._log is not None:
+            self._log.write(line + "\n")
+            self._log.flush()
+        if self._trace is not None:
+            self._trace(line)
+
+    def transmit(self, apdu: APDU | bytes | bytearray, *, context: str | None = None) -> Response:
+        raw = apdu.to_bytes() if isinstance(apdu, APDU) else bytes(apdu)
+        ins = raw[1] if len(raw) > 1 else 0
+        self._emit("> " + self._redactor.redact_command(raw))
+
+        data, sw1, sw2 = self._conn.transmit(list(raw))
+
+        # 6Cxx: wrong Le — resend with the corrected Le in the trailing byte.
+        if sw1 == 0x6C and len(raw) >= 5:
+            data, sw1, sw2 = self._conn.transmit(list(raw[:-1]) + [sw2])
+
+        # 61xx: more data — pull it with GET RESPONSE.
+        acc = list(data)
+        while sw1 == 0x61:
+            more, sw1, sw2 = self._conn.transmit([0x00, 0xC0, 0x00, 0x00, sw2])
+            acc += list(more)
+
+        resp = Response(bytes(acc), sw1, sw2)
+        self._emit("< " + self._redactor.redact_response(resp.data, resp.sw1, resp.sw2, ins=ins))
+        return resp
+
+    def transmit_chained(
+        self, apdu: APDU, *, block_size: int = 200, context: str | None = None
+    ) -> Response:
+        """Send a command whose data exceeds a short APDU via ISO command chaining
+        (CLA bit 0x10 on every block but the last, which keeps the original CLA/Le)."""
+        blocks = [apdu.data[i : i + block_size] for i in range(0, len(apdu.data), block_size)] or [
+            b""
+        ]
+        resp: Response | None = None
+        for index, block in enumerate(blocks):
+            final = index == len(blocks) - 1
+            frame = APDU(
+                apdu.cla if final else (apdu.cla | 0x10),
+                apdu.ins,
+                apdu.p1,
+                apdu.p2,
+                data=block,
+                le=apdu.le if final else None,
+            )
+            label = f"{context} [{index + 1}/{len(blocks)}]" if context else None
+            resp = self.transmit(frame, context=label)
+            if not final and not resp.ok:
+                return resp
+        if resp is None:  # unreachable: chained transmit always sends at least one frame
+            raise RuntimeError("no APDU frames were sent")
+        return resp
+
+    def disconnect(self) -> None:
+        self._conn.disconnect()
+
+    def __enter__(self) -> CardSession:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.disconnect()

cryptnox_id_cli/transport/scp02.py

@@ -0,0 +1,247 @@
+"""SCP02 secure channel (GlobalPlatform Card Spec 2.x), used for PIV admin commands.
+
+Some Cryptnox cards present an SCP02 admin channel rather than SCP03 -- notably the
+JCOP4 D321 / A27F 110KB family, whose PIV admin SSD is an SCP02 Security Domain. On
+those, ``INITIALIZE UPDATE`` returns a 28-byte body with ``keyInfo[1] == 0x02`` and the
+SCP03 layer cannot speak to the card. This module mirrors :mod:`scp03`'s shape
+(:class:`Scp02Keys`, :class:`Scp02Session`, :func:`open_channel`) so that
+:class:`~cryptnox_id_cli.applets.piv.admin.PivAdmin` is agnostic to the SCP version.
+
+The crypto follows GlobalPlatformPro (the proven ``gp`` reference) for implementation
+option **i = 0x55** (``icvEnc = true``, ``macModifiedAPDU = true``):
+
+* **Session keys** (3DES, 2-key) derived by 3DES-CBC with a zero IV over a 16-byte block
+  ``<const(2)> | seqCounter(2) | 00*12``: ``S-ENC`` (``0182``), ``S-MAC`` (``0101``),
+  ``S-DEK`` (``0181``).
+* **Cryptograms** use the full 3DES-CBC MAC (every block 3DES) with ``S-ENC`` and a zero
+  IV: card = ``MAC(hostChallenge | cardChallenge)``, host = ``MAC(cardChallenge |
+  hostChallenge)`` -- where ``cardChallenge`` is the 8 bytes ``seqCounter(2) |
+  random(6)``.
+* **C-MAC** is the ISO 9797-1 retail MAC (single-DES chain, final block 3DES) computed
+  over the *plaintext* modified APDU (CLA|0x04, INS, P1, P2, origLc+8, data). The ICV
+  starts at zero and, for every command after the first, is the previous C-MAC encrypted
+  with single-DES under ``S-MAC``.
+* **C-ENC** (when the security level includes C-DECRYPTION) is 3DES-CBC under ``S-ENC``
+  with a zero IV over 80-padded data, applied *after* the C-MAC (encrypt-and-MAC). The
+  transmitted ``Lc`` is the encrypted length + 8, while the C-MAC used origLc + 8.
+
+Correctness is proven end-to-end by the card: wrong keys fail the card-cryptogram check
+locally and EXTERNAL AUTHENTICATE is refused -- no silent corruption.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from cryptography.hazmat.decrepit.ciphers.algorithms import TripleDES
+from cryptography.hazmat.primitives.ciphers import Cipher, modes
+
+from cryptnox_id_cli.transport.apdu import APDU, Response
+from cryptnox_id_cli.transport.errors import Scp02Error
+
+_BLOCK = 8
+_ZERO_IV = b"\x00" * _BLOCK
+
+# Session-key derivation constants (GP Card Spec 2.2, E.4.1).
+_DERIV_S_ENC = b"\x01\x82"
+_DERIV_S_MAC = b"\x01\x01"
+_DERIV_S_DEK = b"\x01\x81"
+
+# Security-level bits (EXTERNAL AUTHENTICATE P1) -- same encoding as SCP03.
+SL_C_MAC = 0x01
+SL_C_DECRYPTION = 0x02
+SL_CMAC_CENC = SL_C_MAC | SL_C_DECRYPTION  # 0x03
+
+# Largest plaintext we wrap into a single short APDU. Encrypted+padded data plus the
+# 8-byte C-MAC must leave the Lc <= 0xFF; larger bodies go via ISO command chaining
+# (PivAdmin.send_chained, block_size=200), so this ceiling is never hit in practice.
+_MAX_SHORT_PLAINTEXT = 239
+
+
+def _k3(key: bytes) -> bytes:
+    """Expand a 16-byte 2-key 3DES key to the 24-byte K1|K2|K1 form GP uses."""
+    return key + key[:8] if len(key) == 16 else key
+
+
+def _k1(key: bytes) -> bytes:
+    """The first 8 key bytes as a 24-byte single-DES key (K1|K1|K1)."""
+    return key[:8] * 3
+
+
+def _des_ecb(key: bytes, block: bytes) -> bytes:
+    """Single-DES ECB (the first 8 key bytes), used for ICV encryption."""
+    enc = Cipher(TripleDES(_k1(key)), modes.ECB()).encryptor()  # noqa: S304 - single-block ICV
+    return enc.update(block) + enc.finalize()
+
+
+def _des_cbc(key: bytes, iv: bytes, data: bytes) -> bytes:
+    """Single-DES CBC (the first 8 key bytes)."""
+    enc = Cipher(TripleDES(_k1(key)), modes.CBC(iv)).encryptor()
+    return enc.update(data) + enc.finalize()
+
+
+def _des3_cbc(key: bytes, iv: bytes, data: bytes) -> bytes:
+    """3DES CBC (2-key static/session keys expanded to the 24-byte K1|K2|K1 form)."""
+    enc = Cipher(TripleDES(_k3(key)), modes.CBC(iv)).encryptor()
+    return enc.update(data) + enc.finalize()
+
+
+def _pad80(data: bytes) -> bytes:
+    """ISO 7816-4 padding: 0x80 then 0x00s to the next 8-byte boundary (always adds)."""
+    padded = data + b"\x80"
+    if len(padded) % _BLOCK:
+        padded += b"\x00" * (_BLOCK - len(padded) % _BLOCK)
+    return padded
+
+
+def _mac_3des(s_enc: bytes, data: bytes) -> bytes:
+    """Full 3DES-CBC MAC over 80-padded data, zero IV -- used for the cryptograms."""
+    out = _des3_cbc(s_enc, _ZERO_IV, _pad80(data))
+    return out[-_BLOCK:]
+
+
+def _retail_mac(s_mac: bytes, data: bytes, icv: bytes) -> bytes:
+    """ISO 9797-1 MAC algorithm 3 (retail MAC): single-DES chain, final block 3DES."""
+    padded = _pad80(data)
+    iv = icv
+    if len(padded) > _BLOCK:
+        chain = _des_cbc(s_mac, iv, padded[:-_BLOCK])
+        iv = chain[-_BLOCK:]
+    return _des3_cbc(s_mac, iv, padded[-_BLOCK:])[-_BLOCK:]
+
+
+def _derive_key(static_key: bytes, constant: bytes, seq: bytes) -> bytes:
+    """Derive one 16-byte session key: 3DES-CBC(zero IV) over const | seq | 00*12."""
+    return _des3_cbc(static_key, _ZERO_IV, constant + seq + b"\x00" * 12)
+
+
+@dataclass
+class Scp02Keys:
+    enc: bytes
+    mac: bytes
+    dek: bytes
+
+    @classmethod
+    def same(cls, key: bytes) -> Scp02Keys:
+        return cls(key, key, key)
+
+
+class Scp02Session:
+    """An open SCP02 session: holds session keys and wraps/unwraps command APDUs."""
+
+    def __init__(self, s_enc: bytes, s_mac: bytes, s_dek: bytes, security_level: int) -> None:
+        self.s_enc = s_enc
+        self.s_mac = s_mac
+        self.s_dek = s_dek
+        self.security_level = security_level
+        #: last computed C-MAC; ``None`` until the first MAC (EXTERNAL AUTHENTICATE).
+        self.icv: bytes | None = None
+
+    def _cmac(self, mac_input: bytes) -> bytes:
+        """Retail MAC over ``mac_input`` with ICV chaining; advances the session ICV."""
+        # First MAC uses the zero ICV; later commands chain on single-DES(previous C-MAC).
+        icv = _ZERO_IV if self.icv is None else _des_ecb(self.s_mac, self.icv)
+        mac = _retail_mac(self.s_mac, mac_input, icv)
+        self.icv = mac
+        return mac
+
+    def wrap(self, apdu: APDU) -> bytes:
+        """Return the wrapped command bytes (CLA|0x04, optional C-ENC, C-MAC appended).
+
+        Short Lc only -- callers chain larger bodies (see ``_MAX_SHORT_PLAINTEXT``). The
+        C-MAC is computed over the *plaintext* modified APDU (origLc+8); the data is then
+        encrypted and the wire Lc becomes the encrypted length + 8.
+        """
+        data = apdu.data
+        if len(data) > _MAX_SHORT_PLAINTEXT:
+            raise Scp02Error(
+                f"SCP02 wraps short APDUs only ({len(data)} > {_MAX_SHORT_PLAINTEXT} "
+                "plaintext bytes); send large bodies via command chaining."
+            )
+        cla = apdu.cla | 0x04
+        header = bytes([cla, apdu.ins, apdu.p1, apdu.p2])
+
+        # C-MAC over the plaintext modified APDU: header | (origLc + 8) | data.
+        mac = self._cmac(header + bytes([len(data) + 8]) + data)
+
+        body = data
+        if self.security_level & SL_C_DECRYPTION and data:
+            body = _des3_cbc(self.s_enc, _ZERO_IV, _pad80(data))
+
+        out = header + bytes([len(body) + 8]) + body + mac
+        if apdu.le is not None:
+            out += bytes([0x00 if apdu.le >= 256 else apdu.le & 0xFF])
+        return out
+
+    def unwrap(self, resp: Response) -> Response:
+        """At security level 0x03 the response is plaintext; pass it through."""
+        return resp
+
+
+def derive_session_keys(keys: Scp02Keys, seq: bytes) -> tuple[bytes, bytes, bytes]:
+    s_enc = _derive_key(keys.enc, _DERIV_S_ENC, seq)
+    s_mac = _derive_key(keys.mac, _DERIV_S_MAC, seq)
+    s_dek = _derive_key(keys.dek, _DERIV_S_DEK, seq)
+    return s_enc, s_mac, s_dek
+
+
+def open_channel(
+    transmit,
+    keys: Scp02Keys,
+    *,
+    key_version: int = 0,
+    security_level: int = SL_CMAC_CENC,
+    host_challenge: bytes | None = None,
+    init_response: Response | None = None,
+) -> Scp02Session:
+    """Run INITIALIZE UPDATE + EXTERNAL AUTHENTICATE for SCP02.
+
+    ``transmit(APDU|bytes) -> Response``. If ``init_response`` is given (the caller has
+    already issued INITIALIZE UPDATE to auto-detect the SCP version), it is reused with
+    the matching ``host_challenge`` instead of issuing a second one.
+
+    Raises :class:`Scp02Error` on a wrong key (card-cryptogram mismatch) or a card
+    rejection.
+    """
+    if init_response is None:
+        host_challenge = host_challenge or os.urandom(8)
+        resp = transmit(APDU(0x80, 0x50, key_version, 0x00, data=host_challenge, le=256))
+    else:
+        if host_challenge is None:
+            raise Scp02Error("host_challenge is required when init_response is supplied.")
+        resp = init_response
+
+    if not resp.ok:
+        raise Scp02Error(f"INITIALIZE UPDATE rejected (SW={resp.sw_hex()}).")
+    body = resp.data
+    if len(body) < 28:
+        raise Scp02Error(f"INITIALIZE UPDATE response too short ({len(body)} bytes) for SCP02.")
+
+    # keyDivData(10) | keyInfo(2: ver, 0x02) | seqCounter(2) | cardChallenge(6) | cardCrypto(8).
+    seq = body[12:14]
+    card_challenge = body[12:20]  # full 8-byte challenge = seqCounter | random(6)
+    card_cryptogram = body[20:28]
+
+    s_enc, s_mac, s_dek = derive_session_keys(keys, seq)
+
+    expected = _mac_3des(s_enc, host_challenge + card_challenge)
+    if expected != card_cryptogram:
+        raise Scp02Error("Card cryptogram mismatch - the SCP02 keys are wrong for this card.")
+
+    session = Scp02Session(s_enc, s_mac, s_dek, security_level)
+    host_cryptogram = _mac_3des(s_enc, card_challenge + host_challenge)
+
+    # EXTERNAL AUTHENTICATE: CLA 0x84, P1 = security level, Lc = 0x10 (host cryptogram + C-MAC).
+    # The host cryptogram is MACed in clear (never encrypted), with the zero ICV.
+    header = bytes([0x84, 0x82, security_level, 0x00])
+    mac = session._cmac(header + bytes([len(host_cryptogram) + 8]) + host_cryptogram)
+    ext_auth = header + bytes([len(host_cryptogram) + 8]) + host_cryptogram + mac
+
+    resp = transmit(ext_auth)
+    if not resp.ok:
+        raise Scp02Error(
+            f"EXTERNAL AUTHENTICATE rejected (SW={resp.sw_hex()}); "
+            "keys or security level may be wrong."
+        )
+    return session