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

cryptnox_id_cli/applets/piv/constants.py

@@ -0,0 +1,66 @@
+"""PIV constants for the OpenFIPS201 applet under test.
+
+Values reflect what THIS applet implements (verified from source + the live card),
+not generic PIV assumptions: e.g. no 3DES, no RSA-1024/4096; admin key is AES-only.
+"""
+
+from __future__ import annotations
+
+# AID observed on the card; the trailing 00 01 00 is the version/coexistent suffix.
+PIV_AID = bytes.fromhex("A000000308000010000100")
+PIV_RID = bytes.fromhex("A000000308")
+
+# Instruction bytes (ISO 7816-4 / PIV).
+INS_SELECT = 0xA4
+INS_GET_DATA = 0xCB
+INS_VERIFY = 0x20
+INS_CHANGE_REFERENCE_DATA = 0x24
+INS_RESET_RETRY = 0x2C
+INS_GENERAL_AUTHENTICATE = 0x87
+INS_PUT_DATA = 0xDB
+INS_GENERATE_ASYMMETRIC = 0x47
+INS_GET_RESPONSE = 0xC0
+
+# Key-reference (slot) bytes.
+KEYREF_PIV_AUTH = 0x9A
+KEYREF_ADMIN = 0x9B  # management/admin key (AES only on this applet)
+KEYREF_DIGITAL_SIGNATURE = 0x9C
+KEYREF_KEY_MANAGEMENT = 0x9D
+KEYREF_CARD_AUTH = 0x9E
+KEYREF_SECURE_MESSAGING = 0x04
+KEYREF_RETIRED_FIRST = 0x82
+KEYREF_RETIRED_LAST = 0x95
+
+# Verifier references. The PIV Application PIN (0x80) is the only cardholder PIN this
+# CLI provisions; the Global PIN (key ref 0x00) is intentionally not supported -- see
+# docs/adr/0001-piv-application-pin-not-global-pin.md.
+REF_PIV_PIN = 0x80
+REF_PUK = 0x81
+
+# Algorithm identifiers (SP 800-78). Only the ones THIS applet supports are "supported".
+ALGORITHMS: dict[int, str] = {
+    0x06: "RSA-1024",
+    0x07: "RSA-2048",
+    0x05: "RSA-3072",
+    0x16: "RSA-4096",
+    0x08: "AES-128",
+    0x0A: "AES-192",
+    0x0C: "AES-256",
+    0x11: "ECC-P256",
+    0x14: "ECC-P384",
+    0x27: "PIV-SM-CS2 (AES-128/SHA-256)",
+    0x2E: "PIV-SM-CS7 (AES-256/SHA-384)",
+}
+
+# Algorithms this OpenFIPS201 FIPS build actually implements. RSA-4096 (0x16) is
+# included: on-card createKey + GENERATE for RSA-4096 is confirmed on the D600/SCP03
+# hardware (returns a real 512-byte modulus), gated only by the chip's DF2B max-RSA
+# = 0x1000 on a non-fused card. NOTE: this covers on-card key GENERATION and key
+# objects; the host-side key-IMPORT/sign helpers (keyimport.py) still cover only
+# RSA-2048/3072, so external RSA-4096 import is a separate, not-yet-implemented path.
+SUPPORTED_ALGORITHMS: frozenset[int] = frozenset(
+    {0x07, 0x05, 0x16, 0x08, 0x0A, 0x0C, 0x11, 0x14, 0x27, 0x2E}
+)
+
+# Explicitly removed in this FIPS build (used to warn / never offer).
+REMOVED_ALGORITHMS: frozenset[int] = frozenset({0x06})  # RSA-1024 (+ 3DES) — FIPS-gated

cryptnox_id_cli/applets/piv/keyimport.py

@@ -0,0 +1,244 @@
+"""PIV asymmetric private-key injection (CHANGE REFERENCE DATA ADMIN over SCP03).
+
+OpenFIPS201 accepts externally generated key material with ``00 24 <P1=mechanism>
+<P2=key reference>`` carrying exactly ONE key-element TLV per command, so an import
+is a short sequence of admin commands (one fresh SCP03 session each on JCOP 4.5).
+The target key object must already exist with the same (slot, mechanism) pair and
+the IMPORTABLE attribute; RSA objects additionally fix CRT vs plain form at
+creation. A key only becomes usable once both public and private parts are loaded,
+and re-loading an initialised key requires a CLEAR first — every plan therefore
+starts with CLEAR, which makes re-imports idempotent.
+
+Element tags and exact-length rules (mirrors the applet's PIVKeyECC/PIVKeyRSA):
+CLEAR ``9F`` (empty); ECC public point ``86`` (X9.62 uncompressed, 65/97 bytes) and
+private scalar ``87`` (big-endian right-aligned, 32/48 bytes); RSA modulus ``81``
+(k bytes), public exponent ``82`` (exactly 3 bytes), private exponent ``83``
+(k bytes, plain form only), CRT components ``90``/``91``/``92``/``93``/``94``
+(P/Q/dP/dQ/qInv, each k/2 bytes).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+
+from cryptnox_id_cli.applets.piv import constants as c
+from cryptnox_id_cli.transport.apdu import APDU
+from cryptnox_id_cli.transport.errors import CryptnoxError
+from cryptnox_id_cli.util import tlv
+
+INS_CHANGE_REFERENCE_DATA = 0x24
+INS_GENERAL_AUTHENTICATE = 0x87
+
+ELEMENT_CLEAR = 0x9F
+ELEMENT_ECC_POINT = 0x86
+ELEMENT_ECC_SECRET = 0x87
+ELEMENT_RSA_N = 0x81
+ELEMENT_RSA_E = 0x82
+ELEMENT_RSA_D = 0x83
+ELEMENT_RSA_P = 0x90
+ELEMENT_RSA_Q = 0x91
+ELEMENT_RSA_DP = 0x92
+ELEMENT_RSA_DQ = 0x93
+ELEMENT_RSA_PQ = 0x94
+
+# Largest TLV body sent as a single (SCP03-wrapped) short APDU; larger bodies go
+# through ISO command chaining. Matches PivAdmin.send_chained's plaintext budget.
+SINGLE_APDU_MAX = 200
+
+# Mechanism -> (curve, scalar/point sizes) for ECC, modulus size for RSA.
+_EC_BY_MECH: dict[int, type[ec.EllipticCurve]] = {0x11: ec.SECP256R1, 0x14: ec.SECP384R1}
+_EC_SCALAR_LEN = {0x11: 32, 0x14: 48}
+_RSA_MODULUS_LEN = {0x07: 256, 0x05: 384}
+
+# Host-side slot policy (SP 800-78 per-key-reference algorithm table): PKI slots
+# and the retired key history accept the four asymmetric mechanisms; 9B is
+# AES-only and 04 is secure-messaging-only. The deployed pristine v2.0.0-fips
+# applet does NOT enforce this on-card (the 800-73-5 branch adds it as gap
+# G2/G4) - the CLI refuses host-side either way.
+_ASYM_SLOTS = frozenset(
+    {
+        c.KEYREF_PIV_AUTH,
+        c.KEYREF_DIGITAL_SIGNATURE,
+        c.KEYREF_KEY_MANAGEMENT,
+        c.KEYREF_CARD_AUTH,
+        *range(c.KEYREF_RETIRED_FIRST, c.KEYREF_RETIRED_LAST + 1),
+    }
+)
+
+# DigestInfo prefixes for EMSA-PKCS1-v1_5 (RFC 8017 §9.2 notes).
+_DIGEST_INFO = {
+    "sha256": bytes.fromhex("3031300D060960864801650304020105000420"),
+    "sha384": bytes.fromhex("3041300D060960864801650304020205000430"),
+}
+
+
+class KeyImportError(CryptnoxError):
+    """Key material unsuitable for this applet (algorithm, slot, encoding)."""
+
+    code = "key_import"
+
+
+@dataclass(frozen=True)
+class KeyElement:
+    """One CHANGE REFERENCE DATA ADMIN element: a single tagged key component."""
+
+    tag: int
+    value: bytes
+    label: str
+    secret: bool
+
+    def body(self) -> bytes:
+        return tlv.build(self.tag, self.value)
+
+
+def load_private_key(raw: bytes, password: bytes | None):
+    """Load a PEM or DER private key (PKCS#8 or traditional encoding)."""
+    loader = (
+        serialization.load_pem_private_key
+        if raw.lstrip().startswith(b"-----")
+        else serialization.load_der_private_key
+    )
+    return loader(raw, password=password)
+
+
+def load_pkcs12(raw: bytes, password: bytes | None):
+    """Parse a PKCS#12 container -> (private key, leaf certificate DER, extra
+    certificate DERs). Both a key and its certificate must be present — that is
+    the point of the .p12 device-setup flow."""
+    from cryptography.hazmat.primitives.serialization import pkcs12
+
+    key, cert, extras = pkcs12.load_key_and_certificates(raw, password)
+    if key is None or cert is None:
+        raise KeyImportError("the PKCS#12 file must contain both a private key and its certificate")
+    der = cert.public_bytes(serialization.Encoding.DER)
+    extra_ders = [c_.public_bytes(serialization.Encoding.DER) for c_ in (extras or [])]
+    return key, der, extra_ders
+
+
+def mechanism_for_key(key) -> int:
+    """Map a private key to this applet's mechanism id, or refuse it."""
+    if isinstance(key, ec.EllipticCurvePrivateKey):
+        for mech, curve in _EC_BY_MECH.items():
+            if isinstance(key.curve, curve):
+                return mech
+        raise KeyImportError(
+            f"EC curve {key.curve.name} not supported; this applet takes "
+            "SECP256R1 (ECCP256) or SECP384R1 (ECCP384)."
+        )
+    if isinstance(key, rsa.RSAPrivateKey):
+        for mech, k in _RSA_MODULUS_LEN.items():
+            if key.key_size == k * 8:
+                return mech
+        raise KeyImportError(
+            f"RSA-{key.key_size} not supported; this applet takes RSA-2048 or RSA-3072."
+        )
+    raise KeyImportError(
+        f"unsupported key type {type(key).__name__}; this applet takes "
+        "ECC P-256/P-384 and RSA-2048/3072."
+    )
+
+
+def validate_slot_mechanism(ref: int, mechanism: int) -> None:
+    """Refuse slots that can never hold an asymmetric key on this applet."""
+    if ref == c.KEYREF_ADMIN:
+        raise KeyImportError("slot 9B is the admin key (AES only); it cannot hold a PKI key.")
+    if ref == c.KEYREF_SECURE_MESSAGING:
+        raise KeyImportError("slot 04 is reserved for PIV secure messaging.")
+    if ref not in _ASYM_SLOTS:
+        raise KeyImportError(
+            f"slot {ref:02X} is not a PIV asymmetric key slot "
+            "(use 9A/9C/9D/9E or a retired slot 82-95)."
+        )
+    if mechanism not in (*_EC_BY_MECH, *_RSA_MODULUS_LEN):
+        raise KeyImportError(f"mechanism {mechanism:#04x} is not an asymmetric mechanism.")
+
+
+def encode_exponent(e: int) -> bytes:
+    """The applet takes the RSA public exponent as exactly 3 bytes."""
+    if e <= 0 or e >= 1 << 24:
+        raise KeyImportError(f"RSA public exponent {e} does not fit the applet's 3-byte field.")
+    return e.to_bytes(3, "big")
+
+
+def element_plan(key, *, rsa_crt: bool = True) -> list[KeyElement]:
+    """The ordered element sequence for a key: CLEAR, then public, then private.
+
+    The key object only flips to initialised when its last component lands, so
+    every intermediate element is accepted on a freshly cleared object.
+    """
+    mechanism = mechanism_for_key(key)
+    if isinstance(key, ec.EllipticCurvePrivateKey):
+        n = _EC_SCALAR_LEN[mechanism]
+        point = key.public_key().public_bytes(
+            serialization.Encoding.X962, serialization.PublicFormat.UncompressedPoint
+        )
+        scalar = key.private_numbers().private_value.to_bytes(n, "big")
+        return [
+            KeyElement(ELEMENT_CLEAR, b"", "CLEAR (9F)", False),
+            KeyElement(ELEMENT_ECC_POINT, point, "public point (86)", False),
+            KeyElement(ELEMENT_ECC_SECRET, scalar, "private scalar (87)", True),
+        ]
+    k = _RSA_MODULUS_LEN[mechanism]
+    pub = key.public_key().public_numbers()
+    priv = key.private_numbers()
+    plan = [
+        KeyElement(ELEMENT_CLEAR, b"", "CLEAR (9F)", False),
+        KeyElement(ELEMENT_RSA_N, pub.n.to_bytes(k, "big"), "modulus N (81)", False),
+        KeyElement(ELEMENT_RSA_E, encode_exponent(pub.e), "exponent E (82)", False),
+    ]
+    if rsa_crt:
+        half = k // 2
+        plan += [
+            KeyElement(ELEMENT_RSA_P, priv.p.to_bytes(half, "big"), "P (90)", True),
+            KeyElement(ELEMENT_RSA_Q, priv.q.to_bytes(half, "big"), "Q (91)", True),
+            KeyElement(ELEMENT_RSA_DP, priv.dmp1.to_bytes(half, "big"), "dP (92)", True),
+            KeyElement(ELEMENT_RSA_DQ, priv.dmq1.to_bytes(half, "big"), "dQ (93)", True),
+            KeyElement(ELEMENT_RSA_PQ, priv.iqmp.to_bytes(half, "big"), "qInv (94)", True),
+        ]
+    else:
+        plan.append(KeyElement(ELEMENT_RSA_D, priv.d.to_bytes(k, "big"), "private D (83)", True))
+    return plan
+
+
+def import_apdu(ref: int, mechanism: int, element: KeyElement) -> APDU:
+    """CHANGE REFERENCE DATA ADMIN carrying one key element (SCP03-wrapped later)."""
+    return APDU(0x00, INS_CHANGE_REFERENCE_DATA, mechanism, ref, data=element.body())
+
+
+def probe_apdu(ref: int, mechanism: int) -> APDU:
+    """Non-destructive (slot, mechanism) probe: GENERAL AUTHENTICATE with a dummy
+    1-byte challenge. 6A86 = no such key object; 6982 = exists, access (PIN) not
+    met; 6983 = exists, value not initialised. Never touches PIN retry counters."""
+    body = tlv.build_constructed(0x7C, tlv.build(0x82, b"") + tlv.build(0x81, b"\x00"))
+    return APDU(0x00, INS_GENERAL_AUTHENTICATE, mechanism, ref, data=body, le=256)
+
+
+def digest_for_mechanism(mechanism: int):
+    """The hash this CLI pairs with each mechanism (SHA-256, SHA-384 for P-384)."""
+    return hashes.SHA384() if mechanism == 0x14 else hashes.SHA256()
+
+
+def rsa_modulus_len(mechanism: int) -> int | None:
+    """Modulus length in bytes for an RSA mechanism, ``None`` otherwise."""
+    return _RSA_MODULUS_LEN.get(mechanism)
+
+
+def emsa_pkcs1_v15(digest: bytes, em_len: int, *, hash_name: str | None = None) -> bytes:
+    """EMSA-PKCS1-v1_5 encode a message digest to ``em_len`` bytes (RFC 8017 §9.2).
+
+    The applet's RSA GENERAL AUTHENTICATE performs a raw private-key operation over
+    a full modulus-length block, so the host supplies the padded encoding. The hash
+    is inferred from the digest length unless given explicitly.
+    """
+    if hash_name is None:
+        hash_name = {32: "sha256", 48: "sha384"}.get(len(digest), "")
+    prefix = _DIGEST_INFO.get(hash_name)
+    if prefix is None:
+        raise KeyImportError(f"no DigestInfo for a {len(digest)}-byte digest")
+    t = prefix + digest
+    if em_len < len(t) + 11:
+        raise KeyImportError("modulus too short for EMSA-PKCS1-v1_5 encoding")
+    return b"\x00\x01" + b"\xff" * (em_len - len(t) - 3) + b"\x00" + t

cryptnox_id_cli/applets/piv/objects.py

@@ -0,0 +1,126 @@
+"""PIV data-object registry plus GET DATA construction / unwrapping."""
+
+from __future__ import annotations
+
+import contextlib
+import gzip
+from dataclasses import dataclass
+
+from cryptnox_id_cli.applets.piv import constants as c
+from cryptnox_id_cli.transport.apdu import APDU
+from cryptnox_id_cli.util import tlv
+from cryptnox_id_cli.util.hexutil import from_hex
+
+TAG_DATA = 0x53  # most PIV objects are wrapped in tag 0x53
+TAG_DISCOVERY = 0x7E
+TAG_CERT = 0x70  # certificate (possibly gzip-compressed)
+TAG_CERTINFO = 0x71  # 1 byte; bit0 set => certificate is gzip-compressed
+
+
+@dataclass(frozen=True)
+class PivObject:
+    name: str
+    oid: bytes
+    description: str
+    mandatory: bool = False
+    pin_protected: bool = False
+    slot: int | None = None
+
+    @property
+    def oid_hex(self) -> str:
+        return self.oid.hex().upper()
+
+
+PIV_OBJECTS: list[PivObject] = [
+    PivObject("ccc", from_hex("5FC107"), "Card Capability Container", mandatory=True),
+    PivObject("chuid", from_hex("5FC102"), "Card Holder Unique Identifier", mandatory=True),
+    PivObject("discovery", bytes([TAG_DISCOVERY]), "Discovery Object", mandatory=False),
+    PivObject(
+        "auth-cert", from_hex("5FC105"), "Certificate for PIV Auth (9A)", slot=c.KEYREF_PIV_AUTH
+    ),
+    PivObject(
+        "sign-cert",
+        from_hex("5FC10A"),
+        "Certificate for Digital Sig (9C)",
+        slot=c.KEYREF_DIGITAL_SIGNATURE,
+    ),
+    PivObject(
+        "keymgmt-cert",
+        from_hex("5FC10B"),
+        "Certificate for Key Mgmt (9D)",
+        slot=c.KEYREF_KEY_MANAGEMENT,
+    ),
+    PivObject(
+        "card-auth-cert",
+        from_hex("5FC101"),
+        "Certificate for Card Auth (9E)",
+        slot=c.KEYREF_CARD_AUTH,
+    ),
+    # Key-attestation leaf, stored in the retired-slot-95 certificate container (5FC120).
+    # This repurposes a retired-key cert container (least likely to hold a real retired key)
+    # to carry the factory/issuance-time PIV key-attestation leaf — see docs/attestation-format.md.
+    PivObject(
+        "attestation-cert",
+        from_hex("5FC120"),
+        "PIV key attestation leaf (retired slot 95 container)",
+        slot=0x95,
+    ),
+    PivObject("security-object", from_hex("5FC106"), "Security Object"),
+    PivObject("key-history", from_hex("5FC10C"), "Key History Object"),
+    PivObject("printed", from_hex("5FC109"), "Printed Information", pin_protected=True),
+    PivObject("fingerprints", from_hex("5FC103"), "Cardholder Fingerprints", pin_protected=True),
+    PivObject("facial", from_hex("5FC108"), "Cardholder Facial Image", pin_protected=True),
+    PivObject("bitg", from_hex("7F61"), "Biometric Information Templates Group"),
+]
+
+OBJECTS_BY_NAME: dict[str, PivObject] = {o.name: o for o in PIV_OBJECTS}
+
+
+def object_by_name(name: str) -> PivObject | None:
+    return OBJECTS_BY_NAME.get(name.lower())
+
+
+def get_data_apdu(oid: bytes) -> APDU:
+    """Build a GET DATA APDU for the given object identifier."""
+    tag_list = bytes([0x5C, len(oid)]) + oid
+    return APDU(0x00, c.INS_GET_DATA, 0x3F, 0xFF, data=tag_list, le=256)
+
+
+def unwrap(oid: bytes, data: bytes) -> bytes:
+    """Strip the outer tag-0x53 wrapper for standard objects; pass discovery through."""
+    if oid == bytes([TAG_DISCOVERY]):
+        return data
+    try:
+        tlvs = tlv.parse(data)
+    except ValueError:
+        return data
+    node = tlv.find(tlvs, TAG_DATA)
+    return node.value if node is not None else data
+
+
+def extract_certificate(object_value: bytes) -> bytes | None:
+    """Pull the DER certificate out of a PIV certificate container (tag 0x70),
+    decompressing it if the CertInfo (tag 0x71) flags gzip. ``object_value`` is the
+    already-unwrapped object content."""
+    try:
+        nodes = tlv.parse(object_value)
+    except ValueError:
+        return None
+    # Look only at the container's own top-level TLVs. tlv.find descends depth-first,
+    # and tag 0x70 is constructed, so a find() for 0x71 could match a node *inside*
+    # the certificate's parsed DER and read the wrong gzip flag.
+    cert = next((n for n in nodes if n.tag == TAG_CERT), None)
+    if cert is None:
+        return None
+    der = cert.value
+    info = next((n for n in nodes if n.tag == TAG_CERTINFO), None)
+    if info is not None and info.value and (info.value[0] & 0x01):
+        with contextlib.suppress(Exception):
+            der = gzip.decompress(der)
+    return der
+
+
+def wrap_certificate(der: bytes, *, compressed: bool = False) -> bytes:
+    """Build a PIV certificate container value: 70 <cert> 71 01 <info> FE 00."""
+    info = 0x01 if compressed else 0x00
+    return tlv.build(TAG_CERT, der) + tlv.build(TAG_CERTINFO, bytes([info])) + tlv.build(0xFE, b"")

cryptnox_id_cli/applets/piv/perso.py

@@ -0,0 +1,138 @@
+"""PIV personalization wire grammar: set verifier (PIN/PUK) values, on-card key
+generation, and writing data objects.
+
+CHANGE REFERENCE DATA ADMIN (INS 24), GENERATE ASYMMETRIC KEYPAIR (INS 47) and
+PUT DATA (INS DB) per SP 800-73 / the applet's perso-grammar doc. The exact
+CHANGE-REF-DATA value layout is marked "to verify" in that doc, so it is
+validated against the live card.
+"""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec, rsa
+
+from cryptnox_id_cli.transport.apdu import APDU
+from cryptnox_id_cli.util import tlv
+
+INS_CHANGE_REFERENCE_DATA = 0x24
+INS_GENERATE_ASYMMETRIC = 0x47
+INS_PUT_DATA = 0xDB
+
+P1_PIN_VALUE = 0xFF  # CHANGE REF DATA ADMIN P1 for a PIN/PUK reference (vs a key mechanism)
+
+TAG_GENERATE_REQUEST = 0xAC
+TAG_MECHANISM = 0x80
+TAG_PUBKEY_TEMPLATE = 0x7F49
+TAG_RSA_MODULUS = 0x81
+TAG_RSA_EXPONENT = 0x82
+TAG_ECC_POINT = 0x86
+
+TAG_DATA = 0x53
+TAG_TAG_LIST = 0x5C
+TAG_DISCOVERY = 0x7E  # the one PIV object written (and read) bare, never 53-wrapped
+
+# Curves by mechanism id.
+_EC_CURVES = {0x11: ec.SECP256R1, 0x14: ec.SECP384R1}
+
+# Asymmetric algorithm name -> mechanism id (those this applet supports).
+ALGORITHMS = {"ECCP256": 0x11, "ECCP384": 0x14, "RSA2048": 0x07, "RSA3072": 0x05}
+
+
+def pad_pin(value: bytes, length: int = 8) -> bytes:
+    """PIV PIN/PUK values are padded to 8 bytes with 0xFF."""
+    if len(value) > length:
+        raise ValueError(f"PIN/PUK value exceeds {length} bytes")
+    return bytes(value) + b"\xff" * (length - len(value))
+
+
+def set_verifier_value_apdu(ref: int, padded_value: bytes) -> APDU:
+    """CHANGE REFERENCE DATA ADMIN to set a PIN/PUK value (P1=0xFF, P2=ref).
+
+    Wrapped by the SCP03 layer (admin). ``padded_value`` should already be padded.
+    """
+    return APDU(0x00, INS_CHANGE_REFERENCE_DATA, P1_PIN_VALUE, ref, data=padded_value)
+
+
+def generate_keypair_apdu(slot: int, mechanism: int) -> APDU:
+    """GENERATE ASYMMETRIC KEYPAIR: request AC{80 mechanism} for the given slot."""
+    request = tlv.build_constructed(
+        TAG_GENERATE_REQUEST, tlv.build(TAG_MECHANISM, bytes([mechanism]))
+    )
+    return APDU(0x00, INS_GENERATE_ASYMMETRIC, 0x00, slot, data=request, le=256)
+
+
+def parse_public_key(mechanism: int, response: bytes):
+    """Parse the 7F49 public-key template from a GENERATE response into a
+    cryptography public-key object (EC or RSA)."""
+    nodes = tlv.parse(response)
+    template = tlv.find(nodes, TAG_PUBKEY_TEMPLATE)
+    scope = template.children if (template and template.children) else nodes
+    if mechanism in _EC_CURVES:
+        point = tlv.find(scope, TAG_ECC_POINT)
+        if point is None:
+            raise ValueError("no EC point (tag 86) in GENERATE response")
+        curve = _EC_CURVES[mechanism]()
+        return ec.EllipticCurvePublicKey.from_encoded_point(curve, point.value)
+    modulus = tlv.find(scope, TAG_RSA_MODULUS)
+    exponent = tlv.find(scope, TAG_RSA_EXPONENT)
+    if modulus is None or exponent is None:
+        raise ValueError("no RSA modulus/exponent (tags 81/82) in GENERATE response")
+    n = int.from_bytes(modulus.value, "big")
+    e = int.from_bytes(exponent.value, "big")
+    return rsa.RSAPublicNumbers(e, n).public_key()
+
+
+def public_key_pem(public_key) -> bytes:
+    return public_key.public_bytes(
+        serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo
+    )
+
+
+def put_data_body(oid: bytes, object_data: bytes) -> bytes:
+    """The PUT DATA command body: 5C{oid} 53{object_data} for standard objects.
+
+    The Discovery Object is the documented exception (SP 800-73-4): it travels as the
+    bare 7E TLV itself, no tag list and no 53 wrapper, and the applet's PUT DATA has a
+    dedicated branch keyed on the first CDATA byte being 7E. Wrapping it like a
+    standard object makes the applet store and echo the wrapper, producing a malformed
+    object on the wire - the read side (objects.unwrap) has always special-cased 7E;
+    this is the matching write-side case.
+    """
+    if oid == bytes([TAG_DISCOVERY]):
+        return object_data
+    return tlv.build(TAG_TAG_LIST, oid) + tlv.build(TAG_DATA, object_data)
+
+
+def put_data_apdu(oid: bytes, object_data: bytes) -> APDU:
+    """PUT DATA (standard): write a data object's content into a container (single APDU)."""
+    return APDU(0x00, INS_PUT_DATA, 0x3F, 0xFF, data=put_data_body(oid, object_data))
+
+
+INS_GENERAL_AUTHENTICATE = 0x87
+TAG_DYNAMIC_AUTH = 0x7C
+TAG_AUTH_CHALLENGE = 0x81
+TAG_AUTH_RESPONSE = 0x82
+
+
+def general_authenticate_sign_apdu(slot: int, mechanism: int, digest: bytes) -> APDU:
+    """GENERAL AUTHENTICATE to sign a pre-computed digest with the slot's key.
+
+    Request: 7C { 82 (empty response placeholder), 81 <digest> }.
+    Response: 7C { 82 <signature> }. Requires the slot's access (PIN) to be met.
+    """
+    body = tlv.build_constructed(
+        TAG_DYNAMIC_AUTH, tlv.build(TAG_AUTH_RESPONSE, b"") + tlv.build(TAG_AUTH_CHALLENGE, digest)
+    )
+    return APDU(0x00, INS_GENERAL_AUTHENTICATE, mechanism, slot, data=body, le=256)
+
+
+def parse_sign_response(response: bytes) -> bytes:
+    """Extract the signature (7C → 82) from a GENERAL AUTHENTICATE response."""
+    nodes = tlv.parse(response)
+    template = tlv.find(nodes, TAG_DYNAMIC_AUTH)
+    scope = template.children if (template and template.children) else nodes
+    sig = tlv.find(scope, TAG_AUTH_RESPONSE)
+    if sig is None:
+        raise ValueError("no signature (tag 82) in GENERAL AUTHENTICATE response")
+    return sig.value