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

cryptnox_id_cli/transport/__init__.py

@@ -0,0 +1,28 @@
+"""PC/SC transport: APDU framing, reader selection, status-word decoding."""
+
+from cryptnox_id_cli.transport.apdu import APDU, Response
+from cryptnox_id_cli.transport.errors import (
+    AppletNotFoundError,
+    CardAccessDeniedError,
+    CryptnoxError,
+    NoCardError,
+    NoReadersError,
+    ReaderNotFoundError,
+    StatusWordError,
+    TransportError,
+    describe_sw,
+)
+
+__all__ = [
+    "APDU",
+    "Response",
+    "AppletNotFoundError",
+    "CardAccessDeniedError",
+    "CryptnoxError",
+    "NoCardError",
+    "NoReadersError",
+    "ReaderNotFoundError",
+    "StatusWordError",
+    "TransportError",
+    "describe_sw",
+]

cryptnox_id_cli/transport/apdu.py

@@ -0,0 +1,72 @@
+"""APDU command encoding and response wrapping (ISO 7816-4, short + extended)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class APDU:
+    """A command APDU. ``le`` is the expected response length; use 256 for the
+    short-form ``0x00`` ("up to 256 bytes")."""
+
+    cla: int
+    ins: int
+    p1: int
+    p2: int
+    data: bytes = b""
+    le: int | None = None
+
+    def to_bytes(self) -> bytes:
+        header = bytes((self.cla & 0xFF, self.ins & 0xFF, self.p1 & 0xFF, self.p2 & 0xFF))
+        data = bytes(self.data)
+        le = self.le
+        extended = len(data) > 0xFF or (le is not None and le > 256)
+
+        if not data:
+            if le is None:  # case 1
+                return header
+            # case 2 (Le only)
+            if not extended:
+                return header + bytes((le & 0xFF if le != 256 else 0x00,))
+            return header + b"\x00" + (le & 0xFFFF if le != 65536 else 0).to_bytes(2, "big")
+
+        if not extended:  # case 3 / 4 short
+            out = header + bytes((len(data),)) + data
+            if le is not None:
+                out += bytes((le & 0xFF if le != 256 else 0x00,))
+            return out
+
+        out = header + b"\x00" + len(data).to_bytes(2, "big") + data  # case 3 / 4 extended
+        if le is not None:
+            out += (le & 0xFFFF if le != 65536 else 0).to_bytes(2, "big")
+        return out
+
+    def to_list(self) -> list[int]:
+        return list(self.to_bytes())
+
+    def header_hex(self) -> str:
+        return bytes((self.cla, self.ins, self.p1, self.p2)).hex().upper()
+
+
+@dataclass(frozen=True)
+class Response:
+    """A response APDU: payload plus the two status bytes."""
+
+    data: bytes
+    sw1: int
+    sw2: int
+
+    @property
+    def sw(self) -> int:
+        return ((self.sw1 & 0xFF) << 8) | (self.sw2 & 0xFF)
+
+    @property
+    def ok(self) -> bool:
+        return self.sw == 0x9000
+
+    def sw_hex(self) -> str:
+        return f"{self.sw1:02X}{self.sw2:02X}"
+
+    def data_hex(self) -> str:
+        return self.data.hex().upper()

cryptnox_id_cli/transport/elevation.py

@@ -0,0 +1,165 @@
+"""Windows elevation detection and the FIDO/SCARD_E_NO_ACCESS message.
+
+On Windows, selecting the FIDO CTAP AID from a non-elevated process is refused by
+the resource manager with ``SCARD_E_NO_ACCESS`` (0x80100027). We detect this so the
+``fido``/``doctor`` commands can print actionable guidance instead of a raw error.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+SCARD_E_NO_ACCESS = 0x80100027
+
+# The reason FIDO2 needs elevation - surfaced to the user, not just the bare rule.
+FIDO_REQUIREMENT = (
+    "FIDO2 needs an Administrator terminal on Windows because the OS reserves direct "
+    "PC/SC access to the FIDO2/CTAP applet for the WebAuthn platform API and blocks "
+    "non-elevated processes (SCARD_E_NO_ACCESS)."
+)
+
+FIDO_WINDOWS_MESSAGE = (
+    "FIDO2 access was blocked by Windows.\n"
+    "Why: the OS reserves direct PC/SC access to the FIDO2/CTAP AID for the WebAuthn "
+    "platform API and denies non-elevated processes (SCARD_E_NO_ACCESS 0x80100027).\n"
+    "Fix: run this command from an Administrator terminal - the CLI can relaunch itself "
+    "elevated when you confirm - or use Android/NFC tooling."
+)
+
+
+def is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
+def is_elevated() -> bool | None:
+    """True/False if determinable, else None (unknown platform/error)."""
+    if is_windows():
+        try:
+            import ctypes
+
+            shell32 = getattr(ctypes, "windll").shell32  # noqa: B009 (windll is Windows-only)
+            return bool(shell32.IsUserAnAdmin())
+        except Exception:
+            return None
+    try:
+        import os
+
+        geteuid = getattr(os, "geteuid", None)  # POSIX-only
+        return geteuid() == 0 if geteuid is not None else None
+    except OSError:
+        return None
+
+
+def fido_elevation_status() -> tuple[str, str]:
+    """Describe the FIDO elevation requirement for the *current* process.
+
+    Returns ``(severity, message)`` where severity is ``"ok"`` (requirement met or
+    not applicable), ``"warn"`` (requirement not met - action needed), or ``"note"``
+    (requirement applies but elevation could not be confirmed). An empty message
+    means there is nothing to show (non-Windows).
+    """
+    if not is_windows():
+        return ("ok", "")
+    elev = is_elevated()
+    if elev is True:
+        return ("ok", f"{FIDO_REQUIREMENT} This terminal is elevated.")
+    if elev is False:
+        return (
+            "warn",
+            f"{FIDO_REQUIREMENT} This process is NOT elevated, so the call will fail; "
+            "re-run from an Administrator terminal.",
+        )
+    return ("note", f"{FIDO_REQUIREMENT} Could not confirm this process is elevated.")
+
+
+def relaunch_command() -> tuple[str, list[str], list[str]]:
+    """The (program, prefix, user_args) needed to re-invoke this exact CLI command.
+
+    ``prefix`` is any interpreter prefix (``-m cryptnox_id_cli``) and ``user_args``
+    is the original ``sys.argv`` tail. Splitting them lets the caller inject *root*
+    options (which click requires BEFORE the subcommand) in the right position.
+    Handles both the PyInstaller one-file build (``sys.frozen``) and a module run.
+    """
+    if getattr(sys, "frozen", False):
+        return sys.executable, [], list(sys.argv[1:])
+    return sys.executable, ["-m", "cryptnox_id_cli"], list(sys.argv[1:])
+
+
+# Distinguishes "user clicked No on the UAC prompt" from a real failure.
+ERROR_CANCELLED = 1223
+
+
+def relaunch_elevated(extra_args: list[str]) -> int | None:
+    """Re-launch the current command elevated via a Windows UAC prompt and wait.
+
+    ``extra_args`` are root-level options injected BEFORE the subcommand (e.g. a
+    result-capture flag). Returns the elevated child's exit code, ``None`` if
+    elevation could not be started (non-Windows, the user declined UAC, or an error).
+    """
+    if not is_windows():
+        return None
+    import ctypes
+    import ctypes.wintypes as wintypes
+
+    program, prefix, user_args = relaunch_command()
+    params = subprocess.list2cmdline([*prefix, *extra_args, *user_args])
+
+    class _SHELLEXECUTEINFOW(ctypes.Structure):
+        _fields_ = [
+            ("cbSize", wintypes.DWORD),
+            ("fMask", ctypes.c_ulong),
+            ("hwnd", wintypes.HWND),
+            ("lpVerb", wintypes.LPCWSTR),
+            ("lpFile", wintypes.LPCWSTR),
+            ("lpParameters", wintypes.LPCWSTR),
+            ("lpDirectory", wintypes.LPCWSTR),
+            ("nShow", ctypes.c_int),
+            ("hInstApp", wintypes.HINSTANCE),
+            ("lpIDList", ctypes.c_void_p),
+            ("lpClass", wintypes.LPCWSTR),
+            ("hkeyClass", wintypes.HKEY),
+            ("dwHotKey", wintypes.DWORD),
+            ("hIcon", wintypes.HANDLE),
+            ("hProcess", wintypes.HANDLE),
+        ]
+
+    see_mask_nocloseprocess = 0x00000040
+    sw_hide = 0
+    infinite = 0xFFFFFFFF
+
+    shell32 = getattr(ctypes, "windll").shell32  # noqa: B009 (windll is Windows-only)
+    kernel32 = getattr(ctypes, "windll").kernel32  # noqa: B009
+
+    sei = _SHELLEXECUTEINFOW()
+    sei.cbSize = ctypes.sizeof(sei)
+    sei.fMask = see_mask_nocloseprocess
+    sei.lpVerb = "runas"
+    sei.lpFile = program
+    sei.lpParameters = params
+    sei.nShow = sw_hide
+
+    if not shell32.ShellExecuteExW(ctypes.byref(sei)) or not sei.hProcess:
+        return None  # declined UAC (GetLastError == ERROR_CANCELLED) or failed to start
+
+    try:
+        kernel32.WaitForSingleObject(sei.hProcess, infinite)
+        code = wintypes.DWORD()
+        kernel32.GetExitCodeProcess(sei.hProcess, ctypes.byref(code))
+        return int(code.value)
+    finally:
+        kernel32.CloseHandle(sei.hProcess)
+
+
+def looks_like_no_access(exc: BaseException) -> bool:
+    """Heuristically detect the Windows no-access block from a pyscard exception."""
+    hr = getattr(exc, "hresult", None)
+    if isinstance(hr, int) and (hr & 0xFFFFFFFF) == SCARD_E_NO_ACCESS:
+        return True
+    s = str(exc).lower()
+    return (
+        "0x80100027" in s
+        or "scard_e_no_access" in s
+        or "access is denied" in s
+        or "access denied" in s
+    )

cryptnox_id_cli/transport/errors.py

@@ -0,0 +1,185 @@
+"""Exception hierarchy and friendly ISO 7816 status-word decoding.
+
+Every status word is mapped to a plain-language message plus the raw code, so the
+CLI never shows a bare ``SW=6982``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class CryptnoxError(Exception):
+    """Base class for all errors surfaced by the CLI's error funnel."""
+
+    exit_code = 1
+    #: short machine token, e.g. "card_access_denied"
+    code = "error"
+
+    def to_dict(self) -> dict[str, object]:
+        return {"error": self.code, "message": str(self)}
+
+
+class TransportError(CryptnoxError):
+    code = "transport_error"
+
+
+class NoReadersError(TransportError):
+    code = "no_readers"
+    exit_code = 3
+
+
+class ReaderNotFoundError(TransportError):
+    code = "reader_not_found"
+    exit_code = 3
+
+
+class NoCardError(TransportError):
+    code = "no_card"
+    exit_code = 3
+
+
+class CardAccessDeniedError(TransportError):
+    """PC/SC refused the transmit (e.g. Windows blocking the FIDO CTAP AID)."""
+
+    code = "card_access_denied"
+    exit_code = 4
+
+    def __init__(self, message: str, *, hresult: int | None = None) -> None:
+        super().__init__(message)
+        self.hresult = hresult
+
+
+class AppletNotFoundError(CryptnoxError):
+    code = "applet_not_found"
+    exit_code = 5
+
+
+class Scp03Error(CryptnoxError):
+    """SCP03 secure-channel failure (wrong keys, bad cryptogram, MAC error)."""
+
+    code = "scp03_error"
+    exit_code = 7
+
+
+class Scp02Error(CryptnoxError):
+    """SCP02 secure-channel failure (wrong keys, bad cryptogram, MAC error)."""
+
+    code = "scp02_error"
+    exit_code = 7
+
+
+@dataclass(frozen=True)
+class SWInfo:
+    sw: int
+    name: str
+    message: str
+    ok: bool = False
+    more_data: int | None = None  # 61xx -> bytes still available
+    wrong_le: int | None = None  # 6Cxx -> correct Le
+    retries: int | None = None  # 63Cx -> remaining tries
+
+    def sw_hex(self) -> str:
+        return f"{self.sw:04X}"
+
+
+# Exact status words → (name, friendly message).
+_SW_TABLE: dict[int, tuple[str, str]] = {
+    0x9000: ("OK", "Success."),
+    0x6982: (
+        "SECURITY_STATUS_NOT_SATISFIED",
+        "Security status not satisfied. You probably need to verify the PIN or "
+        "authenticate with the admin key before running this command.",
+    ),
+    0x6983: (
+        "AUTH_METHOD_BLOCKED",
+        "Authentication method blocked. The PIN or PUK is likely blocked.",
+    ),
+    0x6985: (
+        "CONDITIONS_NOT_SATISFIED",
+        "Conditions of use not satisfied. The applet may be in the wrong lifecycle state "
+        "for this command.",
+    ),
+    0x6A80: (
+        "WRONG_DATA",
+        "Incorrect data. Check the command parameters or object format.",
+    ),
+    0x6A81: ("FUNC_NOT_SUPPORTED", "Function not supported by this applet."),
+    0x6A82: (
+        "FILE_NOT_FOUND",
+        "File, object or applet not found. The selected item may not exist on this card.",
+    ),
+    0x6A84: ("NOT_ENOUGH_MEMORY", "Not enough memory on the card for this operation."),
+    0x6A86: ("WRONG_P1P2", "Incorrect P1/P2 parameters."),
+    0x6A88: (
+        "REFERENCE_DATA_NOT_FOUND",
+        "Referenced data not found (e.g. the PIN/key reference is not configured).",
+    ),
+    0x6700: ("WRONG_LENGTH", "Wrong length (Lc/Le)."),
+    0x6D00: ("INS_NOT_SUPPORTED", "Instruction (INS) not supported by this applet."),
+    0x6E00: (
+        "CLA_NOT_SUPPORTED",
+        "Class (CLA) not supported; this function is not reachable over this interface "
+        "(e.g. a contactless-only function on a contact reader).",
+    ),
+    0x6881: ("LOGICAL_CHANNEL_UNSUPPORTED", "Logical channel not supported."),
+    0x6882: ("SM_UNSUPPORTED", "Secure messaging not supported."),
+    0x6999: ("APPLET_SELECT_FAILED", "Applet selection failed or refused."),
+    0x6F00: ("NO_PRECISE_DIAGNOSIS", "Unknown card error (no precise diagnosis)."),
+}
+
+
+def describe_sw(sw1: int, sw2: int) -> SWInfo:
+    """Decode a status word into a friendly :class:`SWInfo`."""
+    sw = ((sw1 & 0xFF) << 8) | (sw2 & 0xFF)
+    if sw == 0x9000:
+        return SWInfo(sw, "OK", "Success.", ok=True)
+    if sw1 == 0x61:
+        return SWInfo(
+            sw, "MORE_DATA", f"{sw2} more byte(s) available (GET RESPONSE).", more_data=sw2
+        )
+    if sw1 == 0x6C:
+        return SWInfo(sw, "WRONG_LE", f"Wrong Le; resend with Le=0x{sw2:02X}.", wrong_le=sw2)
+    if sw1 == 0x63 and (sw2 & 0xF0) == 0xC0:
+        tries = sw2 & 0x0F
+        return SWInfo(
+            sw,
+            "VERIFY_FAILED",
+            f"Verification failed; {tries} attempt(s) remaining.",
+            retries=tries,
+        )
+    if sw == 0x6300:
+        return SWInfo(sw, "VERIFY_FAILED", "Verification failed.")
+    if sw in _SW_TABLE and _SW_TABLE[sw][1]:
+        name, msg = _SW_TABLE[sw]
+        return SWInfo(sw, name, msg)
+    # Family fallbacks.
+    if sw1 == 0x63:
+        return SWInfo(sw, "WARNING", "Operation completed with warning / counter changed.")
+    if sw1 in (0x62, 0x63):
+        return SWInfo(sw, "WARNING", f"Warning (SW={sw:04X}).")
+    if sw1 in (0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x6B, 0x6C, 0x6D, 0x6E, 0x6F):
+        return SWInfo(sw, "ERROR", f"Card returned error SW={sw:04X}.")
+    return SWInfo(sw, "UNKNOWN", f"Unrecognised status word SW={sw:04X}.")
+
+
+class StatusWordError(CryptnoxError):
+    """A command returned a non-success status word."""
+
+    code = "status_word"
+    exit_code = 6
+
+    def __init__(self, sw1: int, sw2: int, *, context: str | None = None) -> None:
+        self.info = describe_sw(sw1, sw2)
+        self.context = context
+        prefix = f"{context}: " if context else ""
+        super().__init__(f"{prefix}{self.info.message} (SW={self.info.sw_hex()})")
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "error": self.code,
+            "message": str(self),
+            "sw": self.info.sw_hex(),
+            "sw_name": self.info.name,
+            "context": self.context,
+        }