## 为什么

Linux 下的硬件 USB 指纹读取器稀缺、昂贵，并且现有的（如 Validity、Synaptics 等）都是通过不稳定的 libfprint 驱动逆向工程而来，这些驱动会在供应商固件更新时失效。Grow R503 的协议是 **公开** 的，Arduino 端是你自己的代码，而 libfprint 兼容层只是 D-Bus。

你最终还会得到一个从头到尾都能读到源代码的指纹读取器。

## 物料清单

| 部件 | 备注 | 大致成本 |
|------|-------|------|
| Grow R503 电容式指纹传感器 | 带有 RGB 环的圆形款 | ~$10 |
| Arduino Uno R3 / Nano / Mega / 任何 ATmega328 开发板 | 任何能运行 SoftwareSerial 的板子 | $5–$25 |
| 4–6 根杜邦线 | 杜邦 / 面包板 | 微不足道 |

就这样。**无需电平转换器，无需分压器** — 原因见 [`SPEC.md` §3.1](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md)（R503 的 RX 线在实践中可承受 5V；数据手册有误）。

## 接线```
R503             Arduino (Uno R3 / Nano / etc.)
----             ------------------------------
Red (VCC)        3V3
White (3.3VT)    3V3                  (touch-IC supply; shares rail with red)
Black (GND)      GND
Yellow (TXD)     D2  ── SoftwareSerial RX
Brown (RXD)      D3  ── SoftwareSerial TX   (direct — no divider!)
Blue (WAKEUP)    D4                          (optional; not used by firmware yet)

如果两者都成功，你的主机可以使用密封密钥路径。如果 `/dev/tpmrm0` 缺失（旧硬件、BIOS中禁用了TPM，或没有虚拟TPM的虚拟机），则坚持使用默认的明文密钥流程。

## 构建与安装

### 1. 烧录固件

在Arduino IDE中打开 `firmware/r503fp/r503fp.ino` 并上传。或者使用 `arduino-cli`：```bash
# Uno R3:
arduino-cli compile --fqbn arduino:avr:uno firmware/r503fp/
arduino-cli upload  --fqbn arduino:avr:uno --port /dev/ttyACM0 firmware/r503fp/

# Nano (modern Optiboot, including most Elegoo / WAVGAT clones):
arduino-cli compile --fqbn arduino:avr:nano:cpu=atmega328 firmware/r503fp/
arduino-cli upload  --fqbn arduino:avr:nano:cpu=atmega328 --port /dev/ttyUSB0 firmware/r503fp/

# Nano with legacy 57600-baud bootloader (older clones):
#   replace `cpu=atmega328` with `cpu=atmega328old`

### 3. 安装```bash
sudo bash pcside/daemon/dist/install.sh

(此块内容为空)```bash
sudo r503d --status
# port:             /dev/r503
# firmware:         fw=1.1 fmt=2
# firmware paired:  true
# firmware counter: 42
# host key.tpm:     (absent)
# host key:         /var/lib/r503d/key
# host key.bak:     /var/lib/r503d/key.bak
# tpm device:       (absent)
# allow-pair:       (absent)

（由于输入内容为空，无翻译内容）```bash
sudo r503d --status
# port:             /dev/r503
# firmware:         fw=1.1 fmt=2
# firmware paired:  true
# firmware counter: 12
# host key.tpm:     /var/lib/r503d/key.tpm
# host key:         (missing)
# host key.bak:     (missing)
# tpm device:       /dev/tpmrm0
# allow-pair:       (absent)

Both KDE Settings (Plasma 6) and GNOME Control Center's user-account
fingerprint dialogs drive `r503d` exactly as they drive upstream `fprintd`.

### 重新配对 / 密钥轮换

如果你想要一个新的密钥（密钥泄露、计划更换硬件、偏执狂）：```bash
sudo systemctl stop r503d
sudo r503d --unpair                        # framed; wipes Nano EEPROM + host key
sudo touch /etc/r503d/allow-pair
sudo r503d --pair                          # plaintext-key rotation
#  - or -
sudo r503d --pair --seal-tpm               # TPM-sealed rotation
sudo systemctl start r503d

该脚本会停止 `r503d`，重新刷写 `firmware/r503fp_wipe/` 来擦除 Nano EEPROM，然后重新刷写主固件，创建 `/etc/r503d/allow-pair`，运行 `r503d --reseal-tpm` 以生成一个绑定到*当前*PCR7的新密钥，最后重新启动守护进程。整个过程大约耗时90秒。已注册的指纹会被保留——模板存储在 R503 传感器的闪存中，而非 Nano 上。

该脚本需要 `arduino-cli` 可用。如果它安装在当前用户的 `$HOME/.local/bin` 目录下，则可通过 `$SUDO_USER` 自动检测；否则需要在运行前设置 `ARDUINO_CLI=/full/path/to/arduino-cli`。

### 恢复：`state.json` 丢失（计数器不同步）

如果主机密钥完好，但 `/var/lib/r503d/state.json` 丢失或回滚（例如恢复了旧备份或意外删除），守护进程的计数器会落后于 Nano 的 `last_seen`，导致每个帧命令都因 `ERR replay` 而被拒绝。`r503d --status` 会标记此问题；修复方法是一条命令：```bash
sudo systemctl stop r503d
sudo r503d --resync                         # reads Nano last_seen, sets host counter to last_seen+1
sudo systemctl start r503d

如果 `sudo arduino-cli` 报告命令未找到（arduino-cli 位于你的 `~/.local/bin` 中，而不在 root 的 `PATH` 中），请以 `sudo env "PATH=$PATH" arduino-cli …` 运行它，或者给出绝对路径。

这不是攻击者可以利用的后门：重新配对需要主机上的 root 权限（可选文件及 `--pair` 命令行均需要 root 权限），因此，除非你已经拥有 root 权限，否则重新刷写的 Nano 无法被纳入信任。

### 卸载```bash
sudo bash pcside/daemon/dist/uninstall.sh

## 安全模型 — 快速总结

线路级别的认证针对的是特定威胁 —
**"恶意的女仆，带有五分钟和一个备用 Nano"** 加上一个在 `/dev/r503` 上的敌对本地进程 — 而不是拥有实验室的国家级或硬件攻击者。单用户桌面部署，附带已记录的不在范围内的列表。完整的威胁模型见 [`SPEC.md` §13.1](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md)；实现与审查的证据见 [`docs/REVIEW-2026-05-28.md`](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/docs/REVIEW-2026-05-28.md)。一次独立的对抗性权限提升审计 (2026-05-28) 及其针对每个声明的验证/修复过程见 [`docs/SECURITY-AUDIT-2026-05-28.html`](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/docs/SECURITY-AUDIT-2026-05-28.html) 和 [`docs/SECURITY-AUDIT-2026-05-28-VALIDATION.html`](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/docs/SECURITY-AUDIT-2026-05-28-VALIDATION.html)。

**已防御：**
- 将 Nano 热替换为敌对单元（无密钥 → 所有帧通过 MAC 失败）。
- 本地进程在 `/dev/r503` 上注入虚假匹配响应。两层保护：
  设备节点是 `root:root 0600`（udev 规则），并且守护进程使用 `TIOCEXCL` 持有它，因此非 root 进程无法打开它 — 即使能打开，它也没有密钥，所以帧无法通过 MAC 验证。
- 重放录制的 `OK match=...` 帧以用于未来会话。
- 任何帧字段的比特翻转篡改（恒定时间 MAC 比较）。
- 计数器耗尽阻断：一个对端（或 `--resync` 期间的一次性中间人）将单调计数器驱动到 `u64::MAX` 并永久阻塞通道，该行为被两端强制执行的保留计数器上限阻止 (`fw=1.1+`; SPEC §13.4 / 2026-05-28 审计 DoS-2)。
- 本地用户对传感器的拒绝服务攻击：单个捕获槽门限制并发注册/验证工作，且删除路径受操作门控，因此 `Start`/`Stop`（或并发删除）洪泛无法阻塞认证。
- 本地非 root 用户的跨用户指纹植入/清除/枚举（例如 `mallory` 调用 `Claim "root"` 然后注册自己的手指）——每次接受 `username` 的 D-Bus 方法都会检查调用者身份，且系统总线策略在代理层拒绝非 `wheel` 的调用者。
- **离线磁盘攻击主机密钥** *当与 `--seal-tpm` 结合使用时*：磁盘上的密钥使用 TPM2 密封到 PCR7，因此对未挂载分区进行 `dd` 或将 SSD 插入敌对主机只会得到密文。仅在同一台机器上、相同安全启动策略下才能解封。参见 [SPEC §13.12](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md)。

**未防御：**
- 主机 root 权限被攻破（密钥位于 `/var/lib/r503d/key`，`0600 root:root`）。运行中主机上的 root 也可以解封 TPM 密封的变体 — 密封削弱的是 *离线* 攻击，而非在线攻击。
- 对 Nano 的物理攻击（通过 ISP 回读 EEPROM 约 30 秒；芯片开盖等）。
- 固件重刷攻击（Arduino 引导加载程序没有签名 — 但重新配对需要主机上的 root 权限，所以没有主机被攻破，重刷过的 Nano 也无法被信任）。
- R503 侧被攻破（R30x 协议完全无认证；超出范围）。
- **密码学状态。** SipHash-2-4 MAC，128 位共享密钥，64 位 MAC 输出，域分离的 MAC 输入。两个独立的实现（AVR 上手写 C++，含启动时 KAT 自测试；主机上手写 Rust，在 CI 中针对第三方 `siphasher` 包的 1024 个随机向量进行逐位交叉验证）。主机 MAC 比较使用 `subtle::ConstantTimeEq`。线缆解析器在每个 CI 运行中进行属性模糊测试（约 135,000 个输入）。`cargo audit` 干净。SipHash 密钥包装在 `zeroize::Zeroizing<...>` 中，以便在 drop 时清除（每帧的 MAC 输入缓冲区也是如此）。一个 `cargo fuzz` libFuzzer 目标位于 `pcside/daemon/fuzz/`，用于在 nightly 上进行长语料库运行。没有付费的第三方人工审计 — 那仍然很有价值，欢迎 PR。

完整威胁模型及理由： [`SPEC.md` §13.1](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md)。

## 限制

- **多用户可行，但仅限于 `wheel` 组成员。** 每个接受 `username` 的 D-Bus 方法都会检查调用者身份（`Claim`、`EnrollStart`、`VerifyStart`、`ListEnrolledFingers`、`DeleteEnrolledFingers`）；自身请求和 `uid 0` (PAM) 静默成功，来自非 root 调用者的跨用户请求被拒绝，返回 `net.reactivated.Fprint.Error.PermissionDenied`。系统总线策略进一步限制哪些帐户甚至可以开始对话：只有 `root` 和 `wheel` 成员能到达守护进程，其他人在代理层收到 `org.freedesktop.DBus.Error.AccessDenied`。需要跨用户注册？成为 root：`sudo fprintd-enroll target-user`。需要为自助服务终端/多用户实验室放宽跨用户限制？将一条 JS 规则放入 `/etc/polkit-1/rules.d/`，针对 [`net.reactivated.fprint.device.setusername`](https://gitlab.freedesktop.org/libfprint/fprintd/-/blob/master/src/net.reactivated.fprint.device.policy.in) — 动作名称与上游 fprintd 完全一致。
- **一个读取器。** 守护进程在 D-Bus 上暴露单个 Device 对象。多读取器设置需要对 Manager 进行扩展。
- **没有发出 `PropertiesChanged`** 针对 `finger-present` / `finger-needed` 提示属性。所有常见的 fprintd 客户端（PAM、KDE 设置、GNOME）都依赖 `EnrollStatus` / `VerifyStatus` 信号（这些信号会发出），而不是那些轮询的提示 — 但一个严格的客户端如果执行 `Get + PropertiesChanged` 将看到过时的值。
- **单个 Nano = 单点故障。** 如果 Nano 死了，指纹登录就不可用，直到你重新刷写一个备用件并重新配对。请保持启用密码认证方法作为备份。
- **State.json 丢失可通过一条命令恢复。** 如果 `state.json` 丢失而固件仍有较高的 `last_seen`，守护进程在首次发送时会遇到 `ERR replay`。运行 `sudo r503d --resync` 读取 Nano 的计数器并重新对齐主机 — 无需重新配对。参见 [`SPEC.md` §13.11](https://github.com/matpb/linux-fingerprint-r503/blob/HEAD/SPEC.md)。

## 故障排除```bash
# Daemon logs:
sudo journalctl -u r503d.service -f

# Confirm the sensor enumerates correctly:
ls -l /dev/r503
busctl --system call net.reactivated.Fprint /net/reactivated/Fprint/Device/0 \
    net.reactivated.Fprint.Device ListEnrolledFingers s ""

# Confirm fprintd is masked and r503d owns the bus name:
systemctl is-enabled fprintd  # should print "masked"
busctl --system list | grep -i fprint