HenriquesPontes/keylink

# 🗝️ KeyLink：通用移动密钥平台 []() []() []() **KeyLink** 是一个开源的软硬件技术栈，它通过一个安全且通过 MagSafe 吸附的 BLE 网桥来代理 RFID 和 NFC 模拟，从而将你的 iPhone 变成一把通用访问密钥。 通过将射频调制任务卸载到一个微型且基于 ESP32 的代理设备上（该设备可磁吸贴合在你的 iPhone 背面），KeyLink 完全绕过了 Apple 严格的 NFC 硬件锁定和 CoreNFC 限制——无需越狱，无需破解钱包应用，也无需缴纳任何第三方订阅费。最终结果是什么？你只需用 iPhone 轻触一下门禁即可。 ## 📸 界面预览

## 📑 目录 - [核心功能](#-core-features) - [支持的协议](#-supported-protocols) - [架构](#-architecture-how-it-works) - [新手指南](#-getting-started) - [硬件要求](#1-hardware-requirements) - [固件安装](#2-firmware-installation) - [iOS 应用构建](#3-ios-application-build) - [路线图与状态](#-roadmap--status) - [法律与安全免责声明](#-legal--security-disclaimer) ## ✨ 核心功能 * 📱 **原生 iOS 应用：** 一个精心打造的 SwiftUI 库，用于管理你所有的实体钥匙、门禁卡和 Amiibo，支持拖拽整理和自定义渐变色设计。 * 🔒 **端到端加密 (E2EE)：** 所有 BLE 通信均通过使用 Pre-Shared Key (PSK) 的 **AES-256-GCM** 进行保护，确保你的原始卡片转储数据免受抓包工具和中间人攻击的威胁。 * 🔄 **后台重连：** 利用 Apple 的 CoreBluetooth 状态恢复机制，应用会在后台自动唤醒并无缝重新连接到硬件网桥。 * 📦 **直接导入 `.bin` 文件：** 可直接从 iOS “文件”应用原生导入 Proxmark3 的 `.bin` 或 `.eml` 转储文件——无需再使用 Python 转换脚本。 * ☁️ **OTA 固件更新：** 通过本地 Wi-Fi AP 直接从 iOS 应用无缝部署并更新 ESP32 固件。 * 🔐 **生物识别安全：** 集成 `LocalAuthentication`（Face ID / Touch ID）以保护对敏感凭证数据的访问。 * 📸 **数字通行证：** 内置摄像头扫描和 `CoreImage` 二维码生成功能，允许你将数字通行证与实体 RF 凭证一并存储。 ## 📡 支持的协议 KeyLink 在 ESP32 上采用了一个自定义协议状态机，能够原生实现高速加密握手。 | 协议 | 状态 | 特性 | | :--- | :---: | :--- | | **MIFARE Classic (1K/4K)** | 🟢 完全支持 | 真正的 Crypto1 引擎、扇区密钥 (A/B)、嵌套认证、UID 克隆 | | **MIFARE Ultralight / NTAG** | 🟢 完全支持 | 原始页面模拟、`FAST_READ`、NTAG215 (Amiibo) `PWD_AUTH` 欺骗 | | **HID Prox (125 kHz)** | 🟢 完全支持 | 在 GPIO 4 上进行 Bit-bang 的 FSK/ASK 调制 | | **MIFARE DESFire EV1/EV2** | 🟡 Alpha 测试版 | ISO-DEP APDU 框架搭建，原生/ISO/AES 认证状态机 (WIP) | | **DESFire Light** | 🟢 仅限 UID | ISO/IEC 14443-4 初始化 | ## 🏗️ 架构：工作原理 ``` sequenceDiagram participant U as User participant I as iOS App (SwiftUI) participant E as ESP32 (BLE Bridge) participant P as PN532 (NFC) participant R as Door Reader U->>I: Taps "Emulate" I->>I: Extract Keys & Data I->>I: AES-256-GCM Encrypt Payload I->>E: Transmit over BLE (GATT) E->>E: AES-256-GCM Decrypt E->>E: Load into SRAM E->>P: Initialize tgInitAsTarget R->>P: 13.56MHz Field Query P->>E: Forward Challenge E->>E: Calculate Crypto1 Response (<5ms) E->>P: Send Response P->>R: Transmit Response R->>R: Authenticate & Unlock ``` KeyLink 由两个紧密集成的组件组成： 1. **软件网桥 (iOS)：** 作为你的安全指挥中心。它负责解析 `.bin` 文件，将数据安全地存储在 SwiftData 中，并处理与网桥之间加密的 BLE 传输。 2. **硬件网桥 (ESP32-S3 + PN532)：** 一款微型、电池供电的代理设备，设计用于通过 MagSafe 吸附在你的 iPhone 背面。它会解密 BLE 负载并将其加载到高速 SRAM 中。它将 PN532 配置为活动目标 (`tgInitAsTarget`)，从而绕过移动操作系统。当读卡器查询该网桥时，ESP32 会实时动态计算加密响应，以满足严格的 `<5ms` 时序限制。 ## 🌍 真实使用场景 想知道当你真正站在门前时，这一切是如何协同工作的吗？以下是你在现实生活中使用 KeyLink 的逐步分解说明： 1. **初始设置（一次性）：** 你在办公桌前使用 Proxmark3 转储你公寓楼的门禁卡（例如 MIFARE Classic 1K 卡）。然后通过 AirDrop 将 `dump.bin` 文件发送到你的 iPhone 并将其导入 KeyLink 应用。 2. **MagSafe 网桥：** 你利用 MagSafe 将微型的 KeyLink 硬件网桥吸附在 iPhone 背面。接着打开网桥的电源。 3. **后台自动连接：** 多亏了 CoreBluetooth 状态恢复机制，你的 iPhone 会在后台使用 AES-256-GCM 加密技术，安全地连接到吸附在上面的网桥。 4. **靠近门禁：** 你走到公寓上锁的门前。 5. **开启模拟：** 你打开 KeyLink 应用（通过 Face ID 认证身份），选择你的“公寓门禁”，然后点击 **模拟**。 6. **握手过程：** iPhone 会安全地将该卡的扇区密钥发送到背面的 MagSafe 网桥。网桥随之启动其 PN532 NFC 芯片。 7. **解锁门禁：** 你将 iPhone 贴近门上的 NFC 读卡器。MagSafe 网桥拦截了读卡器的查询，处理加密响应，随后门锁打开。在外界看来，你仅仅是用你的 iPhone 开了门！ ## 🚀 新手指南 ### 1. 硬件要求 要构建你自己的 KeyLink 网桥，你需要以下现成的组件： * **微控制器：** ESP32-S3-DevKitC-1 * **NFC 前端模块：** PN532 模块（通过拨码开关配置为 HSU UART 模式） * **电源：** 3.7V 500mAh 锂聚合物电池 + TP4056 充电模块 * **其他杂项：** 3.3V 至 5V 电平转换器，用于 125kHz 调制的 1mH 线圈 *（一款适用于紧凑型可穿戴外观的全定制 PCB 原理图目前正在开发中。）* ### 2. 固件安装 1. 在 Arduino IDE 中打开 `/Firmware` 目录。 2. 安装所需的依赖项：`elechouse/PN532`、`ArduinoJson`，并确保你的 ESP32 开发板定义已更新至最新版本。 3. 在 `keycard_bridge.ino` 中定义你自定义的 32 字节 AES-256-GCM Pre-Shared Key (PSK)。 4. 将固件烧录到你的 ESP32-S3 中。 ### 3. iOS 应用构建 1. 在 Xcode 15 或更高版本中打开 `/keycard/keycard.xcodeproj`。 2. 确保你在代码签名时选择了处于激活状态的 Apple Developer 团队。 3. 在 `BLEManager.swift` 中更新匹配的 32 字节 AES-256-GCM PSK。 4. 在你的实体 iPhone 上构建并运行该应用程序（iOS 模拟器不支持 CoreBluetooth 模拟）。 ## 🗺️ 路线图与状态 - [x] 基础的 ESP32 + PN532 模拟 - [x] BLE GATT 命令协议 - [x] iOS 应用：原生 `.bin` 导入和卡片库 - [x] 固件中初始 Crypto1 引擎集成 - [x] 稳定 Crypto1 握手与嵌套认证 - [x] 持久化卡片库 (SwiftData + iCloud) - [x] Amiibo 模拟（NTAG215 特定命令） - [x] 125 kHz 支持 (HID Prox) - [x] 通过 iOS 进行固件 OTA 更新 - [x] 端到端加密 (AES-256-GCM) - [ ] 完整的 MIFARE DESFire EV1/EV2 APDU 协议栈 - [ ] 定稿定制 PCB 制造文件 ## ⚠️ 法律与安全免责声明 KeyLink 的构建严格仅限于**教育和个人使用**，旨在帮助用户模拟他们**已经合法拥有**的实体门禁卡和标签。 明确地说，该项目的初衷并非作为未经授权访问、恶意克隆或商业规避的工具，也不得用于此类用途。对于任何滥用本平台的行为，开发者概不负责。请负责任地使用，并遵守所有当地法律法规。 *©️ 2026 Henriques Pontes，保留所有权利。*

标签：ESP32, iOS, NFC, RFID, 物联网, 硬件代理, 蓝牙低功耗