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

cryptnox_id_cli/applets/genuine/__init__.py

@@ -0,0 +1,12 @@
+"""Cryptnox Genuineness / attestation applet (RID A0000010, AID A000001000024701).
+
+Read-only client for the on-card attestation applet: SELECT, GET INFO, GET CERT
+(leaf / issuer, free-read even when fused) and ATTEST (sign a host nonce with the
+on-card device key). These are the KDF-free genuineness checks — they need no ISD /
+PIV-SSD secret, so this tool can run them without the factory HSM. See
+``docs/genuineness.md``.
+"""
+
+from cryptnox_id_cli.applets.genuine.genuine import GenuinenessApplet, GenuinenessInfo
+
+__all__ = ["GenuinenessApplet", "GenuinenessInfo"]

cryptnox_id_cli/applets/genuine/constants.py

@@ -0,0 +1,32 @@
+"""Constants for the Cryptnox Genuineness / attestation applet.
+
+Values mirror the factory tool (``genuineness_tools/factory_perso.py``): Cryptnox
+RID ``A0000010``, applet instance AID ``A000001000024701``. The applet is
+**contact-only** (enforced on-card), so it does not answer over a contactless
+interface — SELECT there returns 6A82.
+"""
+
+from __future__ import annotations
+
+# Applet instance AID and package AID (RID A0000010 = Cryptnox).
+GENUINE_AID = bytes.fromhex("A000001000024701")
+GENUINE_PKG = bytes.fromhex("A0000010000247")
+
+# Instruction bytes (CLA 0x80). GET INFO / GET CERT / ATTEST are open (no-auth)
+# reads; GENERATE / PUT CERT / LOCK are factory-only over an SCP02 C-MAC channel
+# and are intentionally NOT exposed by this read-only CLI.
+INS_GET_INFO = 0x01
+INS_GET_CERT = 0x02
+INS_ATTEST = 0x04
+INS_GENERATE = 0x10  # factory only (not used here)
+INS_PUT_CERT = 0x12  # factory only (not used here)
+INS_LOCK = 0x1E  # factory only (not used here)
+
+# GET CERT P1 selectors.
+CERT_LEAF = 0x00  # the on-card device leaf (signed by the Cryptnox Genuineness CA)
+CERT_INTERMEDIATE = 0x01  # the issuer cert stored alongside the leaf
+
+# ATTEST domain-separation label. The card returns ECDSA(SHA-256) over LABEL||nonce
+# with the device private key; the host verifies it against the leaf's public key.
+ATTEST_LABEL = b"CRYPTNOX-GENUINE-v1"
+ATTEST_NONCE_LEN = 32

cryptnox_id_cli/applets/genuine/genuine.py

@@ -0,0 +1,85 @@
+"""Read-only client for the Cryptnox Genuineness / attestation applet."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cryptnox_id_cli.applets.genuine import constants as c
+from cryptnox_id_cli.transport.apdu import APDU
+from cryptnox_id_cli.transport.errors import AppletNotFoundError, StatusWordError
+from cryptnox_id_cli.transport.pcsc import CardSession
+
+
+@dataclass
+class GenuinenessInfo:
+    """The 4-byte GET INFO blob, kept raw (the applet's field layout is not
+    documented here — we report what the card returns and never guess a verdict
+    from it)."""
+
+    raw: bytes
+
+    @property
+    def hex(self) -> str:
+        return self.raw.hex().upper()
+
+    def to_dict(self) -> dict[str, object]:
+        return {"raw": self.hex}
+
+
+class GenuinenessApplet:
+    def __init__(self, session: CardSession) -> None:
+        self.session = session
+
+    # -- selection ---------------------------------------------------------- #
+    def select(self) -> None:
+        """SELECT the applet. Raises AppletNotFoundError on 6A82 (also returned on a
+        contactless interface, where this contact-only applet does not answer)."""
+        resp = self.session.transmit(
+            APDU(0x00, 0xA4, 0x04, 0x00, data=c.GENUINE_AID, le=256), context="SELECT GENUINE"
+        )
+        # Same multi-applet quirk as PIV: the first case-4 ISO SELECT after a DESFire
+        # native session is rejected with 6700; retry once as case-3 (no Le).
+        if resp.sw == 0x6700:
+            resp = self.session.transmit(
+                APDU(0x00, 0xA4, 0x04, 0x00, data=c.GENUINE_AID), context="SELECT GENUINE (no Le)"
+            )
+        # 6A82 = AID not found (card manager). 6D00 = INS A4 not supported by whatever
+        # applet happens to be selected (e.g. U2F left selected by a preceding FIDO probe):
+        # the genuineness AID is not selectable there, indistinguishable from absent. A real
+        # genuineness applet answers its own SELECT with 9000, so neither can be a present one.
+        if resp.sw in (0x6A82, 0x6D00):
+            raise AppletNotFoundError("Genuineness applet not found on this card/interface.")
+        if not resp.ok:
+            raise StatusWordError(resp.sw1, resp.sw2, context="SELECT GENUINE")
+
+    def try_select(self) -> bool:
+        try:
+            self.select()
+            return True
+        except AppletNotFoundError:
+            return False
+
+    # -- open (no-auth) reads ----------------------------------------------- #
+    def get_info(self) -> GenuinenessInfo | None:
+        resp = self.session.transmit(
+            APDU(0x80, c.INS_GET_INFO, 0x00, 0x00, le=256), context="GENUINE GET INFO"
+        )
+        return GenuinenessInfo(resp.data) if resp.ok else None
+
+    def get_cert(self, which: int = c.CERT_LEAF) -> bytes | None:
+        """Read a stored DER certificate (CERT_LEAF / CERT_INTERMEDIATE). Free-read —
+        works even on a fused card. Returns None when absent or unreadable."""
+        resp = self.session.transmit(
+            APDU(0x80, c.INS_GET_CERT, which, 0x00, le=65536), context="GENUINE GET CERT"
+        )
+        return resp.data if (resp.ok and resp.data) else None
+
+    def attest(self, nonce: bytes) -> bytes:
+        """ATTEST a host nonce: the card returns ECDSA(SHA-256) over
+        ``ATTEST_LABEL || nonce`` signed by the on-card device private key."""
+        resp = self.session.transmit(
+            APDU(0x80, c.INS_ATTEST, 0x00, 0x00, data=nonce), context="GENUINE ATTEST"
+        )
+        if not resp.ok:
+            raise StatusWordError(resp.sw1, resp.sw2, context="GENUINE ATTEST")
+        return resp.data

cryptnox_id_cli/applets/genuine/verify.py

@@ -0,0 +1,150 @@
+"""Offline verification of the genuineness applet's attestation.
+
+Two independent, KDF-free checks (neither needs the ISD / PIV-SSD secret, so this
+tool can run both without the factory HSM):
+
+* **proof of possession** — the card ATTESTs a fresh host nonce; the returned ECDSA
+  signature is verified against the on-card leaf's public key. This proves the card
+  physically holds the device private key *right now* (a copied certificate cannot
+  fake it).
+* **certificate chain** — the leaf chains ``leaf -> Genuineness CA -> ... -> pinned
+  Cryptnox root`` using the pinned trust anchors (:mod:`cryptnox_id_cli.trust`).
+  Without a pinned root this reports "cannot verify" — it never silently passes.
+
+What this does NOT do: the ISD-KDF and PIV-SSD-KVN2 genuineness methods, which
+require the per-card HSM-derived secret keys. Those are out of scope for a tool with
+no KDF access; absence of that check is stated in the result, not hidden.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from cryptography import x509
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from cryptnox_id_cli.applets.genuine import constants as c
+from cryptnox_id_cli.crypto.attestation import AttestationResult, verify_attestation_chain
+
+
+@dataclass
+class GenuinenessResult:
+    """Outcome of the read-only genuineness verification — JSON-friendly."""
+
+    attested: bool  # card produced a signature that verifies against its leaf key
+    attest_detail: str
+    chain: AttestationResult | None  # None if no leaf cert was available to chain
+    leaf_subject: str | None = None
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def genuine(self) -> bool:
+        """Genuine iff the card proved possession AND the chain anchored at a pinned
+        Cryptnox root. Proof-of-possession alone is necessary but not sufficient."""
+        return self.attested and bool(self.chain and self.chain.verified)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "genuine": self.genuine,
+            "proof_of_possession": self.attested,
+            "proof_detail": self.attest_detail,
+            "leaf_subject": self.leaf_subject,
+            "chain": self.chain.to_dict() if self.chain else None,
+            "notes": self.notes,
+        }
+
+
+def verify_attestation_signature(leaf_der: bytes, nonce: bytes, signature: bytes) -> bool:
+    """True iff ``signature`` is a valid ECDSA(SHA-256) over ``ATTEST_LABEL || nonce``
+    under the leaf certificate's public key."""
+    leaf = x509.load_der_x509_certificate(leaf_der)
+    pub = leaf.public_key()
+    if not isinstance(pub, ec.EllipticCurvePublicKey):
+        return False
+    try:
+        pub.verify(signature, c.ATTEST_LABEL + nonce, ec.ECDSA(hashes.SHA256()))
+        return True
+    except InvalidSignature:
+        return False
+
+
+def _order_intermediates(leaf_der: bytes, pool_ders: list[bytes]) -> list[bytes]:
+    """Order a pool of candidate intermediate CAs into a leaf->root chain, following
+    issuer links and dropping duplicates / self-issued roots. ``verify_attestation_chain``
+    needs the intermediates pre-ordered; the pool (card issuer + pinned + --anchors) is
+    not, so we walk it here."""
+    pool = {der: x509.load_der_x509_certificate(der) for der in pool_ders}
+    ordered: list[bytes] = []
+    current = x509.load_der_x509_certificate(leaf_der)
+    used: set[bytes] = set()
+    while True:
+        nxt = next(
+            (
+                der
+                for der, cert in pool.items()
+                if der not in used
+                and cert.subject == current.issuer
+                and cert.subject != cert.issuer  # a self-issued CA is a root, not an intermediate
+            ),
+            None,
+        )
+        if nxt is None:
+            break
+        ordered.append(nxt)
+        used.add(nxt)
+        current = pool[nxt]
+    return ordered
+
+
+def verify_genuineness(
+    *,
+    leaf_der: bytes | None,
+    nonce: bytes,
+    signature: bytes | None,
+    card_issuer_der: bytes | None,
+    roots: list[bytes],
+    intermediates: list[bytes],
+) -> GenuinenessResult:
+    """Combine proof-of-possession + chain verification into one result.
+
+    ``card_issuer_der`` is the issuer cert read off the card (GET CERT intermediate);
+    it joins the pinned ``intermediates`` in a pool that is then ordered leaf->root so
+    the chain can climb even when only the root is pinned. ``roots``/``intermediates``
+    are the pinned anchors from the trust store (plus any the caller loaded)."""
+    notes: list[str] = []
+    if leaf_der is None:
+        return GenuinenessResult(
+            attested=False,
+            attest_detail="no device leaf certificate on card (applet not personalized)",
+            chain=None,
+            notes=["Genuineness applet present but carries no device leaf certificate."],
+        )
+
+    leaf_subject = x509.load_der_x509_certificate(leaf_der).subject.rfc4514_string()
+
+    if signature is None:
+        attested, detail = False, "ATTEST failed (card returned no signature)"
+    elif verify_attestation_signature(leaf_der, nonce, signature):
+        attested = True
+        detail = f"card signed the {len(nonce)}-byte nonce; verifies against leaf key"
+    else:
+        attested, detail = False, "ATTEST signature did NOT verify against the leaf key"
+
+    pool = ([card_issuer_der] if card_issuer_der else []) + list(intermediates)
+    inter = _order_intermediates(leaf_der, pool)
+    chain = verify_attestation_chain(leaf_der, inter, roots)
+    if not roots:
+        notes.append(
+            "No pinned Cryptnox genuineness root bundled - chain cannot be anchored. "
+            "Drop the root PEM into src/cryptnox_id_cli/trust/genuine/ (or pass "
+            "--anchors DIR) to complete the chain."
+        )
+    return GenuinenessResult(
+        attested=attested,
+        attest_detail=detail,
+        chain=chain,
+        leaf_subject=leaf_subject,
+        notes=notes,
+    )

cryptnox_id_cli/applets/mifare/__init__.py

@@ -0,0 +1,10 @@
+"""MIFARE DESFire EV2 support (contactless).
+
+The DESFire function is the card's default (MIFARE) applet, reached over a
+contactless reader with no JavaCard applet selected. Native commands are sent
+ISO-7816-wrapped (CLA 0x90); multi-frame responses chain via 0x91AF.
+"""
+
+from cryptnox_id_cli.applets.mifare.desfire import DesfireError, DesfireTransport
+
+__all__ = ["DesfireError", "DesfireTransport"]

cryptnox_id_cli/applets/mifare/desfire.py

@@ -0,0 +1,353 @@
+"""MIFARE DESFire EV2 native command transport + read-only parsers.
+
+Native commands are sent ISO-7816-wrapped: ``90 <cmd> 00 00 [Lc <data>] 00``.
+Responses end in ``91 <status>``; ``0x91AF`` means "additional frame", fetched
+with ``90 AF 00 00 00`` until the status is final.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cryptnox_id_cli.transport.errors import CryptnoxError
+from cryptnox_id_cli.transport.pcsc import CardSession
+
+# Native command codes.
+CMD_GET_VERSION = 0x60
+CMD_ADDITIONAL_FRAME = 0xAF
+CMD_GET_FREE_MEMORY = 0x6E
+CMD_GET_APPLICATION_IDS = 0x6A
+CMD_GET_DF_NAMES = 0x6D
+CMD_SELECT_APPLICATION = 0x5A
+CMD_GET_FILE_IDS = 0x6F
+CMD_GET_FILE_SETTINGS = 0xF5
+CMD_CHANGE_FILE_SETTINGS = 0x5F
+CMD_GET_KEY_SETTINGS = 0x45
+CMD_CREATE_APPLICATION = 0xCA
+CMD_DELETE_APPLICATION = 0xDA
+CMD_FORMAT_PICC = 0xFC
+CMD_CREATE_STD_DATA_FILE = 0xCD
+CMD_WRITE_DATA = 0x3D
+CMD_READ_DATA = 0xBD
+CMD_CREATE_VALUE_FILE = 0xCC
+CMD_GET_VALUE = 0x6C
+CMD_CREDIT = 0x0C
+CMD_DEBIT = 0xDC
+CMD_COMMIT_TXN = 0xC7
+CMD_ABORT_TXN = 0xA7
+CMD_CREATE_LINEAR_RECORD_FILE = 0xC1
+CMD_CREATE_CYCLIC_RECORD_FILE = 0xC0
+CMD_WRITE_RECORD = 0x3B
+CMD_READ_RECORDS = 0xBB
+CMD_CLEAR_RECORD_FILE = 0xEB
+CMD_CHANGE_KEY = 0xC4
+
+STATUS_OK = 0x00
+STATUS_ADDITIONAL_FRAME = 0xAF
+STATUS_LENGTH_ERROR = 0x7E  # card rejected the command/payload length
+
+_STATUS = {
+    0x00: "OPERATION_OK",
+    0x0C: "NO_CHANGES",
+    0x0E: "OUT_OF_EEPROM_ERROR",
+    0x1C: "ILLEGAL_COMMAND_CODE",
+    0x1E: "INTEGRITY_ERROR",
+    0x40: "NO_SUCH_KEY",
+    0x7E: "LENGTH_ERROR",
+    0x9D: "PERMISSION_DENIED",
+    0x9E: "PARAMETER_ERROR",
+    0xA0: "APPLICATION_NOT_FOUND",
+    0xA1: "APPL_INTEGRITY_ERROR",
+    0xAE: "AUTHENTICATION_ERROR",
+    0xAF: "ADDITIONAL_FRAME",
+    0xBE: "BOUNDARY_ERROR",
+    0xC1: "CARD_INTEGRITY_ERROR",
+    0xCA: "COMMAND_ABORTED",
+    0xCD: "CARD_DISABLED_ERROR",
+    0xCE: "COUNT_ERROR",
+    0xDE: "DUPLICATE_ERROR",
+    0xEE: "EEPROM_ERROR",
+    0xF0: "FILE_NOT_FOUND",
+    0xF1: "FILE_INTEGRITY_ERROR",
+}
+
+
+def status_name(status: int) -> str:
+    return _STATUS.get(status, f"0x{status:02X}")
+
+
+class DesfireError(CryptnoxError):
+    code = "desfire_error"
+    exit_code = 9
+
+    def __init__(self, status: int, context: str | None = None) -> None:
+        self.status = status
+        prefix = f"{context}: " if context else ""
+        super().__init__(f"{prefix}DESFire status {status_name(status)} (0x{status:02X}).")
+
+
+class DesfireNotSelectedError(CryptnoxError):
+    """The card did not answer as a DESFire (MIFARE not the selected default applet)."""
+
+    code = "desfire_not_selected"
+    exit_code = 5
+
+
+class DesfireFrameTooLargeError(CryptnoxError):
+    """A native command would exceed the single short-frame limit (Lc > 255)."""
+
+    code = "desfire_frame_too_large"
+    exit_code = 2
+
+
+@dataclass
+class DesfireVersion:
+    hw_vendor: int
+    hw_type: int
+    hw_subtype: int
+    hw_major: int
+    hw_minor: int
+    hw_storage: int
+    hw_protocol: int
+    sw_vendor: int
+    sw_type: int
+    sw_subtype: int
+    sw_major: int
+    sw_minor: int
+    sw_storage: int
+    sw_protocol: int
+    uid: bytes
+    batch: bytes
+    cw_production: int
+    year_production: int
+
+    @staticmethod
+    def _storage(code: int) -> int:
+        # n>>1 is the exponent; the low bit flags "between this and the next size".
+        return 1 << (code >> 1)
+
+    @property
+    def storage_bytes(self) -> int:
+        return self._storage(self.hw_storage)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "vendor": "NXP" if self.hw_vendor == 0x04 else f"0x{self.hw_vendor:02X}",
+            "hardware_version": f"{self.hw_major}.{self.hw_minor}",
+            "software_version": f"{self.sw_major}.{self.sw_minor}",
+            "storage_bytes": self.storage_bytes,
+            "protocol": f"0x{self.hw_protocol:02X}",
+            "uid": self.uid.hex().upper(),
+            "batch": self.batch.hex().upper(),
+            "production": f"week {self.cw_production:02X}/year {self.year_production:02X}",
+        }
+
+
+def parse_version(data: bytes) -> DesfireVersion:
+    if len(data) < 28:
+        raise ValueError(f"GetVersion response too short ({len(data)} bytes)")
+    return DesfireVersion(
+        hw_vendor=data[0],
+        hw_type=data[1],
+        hw_subtype=data[2],
+        hw_major=data[3],
+        hw_minor=data[4],
+        hw_storage=data[5],
+        hw_protocol=data[6],
+        sw_vendor=data[7],
+        sw_type=data[8],
+        sw_subtype=data[9],
+        sw_major=data[10],
+        sw_minor=data[11],
+        sw_storage=data[12],
+        sw_protocol=data[13],
+        uid=data[14:21],
+        batch=data[21:26],
+        cw_production=data[26],
+        year_production=data[27],
+    )
+
+
+def parse_application_ids(data: bytes) -> list[bytes]:
+    return [data[i : i + 3] for i in range(0, len(data) - 2, 3)]
+
+
+class DesfireTransport:
+    """Sends DESFire native commands and reassembles 0x91AF multi-frame responses."""
+
+    def __init__(self, session: CardSession) -> None:
+        self.session = session
+
+    @staticmethod
+    def _frame(cmd: int, data: bytes = b"") -> bytes:
+        if len(data) > 0xFF:
+            raise DesfireFrameTooLargeError(
+                f"DESFire native frame data is {len(data)} bytes; this transport sends a single "
+                "short frame (Lc <= 255, including any command header and MAC). Chunked / "
+                "multi-frame (0x91AF) writes are not implemented yet."
+            )
+        if data:
+            return bytes([0x90, cmd, 0x00, 0x00, len(data)]) + bytes(data) + b"\x00"
+        return bytes([0x90, cmd, 0x00, 0x00, 0x00])
+
+    def raw_command(
+        self, cmd: int, data: bytes = b"", *, context: str | None = None
+    ) -> tuple[int, bytes]:
+        """Send one native frame; return ``(status, data)`` without following AF."""
+        ctx = context or f"DESFire {cmd:02X}"
+        resp = self.session.transmit(self._frame(cmd, data), context=ctx)
+        if resp.sw1 != 0x91:
+            raise DesfireNotSelectedError(
+                f"{ctx}: card answered SW={resp.sw_hex()} (not a DESFire response). "
+                "Ensure MIFARE is the selected (default) applet - re-tap the card with no "
+                "JavaCard applet selected, on a DESFire-capable contactless reader."
+            )
+        return resp.sw2, resp.data
+
+    def command(self, cmd: int, data: bytes = b"", *, context: str | None = None) -> bytes:
+        """Send a native command and return the accumulated response data (no status)."""
+        ctx = context or f"DESFire {cmd:02X}"
+        status, first = self.raw_command(cmd, data, context=ctx)
+        acc = bytearray(first)
+        while status == STATUS_ADDITIONAL_FRAME:
+            status, more = self.raw_command(CMD_ADDITIONAL_FRAME, context=f"{ctx} (AF)")
+            acc += more
+        if status != STATUS_OK:
+            raise DesfireError(status, context)
+        return bytes(acc)
+
+    # -- read-only operations ---------------------------------------------- #
+    def get_version(self) -> DesfireVersion:
+        return parse_version(self.command(CMD_GET_VERSION, context="GetVersion"))
+
+    def get_free_memory(self) -> int:
+        data = self.command(CMD_GET_FREE_MEMORY, context="GetFreeMemory")
+        return int.from_bytes(data[:3], "little")
+
+    def application_ids(self) -> list[bytes]:
+        return parse_application_ids(
+            self.command(CMD_GET_APPLICATION_IDS, context="GetApplicationIDs")
+        )
+
+    def select_application(self, aid: bytes) -> None:
+        if len(aid) != 3:
+            raise ValueError("DESFire AID must be 3 bytes")
+        self.command(CMD_SELECT_APPLICATION, bytes(aid), context="SelectApplication")
+
+    def file_ids(self) -> list[int]:
+        return list(self.command(CMD_GET_FILE_IDS, context="GetFileIDs"))
+
+    def get_key_settings(self) -> tuple[int, int, int]:
+        """GetKeySettings for the selected application: (settings, key_type_bits, max_keys).
+
+        ``key_type_bits`` is the top two bits of the second byte: 0x00 = DES/2K3DES,
+        0x40 = 3K3DES, 0x80 = AES. Readable without authentication when the settings
+        permit (the factory default does)."""
+        data = self.command(CMD_GET_KEY_SETTINGS, context="GetKeySettings")
+        if len(data) < 2:
+            raise DesfireError(STATUS_OK, "GetKeySettings (short response)")
+        return data[0], data[1] & 0xC0, data[1] & 0x0F
+
+    # -- write operations (plain comm; MACed variants live in ev2.py) ------- #
+    def create_application(
+        self, aid: bytes, *, key_settings: int = 0x0F, num_keys: int = 3, aes: bool = True
+    ) -> None:
+        """CreateApplication. KeySettings2 high bits select AES (0x80)."""
+        if len(aid) != 3:
+            raise ValueError("DESFire AID must be 3 bytes")
+        if not (1 <= num_keys <= 14):
+            raise ValueError("number of keys must be 1..14")
+        ks2 = (0x80 if aes else 0x00) | num_keys
+        self.command(
+            CMD_CREATE_APPLICATION,
+            bytes(aid) + bytes([key_settings, ks2]),
+            context="CreateApplication",
+        )
+
+    def delete_application(self, aid: bytes) -> None:
+        if len(aid) != 3:
+            raise ValueError("DESFire AID must be 3 bytes")
+        self.command(CMD_DELETE_APPLICATION, bytes(aid), context="DeleteApplication")
+
+    def create_std_data_file(
+        self, file_no: int, size: int, *, comm: int = 0x01, access: int = 0xE000, sdm: bool = False
+    ) -> None:
+        """CreateStdDataFile. ``access`` packs Read|Write|ReadWrite|Change nibbles
+        (MSB first); 0xE = free, 0xF = never. Default: free read, key-0 write.
+
+        ``sdm=True`` sets the FileOption SDM bit (0x40) so the file can later carry a
+        Secure Dynamic Messaging config (EV3; SDM must be enabled at creation). The SDM
+        details themselves are applied with ChangeFileSettings - see ev2.change_file_settings."""
+        file_option = (comm & 0x03) | (0x40 if sdm else 0x00)
+        data = (
+            bytes([file_no, file_option])
+            + access.to_bytes(2, "little")
+            + size.to_bytes(3, "little")
+        )
+        self.command(CMD_CREATE_STD_DATA_FILE, data, context="CreateStdDataFile")
+
+    def create_value_file(
+        self,
+        file_no: int,
+        lower: int,
+        upper: int,
+        value: int,
+        *,
+        comm: int = 0x01,
+        access: int = 0x0000,
+        limited_credit: int = 0x00,
+    ) -> None:
+        """CreateValueFile (plain, like CreateStdDataFile). Default access = key-0 for
+        all ops; comm 0x01 = MAC so get/credit/debit go through the EV2 MAC channel."""
+        data = (
+            bytes([file_no, comm])
+            + access.to_bytes(2, "little")
+            + lower.to_bytes(4, "little", signed=True)
+            + upper.to_bytes(4, "little", signed=True)
+            + value.to_bytes(4, "little", signed=True)
+            + bytes([limited_credit])
+        )
+        self.command(CMD_CREATE_VALUE_FILE, data, context="CreateValueFile")
+
+    def create_record_file(
+        self,
+        file_no: int,
+        record_size: int,
+        max_records: int,
+        *,
+        cyclic: bool = False,
+        comm: int = 0x01,
+        access: int = 0x0000,
+    ) -> None:
+        """CreateLinear/CyclicRecordFile (plain). comm 0x01 = MAC for write/read."""
+        cmd = CMD_CREATE_CYCLIC_RECORD_FILE if cyclic else CMD_CREATE_LINEAR_RECORD_FILE
+        data = (
+            bytes([file_no, comm])
+            + access.to_bytes(2, "little")
+            + record_size.to_bytes(3, "little")
+            + max_records.to_bytes(3, "little")
+        )
+        ctx = "CreateCyclicRecordFile" if cyclic else "CreateLinearRecordFile"
+        self.command(cmd, data, context=ctx)
+
+    @staticmethod
+    def value_arg(file_no: int, amount: int) -> bytes:
+        """Credit/Debit argument: file number + signed 4-byte little-endian amount."""
+        return bytes([file_no]) + amount.to_bytes(4, "little", signed=True)
+
+    @staticmethod
+    def data_header(file_no: int, offset: int, length: int) -> bytes:
+        return bytes([file_no]) + offset.to_bytes(3, "little") + length.to_bytes(3, "little")
+
+    def read_data_plain(self, file_no: int, offset: int = 0, length: int = 0) -> bytes:
+        """ReadData in plain communication (free-read files; length 0 = whole file)."""
+        return self.command(
+            CMD_READ_DATA, self.data_header(file_no, offset, length), context="ReadData"
+        )
+
+
+def parse_value(data: bytes) -> int:
+    """A GetValue response payload: a signed 4-byte little-endian integer."""
+    if len(data) < 4:
+        raise ValueError(f"GetValue response too short ({len(data)} bytes)")
+    return int.from_bytes(data[:4], "little", signed=True)