✨ add NDEF URL writing functionality for NTAG 424 DNA and NTAG21x tags

Author: shinaji

src/schnee/adapters/backend/contracts.py

@@ -30,3 +30,6 @@ class ProfileBackend(ProfileReaderBackend, Protocol):
 
     def apply_plan(self, plan: ChangePlan) -> Ntag424DnaProfile:
         """Apply a profile change plan."""
+
+    def write_ndef_url(self, url: str) -> None:
+        """Write one URL NDEF record to the current tag."""

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

@@ -20,7 +20,11 @@
     TagInfo,
     TagType,
 )
-from schnee.adapters.ntag.utils import int_to_3bytes_le
+from schnee.adapters.ntag.utils import (
+    build_ndef_url_file_data,
+    build_type2_ndef_url_tlv,
+    int_to_3bytes_le,
+)
 
 from .client import PcscApduClient
 from .reader import PcscConnection, PcscReader, PcscReaderProvider
@@ -59,6 +63,9 @@ class UnsupportedProfileReadError(PcscBackendError):
     class NdefParseError(PcscBackendError):
         """Raised when NDEF data cannot be represented as a profile."""
 
+    class NdefWriteError(PcscBackendError):
+        """Raised when NDEF data cannot be written to the current tag."""
+
     def __init__(self, reader: PcscReader) -> None:
         self.reader = reader
         self.client = PcscApduClient(reader)
@@ -125,6 +132,16 @@ def apply_plan(self, plan: ChangePlan) -> Ntag424DnaProfile:
         msg = "PC/SC profile writes are not implemented yet"
         raise self.UnsupportedPlanError(msg)
 
+    def write_ndef_url(self, url: str) -> None:
+        """Write one URL NDEF record to NTAG 424 DNA or NTAG21x tags."""
+        try:
+            self._select_ntag_application()
+        except CardConnectionException, PcscApduClient.PcscApduClientError:
+            self._write_type2_ndef_url(url)
+            return
+
+        self._write_ntag424_ndef_url(url)
+
     def _read_uid(self) -> str:
         """Read UID using the common PC/SC contactless reader command."""
         response = self.send_apdu(
@@ -177,6 +194,16 @@ def _read_data_file(self, *, file_no: int, offset: int, length: int) -> list[int
             ),
         ).data
 
+    def _write_ntag424_ndef_url(self, url: str) -> None:
+        """Write one URL NDEF record to the NTAG 424 DNA NDEF file."""
+        self.send_apdu(
+            Ntag424ApduPreset.write_data_file(
+                file_no=Ntag424ApduPreset.ndef_file_no,
+                offset=[0x00, 0x00, 0x00],
+                data=build_ndef_url_file_data(url),
+            ),
+        )
+
     def _get_file_settings(self, file_no: int) -> list[int]:
         """Send GetFileSettings for an NTAG 424 DNA file."""
         return self.send_apdu(
@@ -263,6 +290,28 @@ def _read_type2_ndef_memory(self, capacity_bytes: int) -> list[int]:
                 break
         return memory[:capacity_bytes]
 
+    def _write_type2_ndef_url(self, url: str) -> None:
+        """Write one URL NDEF TLV to an NTAG21x/Type 2 Tag."""
+        capacity_bytes = self._read_type2_capacity_bytes()
+        tlv = build_type2_ndef_url_tlv(url)
+        if len(tlv) > capacity_bytes:
+            msg = (
+                f"NDEF URL TLV is {len(tlv)} bytes, "
+                f"but tag capacity is {capacity_bytes} bytes"
+            )
+            raise self.NdefWriteError(msg)
+
+        padded = [*tlv, *([0x00] * (self.type2_page_size - 1))]
+        page_count = (len(tlv) + self.type2_page_size - 1) // self.type2_page_size
+        for page_index in range(page_count):
+            start = page_index * self.type2_page_size
+            self.send_apdu(
+                PcscContactlessApduPreset.update_binary(
+                    page=self.type2_ndef_start_page + page_index,
+                    data=padded[start : start + self.type2_page_size],
+                ),
+            )
+
     @classmethod
     def create_pcsc_backend(cls, reader_name: str | None = None) -> PcscBackend:
         """Create a PC/SC backend adapter."""

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

@@ -20,6 +20,11 @@ def read_binary(*, page: int, length: int) -> CommandAPDU:
         """Build a PC/SC READ BINARY command."""
         return CommandAPDU(cla=0xFF, ins=0xB0, p1=0x00, p2=page, le=length)
 
+    @staticmethod
+    def update_binary(*, page: int, data: list[Byte]) -> CommandAPDU:
+        """Build a PC/SC UPDATE BINARY command."""
+        return CommandAPDU(cla=0xFF, ins=0xD6, p1=0x00, p2=page, data=data)
+
 
 class Ntag424ApduPreset:
     """Factory for NTAG 424 DNA native APDUs wrapped for ISO transport."""

src/schnee/adapters/ntag/core.py

@@ -16,9 +16,9 @@
 from schnee.adapters.ntag.crypt import aes_decrypt, aes_encrypt, xor_bytes
 from schnee.adapters.ntag.utils import (
     Offset,
+    build_ndef_url_file_data,
     calculate_offsets,
     int_to_3bytes_le,
-    wrap_ndef_record,
 )
 from schnee.utils.logger import get_logger
 
@@ -536,18 +536,45 @@ def _change_key_iv(
 
     def configure_sdm_url(self, url: str, *, cmd_ctr: int = 1) -> None:
         """Authenticate, write an NDEF URL, and enable SDM explicitly."""
+        self.write_ndef_url_with_auth(url)
+        self.set_sdm_enabled(enabled=True, url_template=url, cmd_ctr=cmd_ctr)
+
+    def write_ndef_url_with_auth(self, url: str) -> None:
+        """Authenticate and write an NDEF URL to the NTAG 424 DNA NDEF file."""
+        self.connect()
+        self.authenticate()
+        self.write_ndef_url(url_string=url)
+
+    def set_sdm_enabled(
+        self,
+        *,
+        enabled: bool,
+        url_template: str | None = None,
+        cmd_ctr: int = 0,
+    ) -> None:
+        """Authenticate and enable or disable SDM for the NDEF file."""
         self.connect()
         k_ses_auth_enc, k_ses_auth_mac, ti, _iv = self.authenticate()
-        self.write_ndef_url(
-            url_string=url,
-        )
-        offset = calculate_offsets(url)
-        self._enable_sdm(
+        if enabled:
+            if url_template is None:
+                msg = "url_template is required when enabling SDM"
+                raise ValueError(msg)
+            offset = calculate_offsets(url_template)
+            self._change_sdm_settings(
+                session_key_enc=k_ses_auth_enc,
+                session_key_mac=k_ses_auth_mac,
+                ti=ti,
+                cmd_ctr=cmd_ctr,
+                payload=self._build_enable_sdm_payload(offset),
+            )
+            return
+
+        self._change_sdm_settings(
             session_key_enc=k_ses_auth_enc,
             session_key_mac=k_ses_auth_mac,
             ti=ti,
             cmd_ctr=cmd_ctr,
-            offset=offset,
+            payload=self._build_disable_sdm_payload(),
         )
 
     def _apdu_select(self) -> None:
@@ -562,17 +589,12 @@ def write_ndef_url(
         """Write NDEF URL to Tag"""
         _logger.debug("--- Write NDEF Data (URL) ---")
 
-        # 1. URLをNDEFデータに変換
-        ndef_record = wrap_ndef_record(url_string)
-        # ファイル全体のデータ: [Length(2bytes)] + [NDEF Record]
-        file_data = [len(ndef_record) >> 8 & 255, len(ndef_record) & 255, *ndef_record]
-
         _logger.debug("Writing URL: %s", url_string)
         response = self.connection.send_apdu(
             Ntag424ApduPreset.write_data_file(
                 file_no=Ntag424ApduPreset.ndef_file_no,
                 offset=[0x00, 0x00, 0x00],
-                data=file_data,
+                data=build_ndef_url_file_data(url_string),
             ),
         )
         _logger.debug("Response: %s", toHexString(response.data))
@@ -639,29 +661,47 @@ def aes_cbc_encrypt_for_ev2(
         # 3. 暗号化実行
         return cipher.encrypt(padded_data)
 
-    def _enable_sdm(
+    @staticmethod
+    def _build_enable_sdm_payload(offset: Offset) -> list[int]:
+        """Build ChangeFileSettings plaintext payload that enables SDM."""
+        file_option = 0x40
+        access_rights = [0x00, 0xE0]
+        sdm_options = 0xC1
+        sdm_access_rights = [0xF1, 0xE1]
+
+        return [
+            file_option,
+            *access_rights,
+            sdm_options,
+            *sdm_access_rights,
+            *int_to_3bytes_le(offset.uid_offset),
+            *int_to_3bytes_le(offset.counter_offset),
+            *int_to_3bytes_le(offset.mac_input_offset),
+            *int_to_3bytes_le(offset.mac_offset),
+        ]
+
+    @staticmethod
+    def _build_disable_sdm_payload() -> list[int]:
+        """Build ChangeFileSettings plaintext payload that disables SDM."""
+        file_option = 0x00
+        access_rights = [0x00, 0xE0]
+        return [file_option, *access_rights]
+
+    def _change_sdm_settings(
         self,
         session_key_enc: bytes,
         session_key_mac: bytes,
         ti: bytes,
         cmd_ctr: int,
-        offset: Offset,
+        payload: list[int],
     ) -> None:
-        """Disable SDM (ChangeFileSettings)"""
-        _logger.debug("--- Phase 3: ChangeFileSettings (Disable SDM) ---")
+        """Send a protected ChangeFileSettings command for the NDEF file."""
+        _logger.debug("--- ChangeFileSettings (SDM) ---")
+        if not 0 <= cmd_ctr <= COMMAND_COUNTER_MAX:
+            msg = "cmd_ctr must be between 0 and 65535"
+            raise ValueError(msg)
 
-        # 設定値
         file_no = 0x02
-        file_option = 0x40  # SDM OFF (Plain Communication)
-        access_rights = [0x00, 0xE0]  # Read=Free, Write=Key0 (現在の値を維持)
-        sdm_options = 0xC1
-        sdm_access_rights = [0xF1, 0x21]
-
-        # ペイロード組み立て
-        payload = [file_option, *access_rights, sdm_options, *sdm_access_rights]
-        payload += int_to_3bytes_le(offset.uid_offset)  # 33. UID
-        payload += int_to_3bytes_le(offset.mac_offset)  # 7. MacIn
-        payload += int_to_3bytes_le(offset.mac_offset)  # 59. MacOut
 
         iv = [
             0xA5,

src/schnee/adapters/ntag/utils.py

@@ -1,6 +1,9 @@
 from dataclasses import dataclass
 
 NDEF_HEADER_LEN = 7
+TYPE2_NDEF_TLV = 0x03
+TYPE2_TERMINATOR_TLV = 0xFE
+TYPE2_EXTENDED_TLV_LENGTH = 0xFF
 
 
 class PlaceholderNotFoundError(ValueError):
@@ -29,6 +32,27 @@ def wrap_ndef_record(url_string: str) -> list[int]:
     return header + no_prefix + list(url_bytes)
 
 
+def build_ndef_url_file_data(url_string: str) -> list[int]:
+    """Build NTAG 424 NDEF file bytes for one URL record."""
+    ndef_record = wrap_ndef_record(url_string)
+    return [len(ndef_record) >> 8 & 255, len(ndef_record) & 255, *ndef_record]
+
+
+def build_type2_ndef_url_tlv(url_string: str) -> list[int]:
+    """Build Type 2 Tag NDEF TLV bytes for one URL record."""
+    ndef_record = wrap_ndef_record(url_string)
+    if len(ndef_record) < TYPE2_EXTENDED_TLV_LENGTH:
+        return [TYPE2_NDEF_TLV, len(ndef_record), *ndef_record, TYPE2_TERMINATOR_TLV]
+    return [
+        TYPE2_NDEF_TLV,
+        TYPE2_EXTENDED_TLV_LENGTH,
+        len(ndef_record) >> 8 & 255,
+        len(ndef_record) & 255,
+        *ndef_record,
+        TYPE2_TERMINATOR_TLV,
+    ]
+
+
 @dataclass
 class Offset:
     """Offsets for SDM mirror placeholders inside an NDEF URL file."""