GitHub - jetnoir/ntag424-macos: The first native macOS SDK for NXP NTAG 424 DNA NFC authentication

The first and only native macOS SDK for NXP NTAG 424 DNA NFC tags.

Provides complete EV2First authentication, Secure Dynamic Messaging (SDM), key management, and tag programming via any PC/SC-compatible contactless reader (e.g., ACS ACR1552).

Features

EV2First Authentication — Full 3-phase challenge-response with session key derivation
Secure Dynamic Messaging — Encrypted PICCData + CMAC verification
Key Management — ChangeKey with cross-key support, HMAC-SHA256 key diversification
Tag Programming — WriteData, ChangeFileSettings, SDM configuration
Cryptographic Primitives — AES-CMAC (NIST SP 800-38B), AES-CBC/ECB, CRC32 (JAMCRC)
Self-Testing — Validates against NIST and NXP AN12196 test vectors at startup
Zero Dependencies — Uses only Apple's CommonCrypto and native PC/SC framework
Pure Swift + C — No Objective-C, no third-party libraries

Quick Start

import NTAG424

// Connect to reader
let manager = PCScManager.shared
manager.startMonitoring()

// When tag detected:
let commands = NTAGCommands()

// Select NDEF application
try commands.selectApplication(aid: Data.fromHex("D2760000850101")!)

// Authenticate with Key 0
let (sessionMAC, sessionENC, ti, _, _) = try commands.authenticateEV2First(
    keyNo: 0,
    key: Data(repeating: 0, count: 16) // factory default
)

// Read NDEF URL
let url = try commands.readNDEFURL()
print("Tag URL: \(url)")

// Write NDEF data
var cmdCounter = 0
try commands.writeNDEFData(ndefRecord, sessionMACKey: sessionMAC,
    sessionENCKey: sessionENC, ti: ti, cmdCounter: &cmdCounter)

// Change a key (cross-key change)
try commands.changeKey(newKey: derivedKey, keyNo: 0x02,
    sessionMACKey: sessionMAC, sessionENCKey: sessionENC,
    ti: ti, cmdCounter: &cmdCounter)

// Enable SDM with encrypted PICCData
try commands.enableSDM(encPICCDataOffset: 36, macOffset: 71,
    sdmMetaReadKey: 0x1, sdmFileReadKey: 0x2,
    sessionMACKey: sessionMAC, sessionENCKey: sessionENC,
    ti: ti, cmdCounter: &cmdCounter)

Verification (Server-Side)

import NTAG424

// Parse a tapped URL: ?e=ENCRYPTED&c=CMAC
let metaReadKey = KeyDerivation.derivedMetaReadKey(masterKey: masterKey)
let (uid, counter) = try VerificationService.decryptPICCData(
    encryptedHex: encParam, metaReadKey: metaReadKey
)

let sdmKey = KeyDerivation.derivedSDMKey(masterKey: masterKey, uid: uid)
let expectedCMAC = try VerificationService.computeCMAC(
    sdmKey: sdmKey, uid: uid, counter: counter
)

let isAuthentic = (expectedCMAC == providedCMAC)

Hardware Requirements

macOS 14+ (Sonoma or later)
Any PC/SC-compatible contactless NFC reader:
- ACS ACR1552 (recommended)
- ACS ACR122U
- HID Omnikey 5022/5427
- Any CCID-compliant reader

Architecture

┌──────────────────────┐
│   Your Application   │
├──────────────────────┤
│   NTAG424 SDK        │  ← NTAGCommands, VerificationService
├──────────────────────┤
│   Crypto Layer       │  ← AES-CMAC, HMAC-SHA256, CRC32
├──────────────────────┤
│   PC/SC Bridge       │  ← C bridge to Apple's winscard.h
├──────────────────────┤
│   macOS PC/SC        │  ← Native smart card framework
├──────────────────────┤
│   USB Reader         │  ← CCID driver (built into macOS)
├──────────────────────┤
│   NTAG 424 DNA       │  ← NXP hardware AES-128
└──────────────────────┘

Protocol Details

This SDK implements the full NXP NTAG 424 DNA protocol per AN12196:

Phase 2 IV: Zero (not encRndB)
PICC Response: Decrypted with original key K (not session key)
Session Keys: SV1 (A55A prefix) → SesAuthENCKey, SV2 (5AA5 prefix) → SesAuthMACKey
Command Encryption: AES-CBC with ISO 7816-4 padding (0x80 + zeros), always applied
Command MAC: CMAC truncated to odd-indexed bytes [1,3,5,7,9,11,13,15]
ChangeKey: Single CRC32 (JAMCRC) + KeyVersion + 0x80 padding
CmdCounter: Increments for all post-auth commands

Tested Against

✅ NIST SP 800-38B AES-CMAC test vectors (4 examples)
✅ NXP AN12196 authentication test vector (full round-trip)
✅ NXP AN12196 CommMode.Full IV computation
✅ NXP AN12196 CommMode.MAC pipeline
✅ Real NTAG 424 DNA hardware (NXP genuine chips)

Licence

AGPL v3 — Free for open-source use. Commercial/proprietary use requires a commercial licence.

See LICENSE for full terms.

Author

Stuart Thomas — Whitby, North Yorkshire, England

Built from 40 years of computing experience, including cryptographic systems for the NHS and London's contactless payment network.