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

cryptnox_id_cli/applets/piv/piv.py

@@ -0,0 +1,171 @@
+"""Read-only PIV applet operations over a :class:`CardSession`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cryptnox_id_cli.applets.piv import constants as c
+from cryptnox_id_cli.applets.piv import objects as obj
+from cryptnox_id_cli.applets.piv.apt import APTInfo, parse_apt
+from cryptnox_id_cli.transport.apdu import APDU, Response
+from cryptnox_id_cli.transport.errors import AppletNotFoundError, StatusWordError
+from cryptnox_id_cli.transport.pcsc import CardSession
+
+
+@dataclass(frozen=True)
+class PinStatus:
+    ref: int
+    configured: bool
+    blocked: bool
+    verified: bool
+    retries: int | None  # remaining tries (None if unknown / not configured)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "ref": f"{self.ref:02X}",
+            "configured": self.configured,
+            "blocked": self.blocked,
+            "verified": self.verified,
+            "retries_remaining": self.retries,
+        }
+
+
+def _pin_status_from_sw(ref: int, resp: Response) -> PinStatus:
+    sw = resp.sw
+    if sw == 0x9000:  # already verified in this session
+        return PinStatus(ref, configured=True, blocked=False, verified=True, retries=None)
+    if resp.sw1 == 0x63 and (resp.sw2 & 0xF0) == 0xC0:
+        tries = resp.sw2 & 0x0F
+        return PinStatus(ref, configured=True, blocked=tries == 0, verified=False, retries=tries)
+    if sw == 0x6983:  # blocked
+        return PinStatus(ref, configured=True, blocked=True, verified=False, retries=0)
+    if sw in (0x6A88, 0x6A80, 0x6A82):  # reference not configured
+        return PinStatus(ref, configured=False, blocked=False, verified=False, retries=None)
+    # Unknown — report not-configured-ish but keep retries None.
+    return PinStatus(ref, configured=False, blocked=False, verified=False, retries=None)
+
+
+def _pad_pin(pin: bytes) -> bytes:
+    """PIV PINs are 8 bytes, padded with 0xFF."""
+    if len(pin) > 8:
+        raise ValueError("PIN must be at most 8 bytes")
+    return bytes(pin) + b"\xff" * (8 - len(pin))
+
+
+class PivApplet:
+    """Thin, read-only PIV client. Mutating commands arrive in later phases."""
+
+    def __init__(self, session: CardSession) -> None:
+        self.session = session
+        self._apt: APTInfo | None = None
+
+    # -- selection ---------------------------------------------------------- #
+    def select(self) -> APTInfo:
+        resp = self.session.transmit(
+            APDU(0x00, c.INS_SELECT, 0x04, 0x00, data=c.PIV_AID, le=256), context="SELECT PIV"
+        )
+        # On the multi-applet card, the first case-4 ISO SELECT issued right after a
+        # DESFire native-command session is rejected with 6700 ("wrong length"); the
+        # identical SELECT sent as case-3 (no Le) is accepted and still returns the
+        # FCI. The composite StateDetector probes DESFire first, so without this the
+        # PIV applet is mis-reported as Unknown over a contactless reader. Retry once
+        # without Le. See docs/troubleshooting.md.
+        if resp.sw == 0x6700:
+            resp = self.session.transmit(
+                APDU(0x00, c.INS_SELECT, 0x04, 0x00, data=c.PIV_AID), context="SELECT PIV (no Le)"
+            )
+        if resp.sw == 0x6A82:
+            raise AppletNotFoundError("PIV applet not found on this card.")
+        if not resp.ok:
+            raise StatusWordError(resp.sw1, resp.sw2, context="SELECT PIV")
+        self._apt = parse_apt(resp.data)
+        return self._apt
+
+    def try_select(self) -> APTInfo | None:
+        try:
+            return self.select()
+        except AppletNotFoundError:
+            return None
+
+    @property
+    def apt(self) -> APTInfo | None:
+        return self._apt
+
+    # -- data objects ------------------------------------------------------- #
+    def get_data(self, oid: bytes) -> Response:
+        return self.session.transmit(obj.get_data_apdu(oid), context="GET DATA")
+
+    def read_object(self, oid: bytes) -> bytes | None:
+        """Return the unwrapped object content, or None if absent (6A82)."""
+        resp = self.get_data(oid)
+        if resp.sw == 0x6A82:
+            return None
+        if not resp.ok:
+            # Access-gated objects (e.g. PIN-protected) may return 6982 — surface as absent-ish.
+            if resp.sw in (0x6982, 0x6983):
+                return None
+            raise StatusWordError(resp.sw1, resp.sw2, context="GET DATA")
+        return obj.unwrap(oid, resp.data)
+
+    def object_present(self, oid: bytes) -> bool:
+        """True if the object holds content (or exists but is access-gated).
+
+        Two distinct "absent" cases per SP 800-73 4.1.1 (same clause in -4 and
+        -5): a container never created at pre-personalization returns 6A82,
+        while a created-but-unused container returns a zero-length object
+        (9000). Both count as absent for every caller's purpose (status, slots,
+        validate, quickstart).
+        """
+        resp = self.get_data(oid)
+        if resp.sw in (0x6982, 0x6983):  # exists but access-gated still counts
+            return True
+        if not resp.ok:
+            return False
+        return bool(obj.unwrap(oid, resp.data))
+
+    # -- PIN / PUK ---------------------------------------------------------- #
+    def pin_status(self, ref: int = c.REF_PIV_PIN) -> PinStatus:
+        """Non-decrementing status query (VERIFY with empty body)."""
+        resp = self.session.transmit(APDU(0x00, c.INS_VERIFY, 0x00, ref), context="VERIFY (status)")
+        return _pin_status_from_sw(ref, resp)
+
+    def verify_pin(self, pin: bytes, ref: int = c.REF_PIV_PIN) -> Response:
+        """Verify a PIN. NOTE: a wrong PIN decrements the retry counter."""
+        self.session.redactor.register(pin)
+        padded = _pad_pin(pin)
+        self.session.redactor.register(padded)
+        return self.session.transmit(
+            APDU(0x00, c.INS_VERIFY, 0x00, ref, data=padded), context="VERIFY PIN"
+        )
+
+    def change_reference(self, old: bytes, new: bytes, ref: int = c.REF_PIV_PIN) -> Response:
+        """Cardholder CHANGE REFERENCE DATA (INS 24, P1=00): swap a PIN or PUK value.
+
+        Body is the current value then the new value, each 0xFF-padded to 8 bytes.
+        A wrong ``old`` decrements the ref's retry counter (same as VERIFY). No admin
+        channel: the cardholder proves knowledge of the current value in-band.
+        """
+        for secret in (old, new):
+            self.session.redactor.register(secret)
+        body = _pad_pin(old) + _pad_pin(new)
+        self.session.redactor.register(body)
+        return self.session.transmit(
+            APDU(0x00, c.INS_CHANGE_REFERENCE_DATA, 0x00, ref, data=body),
+            context="CHANGE REFERENCE DATA",
+        )
+
+    def unblock_pin(self, puk: bytes, new_pin: bytes, ref: int = c.REF_PIV_PIN) -> Response:
+        """RESET RETRY COUNTER (INS 2C): unblock the PIN by proving the PUK.
+
+        Body is the PUK then the new PIN, each 0xFF-padded to 8 bytes. Resets the
+        PIN retry counter to its configured maximum. A wrong PUK decrements the PUK's
+        own counter; if the PUK blocks too, the PIN is unrecoverable.
+        """
+        for secret in (puk, new_pin):
+            self.session.redactor.register(secret)
+        body = _pad_pin(puk) + _pad_pin(new_pin)
+        self.session.redactor.register(body)
+        return self.session.transmit(
+            APDU(0x00, c.INS_RESET_RETRY, 0x00, ref, data=body),
+            context="RESET RETRY COUNTER",
+        )

cryptnox_id_cli/applets/piv/preperso.py

@@ -0,0 +1,174 @@
+"""OpenFIPS201 PUT DATA ADMIN grammar (pre-personalization / factory).
+
+Mirrors the applet's own perso toolkit (``tools/perso/piv_admin.py``) byte-for-byte.
+Builders emit only the CDATA; the SCP03 layer wraps it into the secured APDU
+``84 DB 3F 00 <Lc> <payload> <C-MAC>``.
+
+Create-object parse order enforced by the applet (sequential TLVReader):
+  common prefix:  8B object-id, 8C mode-contact, 8D mode-contactless, [91 admin-key]
+  CONTAINER (0x64): nothing further
+  VERIFIER  (0x65): 8E min-len, 8F max-len, 90 retries-contact, 91 retries-contactless,
+                    [92 charset] [93 history] [94 sequence] [95 repeat] [96 restrict-update]
+  KEY       (0x66): 8E mechanism, 8F role, 90 attributes
+The order is significant — do not reorder elements.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from cryptnox_id_cli.transport.apdu import APDU
+from cryptnox_id_cli.util.tlv import build, build_constructed, concat
+
+# PUT DATA ADMIN command header.
+INS_PUT_DATA = 0xDB
+PUT_DATA_P1 = 0x3F
+PUT_DATA_P2_ADMIN = 0x00
+
+# Operation tags.
+OP_CREATE_CONTAINER = 0x64
+OP_CREATE_VERIFIER = 0x65
+OP_CREATE_KEY = 0x66
+OP_UPDATE_CONFIG = 0x68
+OP_SECURE_APPLET = 0x5F
+OP_BULK_REQUEST = 0x6A
+
+# Common element tags.
+TAG_OBJECT_ID = 0x8B
+TAG_MODE_CONTACT = 0x8C
+TAG_MODE_CONTACTLESS = 0x8D
+TAG_ADMIN_KEY = 0x91  # optional, container/key only (NOT verifier)
+
+# Key element tags.
+TAG_KEY_MECHANISM = 0x8E
+TAG_KEY_ROLE = 0x8F
+TAG_KEY_ATTRIBUTE = 0x90
+
+# Verifier element tags.
+TAG_PIN_MIN_LENGTH = 0x8E
+TAG_PIN_MAX_LENGTH = 0x8F
+TAG_PIN_RETRIES_CONTACT = 0x90
+TAG_PIN_RETRIES_CONTACTLESS = 0x91
+TAG_PIN_RULE_CHARSET = 0x92
+TAG_PIN_RULE_HISTORY = 0x93
+TAG_PIN_RULE_SEQUENCE = 0x94
+TAG_PIN_RULE_REPEAT = 0x95
+TAG_PIN_RESTRICT_UPDATE = 0x96
+
+# Access-mode bytes. A mode is a bitmap EXCEPT ALWAYS which is the special 0x3F.
+MODE_NEVER = 0x00
+MODE_PIN = 0x01
+MODE_OCC = 0x04
+MODE_SM = 0x40
+MODE_USER_ADMIN = 0x80
+MODE_ALWAYS = 0x3F
+MODE_VCI = MODE_SM  # 0x40 (contactless read gated to a PIV-SM session)
+MODE_VCI_PIN = MODE_SM | MODE_PIN  # 0x41
+
+# Key roles and attributes (bitmaps).
+ROLE_AUTHENTICATE = 0x01
+ROLE_KEY_ESTABLISH = 0x02
+ROLE_SIGN = 0x04
+
+ATTR_PERMIT_EXTERNAL = 0x04
+ATTR_PERMIT_MUTUAL = 0x08
+ATTR_IMPORTABLE = 0x10
+ATTR_RSA_CRT = 0x20
+
+
+def _object_id_bytes(object_id: int | bytes | Sequence[int]) -> bytes:
+    if isinstance(object_id, int):
+        return bytes([object_id])
+    return bytes(object_id)
+
+
+def create_container(
+    object_id: int | bytes,
+    mode_contact: int,
+    mode_contactless: int,
+    admin_key: int | None = None,
+) -> bytes:
+    parts = [
+        build(TAG_OBJECT_ID, _object_id_bytes(object_id)),
+        build(TAG_MODE_CONTACT, bytes([mode_contact])),
+        build(TAG_MODE_CONTACTLESS, bytes([mode_contactless])),
+    ]
+    if admin_key is not None:
+        parts.append(build(TAG_ADMIN_KEY, bytes([admin_key])))
+    return build_constructed(OP_CREATE_CONTAINER, *parts)
+
+
+def create_verifier(
+    verifier_id: int,
+    mode_contact: int,
+    mode_contactless: int,
+    min_length: int,
+    max_length: int,
+    retries_contact: int,
+    retries_contactless: int,
+    charset: int | None = None,
+    history: int | None = None,
+    sequence: int | None = None,
+    repeat: int | None = None,
+    restrict_update: int | None = None,
+) -> bytes:
+    parts = [
+        build(TAG_OBJECT_ID, bytes([verifier_id])),
+        build(TAG_MODE_CONTACT, bytes([mode_contact])),
+        build(TAG_MODE_CONTACTLESS, bytes([mode_contactless])),
+        build(TAG_PIN_MIN_LENGTH, bytes([min_length])),
+        build(TAG_PIN_MAX_LENGTH, bytes([max_length])),
+        build(TAG_PIN_RETRIES_CONTACT, bytes([retries_contact])),
+        build(TAG_PIN_RETRIES_CONTACTLESS, bytes([retries_contactless])),
+    ]
+    for tag, val in (
+        (TAG_PIN_RULE_CHARSET, charset),
+        (TAG_PIN_RULE_HISTORY, history),
+        (TAG_PIN_RULE_SEQUENCE, sequence),
+        (TAG_PIN_RULE_REPEAT, repeat),
+        (TAG_PIN_RESTRICT_UPDATE, restrict_update),
+    ):
+        if val is not None:
+            parts.append(build(tag, bytes([val])))
+    return build_constructed(OP_CREATE_VERIFIER, *parts)
+
+
+def create_key(
+    key_id: int,
+    mode_contact: int,
+    mode_contactless: int,
+    mechanism: int,
+    role: int,
+    attributes: int,
+    admin_key: int | None = None,
+) -> bytes:
+    parts = [
+        build(TAG_OBJECT_ID, bytes([key_id])),
+        build(TAG_MODE_CONTACT, bytes([mode_contact])),
+        build(TAG_MODE_CONTACTLESS, bytes([mode_contactless])),
+    ]
+    if admin_key is not None:
+        parts.append(build(TAG_ADMIN_KEY, bytes([admin_key])))
+    parts.extend(
+        [
+            build(TAG_KEY_MECHANISM, bytes([mechanism])),
+            build(TAG_KEY_ROLE, bytes([role])),
+            build(TAG_KEY_ATTRIBUTE, bytes([attributes])),
+        ]
+    )
+    return build_constructed(OP_CREATE_KEY, *parts)
+
+
+def secure_applet() -> bytes:
+    """SECURE APPLET (0x5F) — primitive, empty body. IRREVERSIBLE (locks the applet)."""
+    return build(OP_SECURE_APPLET, b"")
+
+
+def build_bulk(ops: Sequence[bytes]) -> bytes:
+    """Wrap operation TLVs into a BULK request (0x6A)."""
+    return build_constructed(OP_BULK_REQUEST, concat(*ops))
+
+
+def put_data_admin_apdu(payload: bytes) -> APDU:
+    """The (unsecured) PUT DATA ADMIN command; the SCP03 layer secures/wraps it."""
+    return APDU(0x00, INS_PUT_DATA, PUT_DATA_P1, PUT_DATA_P2_ADMIN, data=payload)