跨平台、单文件、纯 Go（无 CGO）的 PN532 MIFARE Classic (M1) RFID 工具包
支持 macOS / Linux / Windows，免安装任何驱动环境，插上 USB-TTL 串口模块即用。
-success){kind=icon}
- 合法授权原则：本工具仅供信息安全研究人员、物联网硬件开发者、高校教学科研及合法卡片持有者用于技术学习、学术研究、自有卡片数据备份或已获得正式书面授权的安全审计与测试。
- 严禁非法与侵权使用：任何个人或组织严禁将本工具用于未经所有者授权的卡片读取、破解、复制、解密等行为，严禁利用本工具从事任何侵犯他人隐私、危害公共安全或从事非法牟利、黑灰产等违法犯罪活动。
- 硬件与数据免责：由于 MIFARE Classic 芯片的物理与协议特性，对卡片扇区控制位及块 0 的读写操作存在不可逆的硬件锁死（变砖）风险。作者及贡献者不对因使用本工具导致的任何硬件损坏、数据丢失或设备故障承担任何责任。
- 完全责任自负：本项目按“原样（AS-IS）”提供，不包含任何明示或暗示的担保。使用者必须严格遵守所在国家或地区的相关法律法规（如《网络安全法》、《数据安全法》及无线电管理条例等）。因违反上述原则或滥用本工具产生的一切民事、行政或刑事法律责任，均由使用者自行完全承担，与本项目作者及贡献者无关。
在 MIFARE Classic 与 PN532 的传统开发与研究中，C/C++ 工具链（如 libnfc、mfoc）往往面临较重的平台依赖与编译配置门槛。nfc-tool 旨在基于现代化 Go 生态，提供一个免环境依赖、开箱即用、原生并发加速的完整解决方案：
- 纯 Go 零外部依赖：无需安装 CGO、驱动或动态链接库，单一静态二进制文件，跨平台构建极其便捷。
- 极速 Nested 攻击引擎：深度优化的 Crypto1 LFSR 并行恢复算法，配合寄存器批写缓存（Writeback Cache）与排序分级，大幅提升破解效率。
- 完善的防砖卡安全保护：自动识别非法访问位占位符、自动重算 UID 块 0 BCC 校验、倒序写块保护，保障卡片可读写安全性。
- 增量密钥缓存：破解过程实时原子化落盘（按卡 UID 隔离缓存），随时中断不丢进度。
- 易于集成与扩展：全局支持
--json（NDJSON 紧凑格式），便于作为自动化脚本或第三方 GUI 前端的后端引擎。
📖 更多详细设计初衷请参阅 doc/GOAL.md，算法性能剖析与实测数据请参阅 doc/PERFORMANCE.md。
将 PN532 模块拨码开关调至 HSU 模式（UART 串口模式），通过 USB-TTL 模块（如 CP2102、CH340、FTDI 等）连接电脑：
| PN532 引脚 | USB-TTL 模块引脚 |
|---|---|
| VCC | 5V / 3.3V |
| GND | GND |
| TXD | RXD |
| RXD | TXD |
# 1. 自动探测串口与卡片信息
nfc-tool detect
# 2. 字典扫描（检测哪些扇区使用了已知/默认密钥）
nfc-tool scan
# 3. 密码学 Nested 攻击破解全部扇区密钥（实时 ETA 进度，按 UID 自动缓存）
nfc-tool crack
# 4. 导出整卡为标准 1024 字节 .mfd 镜像（兼容 mfoc / proxmark3）
nfc-tool dump -o backup.mfd
# 5. 克隆到 CUID / Gen2 可写卡（含 UID 块 0 改写）
nfc-tool clone -i backup.mfd --with-uidnfc-tool 能够智能探测并管理串口：
| 使用方式 | 行为说明 |
|---|---|
nfc-tool <子命令> |
自动扫描：自动探测所有可用串口，优先连接第一个应答的 PN532 设备（macOS 上优先尝试 /dev/cu.*）。 |
nfc-tool --port <端口路径> <子命令> |
指定端口：显式使用该串口（如 macOS: /dev/cu.usbserial-0001，Windows: COM3，Linux: /dev/ttyUSB0）。 |
nfc-tool --list-ports |
列出端口：列出主机所有串口，并明确标出哪个端口有 PN532 响应后退出。 |
全局通用参数 (Global Flags)：
--port <str>: 指定串口路径。--baud <int>: 串口波特率（默认115200）。-k, --keys <file>: 指定外部密钥字典文件（每行一个 12 位十六进制密钥）。--no-cache: 忽略本地按 UID 缓存的已知密钥。--json: 输出紧凑的单行 JSON（NDJSON），便于上位机解析。
读取放置在读写器上的卡片 UID、ATQA、SAK，识别卡片类型。
nfc-tool detect目前专注支持 MIFARE Classic 1K (S50) 及兼容卡（SAK 0x08 / Plus SL1 模拟模式）。若遇其他卡型（如 4K S70 / Ultralight）将主动提醒。
使用内置默认字典 + 用户指定字典 (-k) + UID 本地缓存尝试认证全卡 16 个扇区。
nfc-tool scan
nfc-tool scan -k my_dict.keys利用 MIFARE Classic 密码学弱点（Nested Attack），只需至少 1 个已知扇区密钥，即可全自动求解所有未知扇区的 KeyA / KeyB。
nfc-tool crack
nfc-tool crack -k user_keys.txt特性说明：
- 实时进度与 ETA：命令行显示
[已破/总数]、已耗时与滑动窗口预估剩余时间。 - 增量落盘：每恢复一个 Key 立即原子化写入本地按 UID 隔离的密钥缓存，随时中断不丢失进度。
- 自适应探测 (brokenKeys)：破解出的新密钥会自动复用到其余未破扇区；对可读 Trailer 的扇区直接提取 KeyB，极大缩减攻击时间。
将整张卡片（16 扇区，共 64 块，1024 字节）读取并导出为通用 .mfd 原始二进制文件。
# 导出到文件
nfc-tool dump -o my_card.mfd
# 结合外部字典 dump
nfc-tool dump -o my_card.mfd -k my_keys.keys
# 省略 -o 参数：直接在终端打印十六进制数据块
nfc-tool dump将 .mfd 镜像数据写回普通 M1 卡或兼容卡。
nfc-tool write -i my_card.mfd- 默认安全跳过块 0 (UID)，防止误改写普通卡 UID 扇区。
--with-uid: 连同块 0 一起写入（需 CUID / Gen2 卡支持）。--skip-locked: 若某些扇区因写权限禁止而拒绝写入，跳过该扇区继续写入其余部分。
专为向 CUID (Gen2) 等可写卡克隆设计，具备完整安全防护策略。
# 安全克隆（跳过 UID 与不可读 partial 扇区）
nfc-tool clone -i source.mfd
# 完整克隆（包含改写块 0 UID）
nfc-tool clone -i source.mfd --with-uid
# 预演模式（不真正写卡，打印即将执行的写操作）
nfc-tool clone -i source.mfd --with-uid --dry-run
# 强制填充不可读扇区（使用默认安全权限位）
nfc-tool clone -i source.mfd --force-fill --skip-locked将卡片所有数据块置零，并将 16 个扇区的 KeyA、KeyB 全部重置为出厂默认 FFFFFFFFFFFF（保留 UID 块 0）。
nfc-tool erase --force探测卡片是否支持 Gen1A（0x40/0x43 后门指令），若支持可免密直接改写全卡数据（包括被密码锁死的扇区）。
# 探测后门支持情况
nfc-tool unlock
# 经由后门强行写入镜像
nfc-tool unlock -i image.mfd管理与整理你的 .keys 字典文件（每行一个 12 位十六进制密钥）。
# 校验字典文件有效性
nfc-tool keys check my_keys.keys
# 合并、去重并生成新字典
nfc-tool keys merge combined.keys dict1.keys dict2.keys直接向 MIFARE Classic 写入数据存在因权限配置错误而**永久锁死卡片（变砖）**的高风险。nfc-tool 在底层内置了强制防护策略：
- 访问控制位保护 (
SafeTrailerForWrite)
部分 dump 文件对不可读扇区的控制位填充00000000。若原样写回卡片，将使扇区永久锁死。nfc-tool会自动拦截非法的00000000占位符，安全替换为出厂默认值ff0780。 - 块 0 BCC 校验自动修正 (
FixBlock0)
块 0 包含 4 字节 UID 及 1 字节 XOR 校验和 (BCC)。BCC 错误会导致卡片无法被射频场选中。写入块 0 前工具会自动重新计算并填充正确的 BCC。 - 倒序写入顺序
写块时一律从 扇区 15 → 扇区 0 倒序写入，确保块 0 (UID) 最后写入。避免因提前修改 UID 导致后续扇区密码会话失效。 - Partial 扇区隔离保护
对于仅能通过认证但禁止读取内容的加密扇区，clone 命令默认跳过，避免将无效的占位全 0 数据当成真实内容写入目标卡。
nfc-tool 针对 nested 攻击做了极致优化（LSD Radix 排序分级 + 并行 LFSR 回溯）。你可通过以下环境变量微调：
NFC_TOOL_RECOVERY_JOBS：控制 Nested 破解并行 Worker 数量。- 默认值为
min(NumCPU, 4)（内存占用仅 ~112MB）。 - 在内存充裕的高性能设备上（如 10+ 核），可指定
NFC_TOOL_RECOVERY_JOBS=10跑满并发，大幅缩短困难卡的破解耗时。
- 默认值为
NFC_TOOL_SINGLE_REG：兼容性开关。- 官方标准 PN532 支持多寄存器批量读写；部分廉价的山寨 PN532 模块固件在批量写寄存器时可能无响应。
- 若在破解初期遇到频繁的认证超时，可使用
NFC_TOOL_SINGLE_REG=1 nfc-tool crack启用单寄存器模式。
本项目为 Pure Go 项目，无需安装 MinGW、gcc 或 libnfc。
go install github.com/azurefatty/nfc-tool@latestgit clone https://github.com/azurefatty/nfc-tool.git
cd nfc-tool
go build -trimpath -ldflags="-s -w" -o nfc-tool .chmod +x build.sh
./build.sh构建产物输出于 dist/ 目录：
dist/nfc-tool-darwin-arm64(Apple Silicon Mac)dist/nfc-tool-darwin-amd64(Intel Mac)dist/nfc-tool-linux-amd64(Linux x86_64)dist/nfc-tool-windows-amd64.exe(Windows x86_64)
| 操作系统 | 架构 | 编译支持 | 物理真机验证状态 | 说明 |
|---|---|---|---|---|
| macOS | arm64 (Apple Silicon) | ✅ 支持 | ✅ 已真机完整验证 | 日常主力开发与硬件实测平台（M系列芯片） |
| macOS | amd64 (Intel) | ✅ 支持 | ✅ 已真机完整验证 | 串口通信、Nested破解与读写全功能正常 |
| Linux | amd64 / arm64 | ✅ 支持 | 🟡 待真机测试 | 纯 Go 编译无依赖，底层依赖 go.bug.st/serial，待真机实测 |
| Windows | amd64 / x86 | ✅ 支持 | 🟡 待真机测试 | 单 .exe 静态编译，无需安装驱动环境，待真机实测 |
💡 提示：项目采用纯 Go 编写且已包含跨平台串口抽象与虚拟卡单元测试。目前真机全功能测试主要在 macOS 上完成，Linux / Windows 架构已保证编译通过与单元测试通过。欢迎社区在 Linux / Windows 物理环境下测试并反馈！
nfc-tool/
├── cmd/ # Cobra CLI 命令层（参数解析、格式化输出、JSON/NDJSON 封装）
│ ├── detect.go # 卡片识别
│ ├── scan.go # 字典扫描
│ ├── crack.go # Nested 攻击破解
│ ├── dump.go # 镜像读取
│ ├── write.go # 镜像写入
│ ├── clone.go # CUID 克隆
│ ├── erase.go # 卡片擦除
│ ├── unlock.go # Gen1A 后门交互
│ └── keys.go # 字典管理
├── internal/
│ ├── connect/ # 串口自动识别、PN532 探测与连接打开
│ ├── pn532/ # PN532 HSU 帧解析、唤醒、选卡、InDataExchange 及寄存器写回缓存
│ ├── mfc/ # MIFARE Classic 协议：认证、读写块、BCC 校验、SafeTrailer 访问位修复
│ ├── crypto1/ # 纯 Go 实现的 Crypto1 流密码与 LFSR 回溯算法
│ ├── nested/ # 移植自 mfoc 的 Nested 攻击调度与并行破解引擎
│ ├── keycache/ # 基于卡片 UID 的增量式密钥缓存管理
│ ├── serial/ # 跨平台底层串口封装 (go.bug.st/serial)
│ └── virtualcard/ # 虚拟卡与 PN532 内存模拟器（用于离线全流程单元测试）
├── build.sh # 跨平台构建脚本
└── doc/ # 性能测试基准与技术设计文档