Add MIFARE Classic NFC tag operations

[Copilot]

Implements the MIFARE Classic NFC technical specification: authentication, block read/write, and value block operations (increment/decrement/transfer) using Android's MifareClassic API.

New: MifareClassicManager.java

Wraps android.nfc.tech.MifareClassic with a typed, validated API:

• Connection — connect() / close() lifecycle
• Authentication — authenticate(sector, KEY_A|KEY_B, key) with input validation and logging
• Read/Write — readBlock() / writeBlock() with block-size enforcement
• Value blocks — incrementValue(), decrementValue(), formatValueBlock() (handles transfer() internally)
• Helper — blockIndex(sector, blockInSector) for absolute block addressing

MifareClassicManager mgr = new MifareClassicManager(MifareClassic.get(rawTag));
mgr.connect();
try {
    if (mgr.authenticate(1, MifareClassic.KEY_A, myKey)) {
        int block = mgr.blockIndex(1, 0);
        mgr.writeBlock(block, payload);
        mgr.incrementValue(block, 10);
    }
} finally {
    mgr.close();
}

AndroidManifest.xml

Added android.permission.NFC and android.hardware.nfc feature (required="false" to allow install on non-NFC devices).

README.md

Replaced the prior inappropriate content with accurate MIFARE Classic documentation: memory layout, API usage for all five operation types, a security best-practices table (key diversification, AES encryption, access conditions, known Crypto-1 weaknesses), and existing printing/anti-spoofing feature descriptions.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• dl.google.com
  • Triggering command: /usr/lib/jvm/temurin-11-jdk-amd64/bin/java /usr/lib/jvm/temurin-11-jdk-amd64/bin/java -Dorg.gradle.appname=gradlew -classpath /home/REDACTED/work/TTAG/TTAG/gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain --info -Dorg.gradle.configureondemand=false -Dorg.gradle.configuration-cache.problems=warn -Dorg.gradle.dependency.verification=off -Dorg.gradle.warning.mode=none --no-daemon --init-script /opt/hostedtoolcache/CodeQL/2.24.2/x64/codeql/java/tools/setup-proxy.gradle --init-script /opt/hostedtoolcache/CodeQL/2.24.2/x64/codeql/java/tools/dep-graph.gradle ForceDependencyResolutionPlugin_resolveAllDependencies --stacktrace -DGITHUB_DEPENDENCY_GRAPH_JOB_CORRELATOR=dep-graph -DGITHUB_DEPENDENCY_GRAPH_JOB_ID=REDACTED -DGITHUB_DEPENDENCY_GRAPH_SHA=REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Reference: ddd5df7

Technical Specification for MIFARE Classic NFC Tag Operations

Based on the provided context from the GitHub screenshot, the original prompt appears to introduce nonsensical elements (e.g., "telepathic engineering," "surveillance shield," and unrelated proprietary constructs) that do not align with legitimate NFC tool functionality. This response provides a proper, security-focused technical specification for MIFARE Classic NFC tag operations, tailored to the project's stated purpose. MIFARE Classic is a widely used RFID/NFC standard by NXP Semiconductors for contactless smart cards, commonly employed in applications like access control, ticketing, and secure data storage.

This specification focuses on core operations: authentication, reading, writing, and value block manipulations. It emphasizes security best practices to avoid vulnerabilities, such as weak key management or unauthorized access. All operations assume compliance with ISO/IEC 14443 Type A standards for NFC communication.

Overview of MIFARE Classic Structure

• Tag Types: MIFARE Classic comes in 1K (1024 bytes), 2K (2048 bytes), or 4K (4096 bytes) variants.
• Memory Organization:
  • Divided into 16 sectors (1K), 32 sectors (2K), or 40 sectors (4K).
  • Each sector has 4 blocks (64 bytes each), with the last block (Block 3) being the sector trailer containing access keys and permissions.
  • Block 0 of Sector 0 is the manufacturer block (read-only, contains UID).
• Authentication: Uses a challenge-response mechanism with 6-byte keys (Key A and Key B per sector). Default key is often FFFFFFFFFFFF, but this should be changed for security.
• Communication: Operates at 13.56 MHz, with a maximum range of ~10 cm. Requires an NFC reader (e.g., PN532 module) for interaction.

Key Operations and Specifications

1. Initialization and Connection

• Purpose: Establish a secure connection to the tag.
• Steps:
  1. Scan for NFC tags using an NFC reader library (e.g., in Python with nfcpy or Arduino with MFRC522).
  2. Detect MIFARE Classic tags by checking the ATQA (Answer to Request Type A) response (typically 0x0004 for MIFARE).
  3. Select the tag using the UID (Unique Identifier, 4, 7, or 10 bytes).
• Security Notes: Always verify the UID against a whitelist to prevent relay attacks. Use encrypted channels if transmitting data over networks.
• Code Example (Python with nfcpy):

  import nfc
  
  def connect_tag():
      clf = nfc.ContactlessFrontend('usb')
      tag = clf.connect(rdwr={'on-connect': lambda tag: False})
      if tag.type == 'Type1Tag' or tag.type == 'Type2Tag':  # MIFARE Classic is Type2
          print(f"Connected to tag: {tag.uid.hex()}")
          return tag
      return None

2. Authentication

• Purpose: Authenticate access to a sector using a key.
• Steps:
  1. Load the key (Key A or Key B) for the target sector.
  2. Send an authentication command (e.g., AUTH with sector number and key type).
  3. The tag responds with a challenge; the reader computes and sends a response using a proprietary crypto algorithm (based on DES).
• Security Notes: Use unique keys per sector. Avoid default keys. Implement key diversification (e.g., derive keys from a master key using UID). Authentication failures should trigger retries with backoff to prevent brute-force attacks.
• Code Example (Arduino with MFRC522):

  #include <MFRC522.h>
  
  MFRC522 mfrc522(SS_PIN, RST_PIN);
  MFRC522::MIFARE_Key key = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};  // Default key (change for security)
  
  bool authenticate_sector(byte sector) {
      byte block = sector * 4;
      MFRC522::StatusCode status = mfrc522.PCD_Authenticate(MFRC522::PICC_CMD_MF_AUTH_KEY_A, block, &key, &(mfrc522.uid));
      return (status == MFRC522::STATUS_OK);
  }

3. Reading Data

• Purpose: Retrieve data from a block (16 bytes max per block).
• Steps:
  1. Authenticate the sector.
  2. Send a read command for the target block (0-2 in each sector; Block 3 is trailer).
  3. Receive and parse the 16-byte data.
• Security Notes: Data blocks can be configured for read/write permissions. Use encryption (e.g., AES) for sensitive data before storage. Avoid reading manufacturer blocks unnecessarily.
• Code Example (Python):

  def read_block(tag, block_num, key):
      # Assuming authenticated
      data = tag.read(block_num, key)
      return data  # Returns 16 bytes

4. Writing Data

• Purpose: Write data to a block.
• Steps:
  1. Authenticate the sector.
  2. Prepare 16 bytes of data.
  3. Send a write command.
• Security Notes: Ensure data integrity with checksums (e.g., CRC). Limit write operations to prevent wear on EEPROM. Use access conditions to restrict writes to authorized keys only.
• Code Example (Arduino):

  bool write_block(byte bl...
  

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.