Add NTAG 424 key update and validation support (#5)

Author: shinaji

.pre-commit-config.yaml

@@ -1,9 +1,18 @@
 repos:
   - repo: local
     hooks:
-      - id: nox
-        name: Run Nox
+      - id: nox-pre-commit
+        name: Run Nox pre-commit hook
         entry: uv run nox -s lint type_check --
         language: system
         types: [python]
         pass_filenames: true
+        stages: ["pre-commit"]
+
+      - id: nox-pre-push
+        name: Run Nox pre-push hook
+        entry: uv run nox -s test
+        language: system
+        types: [python]
+        pass_filenames: false
+        stages: ["pre-push"]

pyproject.toml

@@ -66,6 +66,7 @@ target-version = "py314"
 [tool.ruff.lint]
 select = ["ALL"]
 ignore = [
+    "COM812",
     "D100",
     "D104",
     "D107",

src/schnee/adapters/backend/contracts.py

@@ -3,12 +3,22 @@
 from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
+    from schnee.adapters.ntag.apdu import CommandAPDU, ResponseAPDU
     from schnee.adapters.ntag.profile import ChangePlan, Ntag424DnaProfile, NtagProfile
 
 
 @runtime_checkable
 class ProfileReaderBackend(Protocol):
-    """Backend adapter that can read an NTAG profile."""
+    """Backend adapter that can communicate with and read an NTAG profile."""
+
+    def send_apdu(
+        self,
+        apdu: CommandAPDU | list[int],
+        *,
+        check_status: bool = True,
+        ok_statuses: tuple[tuple[int, int], ...] | None = None,
+    ) -> ResponseAPDU:
+        """Transmit an APDU and optionally raise when the status word is not OK."""
 
     def read_profile(self) -> NtagProfile:
         """Read the current tag profile."""

src/schnee/adapters/backend/pcsc/backend.py

@@ -32,16 +32,6 @@
 class PcscBackend:
     """Backend adapter that wraps a PC/SC reader."""
 
-    ntag_application_df_name: ClassVar[list[int]] = [
-        0xD2,
-        0x76,
-        0x00,
-        0x00,
-        0x85,
-        0x01,
-        0x01,
-    ]
-    ndef_file_no: ClassVar[int] = 0x02
     ndef_length_header_size: ClassVar[int] = 2
     ntag424_key_slots: ClassVar[int] = 5
     type2_cc_page: ClassVar[int] = 3
@@ -82,9 +72,19 @@ def connect(self) -> PcscConnection:
         """Connect to the wrapped PC/SC reader."""
         return self.client.connect()
 
-    def send_apdu(self, apdu: CommandAPDU | list[int]) -> ResponseAPDU:
+    def send_apdu(
+        self,
+        apdu: CommandAPDU | list[int],
+        *,
+        check_status: bool = True,
+        ok_statuses: tuple[tuple[int, int], ...] | None = None,
+    ) -> ResponseAPDU:
         """Transmit an APDU through the wrapped PC/SC reader."""
-        return self.client.send_apdu(apdu)
+        return self.client.send_apdu(
+            apdu,
+            check_status=check_status,
+            ok_statuses=ok_statuses,
+        )
 
     def read_profile(self) -> NtagProfile:
         """Read the currently reachable NTAG profile."""
@@ -95,7 +95,7 @@ def read_profile(self) -> NtagProfile:
             return self._read_type2_profile(uid)
 
         file_settings = Ntag424FileSettings.from_response(
-            self._get_file_settings(self.ndef_file_no),
+            self._get_file_settings(Ntag424ApduPreset.ndef_file_no),
         )
         sections = Ntag424ProfileSections.from_parsed_data(
             file_settings=file_settings,
@@ -127,22 +127,23 @@ def apply_plan(self, plan: ChangePlan) -> Ntag424DnaProfile:
 
     def _read_uid(self) -> str:
         """Read UID using the common PC/SC contactless reader command."""
-        response = self.send_apdu(PcscContactlessApduPreset.get_uid())
+        response = self.send_apdu(
+            PcscContactlessApduPreset.get_uid(),
+            check_status=False,
+        )
         if not response.ok:
             msg = f"Unable to read tag UID: status {response.status:#x}"
             raise self.UnsupportedProfileReadError(msg)
         return bytes(response.data).hex().upper()
 
     def _select_ntag_application(self) -> None:
         """Select the NTAG 424 DNA application by DF name."""
-        self.client.send_checked(
-            Ntag424ApduPreset.select_application(self.ntag_application_df_name),
-        )
+        self.send_apdu(Ntag424ApduPreset.select_application())
 
     def _read_ndef_profile(self) -> NdefProfile:
         """Read and parse the NDEF file into profile records."""
         length_data = self._read_data_file(
-            file_no=self.ndef_file_no,
+            file_no=Ntag424ApduPreset.ndef_file_no,
             offset=0,
             length=self.ndef_length_header_size,
         )
@@ -155,7 +156,7 @@ def _read_ndef_profile(self) -> NdefProfile:
             return NdefProfile(present=False)
 
         message = self._read_data_file(
-            file_no=self.ndef_file_no,
+            file_no=Ntag424ApduPreset.ndef_file_no,
             offset=2,
             length=ndef_length,
         )
@@ -168,17 +169,19 @@ def _read_ndef_profile(self) -> NdefProfile:
     def _read_data_file(self, *, file_no: int, offset: int, length: int) -> list[int]:
         """Read bytes from an NTAG 424 DNA data file."""
         offset_bytes = int_to_3bytes_le(offset)
-        return self.client.send_checked(
+        return self.send_apdu(
             Ntag424ApduPreset.read_data_file(
                 file_no=file_no,
                 offset=offset_bytes,
                 length=int_to_3bytes_le(length),
             ),
-        )
+        ).data
 
     def _get_file_settings(self, file_no: int) -> list[int]:
         """Send GetFileSettings for an NTAG 424 DNA file."""
-        return self.client.send_checked(Ntag424ApduPreset.get_file_settings(file_no))
+        return self.send_apdu(
+            Ntag424ApduPreset.get_file_settings(file_no),
+        ).data
 
     def _get_key_versions(self) -> list[int]:
         """Send GetKeyVersion for all NTAG 424 DNA application key slots."""
@@ -188,7 +191,7 @@ def _get_key_versions(self) -> list[int]:
 
     def _get_key_version(self, key_no: int) -> int:
         """Send GetKeyVersion for one NTAG 424 DNA application key."""
-        data = self.client.send_checked(Ntag424ApduPreset.get_key_version(key_no))
+        data = self.send_apdu(Ntag424ApduPreset.get_key_version(key_no)).data
         if len(data) != 1:
             msg = "NTAG 424 DNA key version response must be 1 byte"
             raise self.UnsupportedProfileReadError(msg)
@@ -236,12 +239,12 @@ def _detect_type2_tag_type(self, capacity_bytes: int) -> TagType:
 
     def _read_type2_page(self, page: int) -> list[int]:
         """Read one Type 2 Tag page using the PC/SC READ BINARY command."""
-        data = self.client.send_checked(
+        data = self.send_apdu(
             PcscContactlessApduPreset.read_binary(
                 page=page,
                 length=self.type2_page_size,
             ),
-        )
+        ).data
         if len(data) != self.type2_page_size:
             msg = "Type 2 Tag page reads must return 4 bytes"
             raise self.NdefParseError(msg)

src/schnee/adapters/backend/pcsc/client.py

@@ -44,21 +44,20 @@ def connect(self) -> PcscConnection:
             self.connection.connect()
         return self.connection
 
-    def send_apdu(self, apdu: CommandAPDU | list[int]) -> ResponseAPDU:
-        """Transmit an APDU and return the full response."""
-        command = apdu.to_list() if isinstance(apdu, CommandAPDU) else apdu
-        response, sw1, sw2 = self.connect().transmit(command)
-        return ResponseAPDU(data=response, sw1=sw1, sw2=sw2)
-
-    def send_checked(
+    def send_apdu(
         self,
         apdu: CommandAPDU | list[int],
         *,
+        check_status: bool = True,
         ok_statuses: tuple[tuple[int, int], ...] | None = None,
-    ) -> list[int]:
-        """Transmit an APDU and return data for successful status words."""
-        response = self.send_apdu(apdu)
+    ) -> ResponseAPDU:
+        """Transmit an APDU and optionally raise for unsuccessful status words."""
+        command = apdu.to_list() if isinstance(apdu, CommandAPDU) else apdu
+        response, sw1, sw2 = self.connect().transmit(command)
+        response_apdu = ResponseAPDU(data=response, sw1=sw1, sw2=sw2)
+        if not check_status:
+            return response_apdu
         statuses = self.ok_statuses if ok_statuses is None else ok_statuses
-        if (response.sw1, response.sw2) in statuses:
-            return response.data
-        raise self.ApduStatusError(response.sw1, response.sw2)
+        if (response_apdu.sw1, response_apdu.sw2) in statuses:
+            return response_apdu
+        raise self.ApduStatusError(response_apdu.sw1, response_apdu.sw2)

src/schnee/adapters/ntag/apdu/presets.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import ClassVar
+
 from .base import Byte, CommandAPDU
 
 
@@ -22,10 +24,71 @@ def read_binary(*, page: int, length: int) -> CommandAPDU:
 class Ntag424ApduPreset:
     """Factory for NTAG 424 DNA native APDUs wrapped for ISO transport."""
 
+    application_df_name: ClassVar[list[Byte]] = [
+        0xD2,
+        0x76,
+        0x00,
+        0x00,
+        0x85,
+        0x01,
+        0x01,
+    ]
+    ndef_file_no: ClassVar[int] = 0x02
+
     @staticmethod
-    def select_application(df_name: list[Byte]) -> CommandAPDU:
+    def select_application(
+        df_name: list[Byte] | None = None,
+    ) -> CommandAPDU:
         """Build a SELECT command for the NTAG 424 DNA application DF name."""
-        return CommandAPDU(cla=0x00, ins=0xA4, p1=0x04, p2=0x00, data=df_name)
+        data = Ntag424ApduPreset.application_df_name if df_name is None else df_name
+        return CommandAPDU(
+            cla=0x00,
+            ins=0xA4,
+            p1=0x04,
+            p2=0x00,
+            data=data,
+        )
+
+    @staticmethod
+    def authenticate_ev2_first(key_no: int) -> CommandAPDU:
+        """Build an NTAG 424 DNA AuthenticateEV2First command."""
+        return CommandAPDU(
+            cla=0x90,
+            ins=0x71,
+            p1=0x00,
+            p2=0x00,
+            data=[key_no, 0x00],
+            le=0x00,
+        )
+
+    @staticmethod
+    def additional_frame(data: list[Byte]) -> CommandAPDU:
+        """Build an NTAG 424 DNA AdditionalFrame command."""
+        return CommandAPDU(
+            cla=0x90,
+            ins=0xAF,
+            p1=0x00,
+            p2=0x00,
+            data=data,
+            le=0x00,
+        )
+
+    @staticmethod
+    def change_key(
+        *,
+        key_no: int,
+        encrypted_key_data: list[Byte],
+        mac: list[Byte],
+    ) -> CommandAPDU:
+        """Build an NTAG 424 DNA ChangeKey command."""
+        return CommandAPDU(
+            cla=0x90,
+            ins=0xC4,
+            p1=0x00,
+            p2=0x00,
+            data=[key_no, *encrypted_key_data, *mac],
+            le=0x00,
+        )
 
     @staticmethod
     def read_data_file(
@@ -44,6 +107,28 @@ def read_data_file(
             le=0x00,
         )
 
+    @staticmethod
+    def write_data_file(
+        *,
+        file_no: int,
+        offset: list[Byte],
+        data: list[Byte],
+    ) -> CommandAPDU:
+        """Build an NTAG 424 DNA WriteData command."""
+        length = [
+            len(data) & 0xFF,
+            (len(data) >> 8) & 0xFF,
+            (len(data) >> 16) & 0xFF,
+        ]
+        return CommandAPDU(
+            cla=0x90,
+            ins=0x8D,
+            p1=0x00,
+            p2=0x00,
+            data=[file_no, *offset, *length, *data],
+            le=0x00,
+        )
+
     @staticmethod
     def get_file_settings(file_no: int) -> CommandAPDU:
         """Build an NTAG 424 DNA GetFileSettings command."""