mlintangmz2765/libfprint-elan-04f3-0c90
GitHub: mlintangmz2765/libfprint-elan-04f3-0c90
为 libfprint 的 elanmoc 驱动添加 ELAN 04f3:0c90 片上匹配指纹传感器支持的补丁，解决了 ASUS Vivobook X1404ZA 在 Linux 下指纹录入与识别不可用的问题。
Stars: 0 | Forks: 0
# libfprint 对 ELAN 04f3:0c90 的支持
为 libfprint 的 `elanmoc` 驱动程序添加了对 ELAN 片上匹配（match-on-chip）指纹传感器 `04f3:0c90` 的支持。
见于 ASUS Vivobook X1404ZA (A1404ZA)。已在 Ubuntu 24.04 和 libfprint 1.94.100 上进行了测试。
**状态：录入（enroll）和识别（identify）均可正常工作。**
## 为什么仅靠 PID 是不够的
`elanmoc` 是正确的驱动系列——该传感器使用该协议——但 `04f3:0c90` 并未实现驱动假定存在的三个命令，并且在两个值上与驱动存在分歧：
| | 上游 (upstream) | 04f3:0c90 |
|---|---|---|
| set mode 参数 | `0x03` | `0x00` |
| 录入步骤 (enroll steps) | 9 | 11 |
| 重新录入检查 (re-enroll check) | `40 ff 22` | 未实现 |
| 获取用户 ID (get user id) | `43 21 ` | `40 ff 12 ` |
| 验证 (verify) | `40 ff 73` | `40 ff 03` |
set-mode 的值是真正阻止匹配的原因：在 `0x03` 模式下，传感器会检测手指并报告图像质量，但从不将它们与模板进行比对。
`40 ff 12` 在其 payload 之前还多带有一个字节，这导致用户 ID 长度字段发生了偏移。
有关完整的发现，请参阅 [docs/PROTOCOL.md](docs/PROTOCOL.md)。
## 已知限制
此传感器未实现 `43 21`（获取用户 ID），因此 libfprint 无法枚举或删除片上存储。STORAGE 功能已被移除，指纹元数据改为保留在主机上。
模板仍会被发送到芯片上，该芯片共有 **9 个槽位（slots）**，而在 Linux 中没有任何方法可以释放它们。反复录入最终会填满传感器；目前要清除它只能使用 Windows Hello。
`40 ff 12 ` 可以通过索引读取任何槽位，因此后续可以在其基础上构建列表功能。删除（`0x13`）和清除（`0x98`）尚未在此设备上经过验证。
## 构建
```
git clone https://gitlab.freedesktop.org/libfprint/libfprint.git
cd libfprint
git am /path/to/patches/0001-elanmoc-Add-support-for-ELAN-04f3-0c90.patch
meson setup build
ninja -C build
```
`patches/0002-*` 是可选的，且**不**适用于上游：它会记录每次回复的原始字节，并添加了一个 `ELANMOC_MODE` 环境变量覆盖。
在将其适配到不同的 ELAN PID 时非常有用。
然后，在停止 `fprintd` 的情况下：
```
sudo ./build/examples/enroll
sudo ./build/examples/identify
```
或者使用脚本，这些脚本会停止 `fprintd`，从可写目录中运行，并将每次会话记录到日志中：
```
scripts/build.sh # clone, apply the patch, build
sudo scripts/enroll.sh # 11 touches
sudo scripts/identify.sh # run twice: enrolled finger, then a different one
```
`WITH_DEBUG=1 scripts/build.sh` 也会应用补丁 0002。
## 将此适配到其他 ELAN 传感器
也应用 `patches/0002-*`。它会记录每次回复的原始字节：
```
elanmoc RX 2 B : 40 03
elanmoc RX 64 B: 40 00 00 00 00 1c 46 50 31 2d ...
```
并且允许 `ELANMOC_MODE=3` 在无需重新构建的情况下覆盖 set-mode 参数，这就是此处隔离出模式差异的方法。
首先检查您的传感器是否完全支持 `40 ff 73` 和 `43 21`。如果支持，除了 `id_table` 条目外，它可能不需要其他任何更改。
## 上游
有关此功能是如何提交给 libfprint 的，请参阅 [docs/UPSTREAM.md](docs/UPSTREAM.md)。
## 发现过程
通过使用 USBPcap 在同一台机器上对 Windows 驱动程序进行的 USB 抓取，以及对传感器进行的实验。没有对任何驱动二进制文件进行反汇编，此处也不包含任何供应商代码。
抓包本身并未公开：其中包含指纹会话数据。
## 许可证
该补丁是 libfprint 的衍生作品，因此采用与 libfprint 相同的 **LGPL-2.1-or-later** 许可证。本仓库中的文档和脚本均在相同条款下发布。
标签：C2日志可视化, libfprint, Linux硬件支持, 指纹识别, 生物识别, 网络安全监控, 驱动开发