🪪 NFCIdentityKit

An Advanced iOS SDK for eMRTD & ICAO 9303 Identity Document Reading via CoreNFC

---

📖 Overview

NFCIdentityKit is a highly specialized, secure, and modern iOS SDK built to read and parse biometric identity cards and passports. By utilizing Apple's CoreNFC framework and strict cryptographic standards (ICAO 9303), the kit securely communicates with the identity card's chip, derives encryption keys from the Machine Readable Zone (MRZ), and establishes a Secure Messaging (SM) channel to read Data Groups (e.g., DG1 for personal details).

Whether you are building a FinTech, Banking, or highly secure KYC (Know Your Customer) flow, NFCIdentityKit provides a robust architectural foundation out of the box.

---

📸 App Flow & Previews

       

---

🏗️ Architecture & Folder Structure

The project is built on a clean MVVM-C (Model-View-ViewModel-Coordinator) architecture powered by Apple's Combine framework for reactive state management.

NFCIdentityKit/
├── Application/            # AppDelegate & SceneDelegate
├── Core/                   # Core Logic & Utilities
│   ├── Crypto/             # 🔐 Secure Messaging, APDU, 3DES/AES Mac Padding
│   ├── Models/             # Domain Models (Parsed Identity Data)
│   ├── Parsers/            # 📄 DataGroupParser (DG1, DG2 parsing logic)
│   └── Protocols/          # Protocols & Interfaces
├── Resources/              # Assets (Icons, Images), Info.plist, Lproj
├── Services/               # Hardware & External Integrations
│   ├── NFC/                # KYCNFCService, ChipReader (CoreNFC Delegates)
│   └── Vision/             # Vision Framework (MRZ OCR Scanning)
└── Modules/                # UI & Presentation Layer (MVVM-C)
    ├── AppCoordinator.swift
    ├── Onboarding/         # Welcome & Initial Screen Module
    ├── KYCScanner/         # MRZ Input & Camera Scanning Module
    ├── NFCOverlay/         # NFC Reading Progress & Feedback Module
    └── IdentityDetail/     # Final Parsed Data Presentation Module

---

🔐 How Identity Decryption Works (The Cryptographic Flow)

Reading an NFC identity card isn't just about tapping the phone. It requires a mutual authentication handshake. Here is how NFCIdentityKit handles it:

1. MRZ Extraction: The user's Document Number, Birth Date, and Expiry Date are extracted from the physical card.
2. BAC (Basic Access Control) Key Derivation: Using the extracted data, the SDK derives a pair of keys: K_ENC (for encryption) and K_MAC (for message authentication).
3. Mutual Authentication: An initial GET CHALLENGE APDU command is sent to the NFC chip. The chip and the iOS device exchange encrypted random numbers to prove they both know the keys.
4. Secure Messaging (SM): Once authenticated, a secure channel is established. All subsequent APDU commands sent to the card are padded, MAC'ed, and encrypted.
5. Reading Data Groups: The SDK selects the eMRTD application (A0000002471001) and safely reads binary data from DG1 (MRZ & Details) and other groups.

Warning: Apple strictly requires the com.apple.developer.nfc.readersession.iso7816.select-identifiers key in the Info.plist to communicate with identity chips.

---

🧪 Automated Testing & CI/CD

Hardware-dependent features like NFC are notoriously difficult to test in CI/CD pipelines. NFCIdentityKit solves this by strictly separating the hardware logic from the parsing and cryptographic layers.

• Mock Data Injection: The DataGroupParser and BACHandler are fully tested using pre-recorded Hex Mock Data.
• GitHub Actions: The project includes a .github/workflows/ios.yml pipeline that spins up a macos-latest virtual machine, simulates an iPhone 17 Pro, and automatically runs xcodebuild test on every push to the master branch.

func testDG1ParsingWithMockData() throws {
    // Cryptographic parser successfully verified without a physical NFC device
    let mockDG1Hex = "615B5F1F58503C5455524B41..."
    let parsedResult = DataGroupParser.parseDG1(dataFromHex(mockDG1Hex))
    
    XCTAssertNotNil(parsedResult)
    XCTAssertEqual(parsedResult?.documentNumber, "A52C65740")
}

---

🚀 Future Roadmap

• Implement DG2 Parsing for High-Resolution Identity Photos.
• Active Authentication (AA) support.
• PACE (Password Authenticated Connection Establishment) integration.

---

Developed by Nurullah Kaya