grosa787/dell-controlvault2-fingerprint-linux

# 在 Linux 上使用 Dell ControlVault 2 指纹模块 (Broadcom BCM5880, `0a5c:5834`) 让 **Dell ControlVault 2 / Broadcom BCM5880 "USH"** 指纹读取器 (USB ID **`0a5c:5834`**) 在 Linux 下通过 `fprintd` / `libfprint` 正常工作。 这款读取器出现在许多 **Dell Latitude** 笔记本上（7390、7480、**7490**、 E7470、5290、5490、5590, …）。它曾被认为*在 Linux 上长达十年不受支持* —— `libfprint` 无法识别它，而 Dell 仅为较新的 ControlVault **3** 传感器提供了闭源驱动。 本仓库对该闭源驱动进行了补丁处理，使其也能驱动旧款的 CV2 芯片。 ## 这适合我吗？ 运行 `lsusb`。如果你看到： ``` Bus 00x Device 00x: ID 0a5c:5834 Broadcom Corp. 5880 ``` ……并且 `fprintd-enroll` 提示 *"No devices available"*，那么本项目正是为你准备的。 ## 安装说明 本仓库**仅提供补丁文件**，不包含 Dell 的专有二进制文件。经过补丁处理的 驱动程序会在本地基于 Canonical 官方的原始 OEM 驱动构建。你需要 `git` 和 `python3`。 ``` git clone https://github.com/grosa787/dell-controlvault2-fingerprint-linux cd dell-controlvault2-fingerprint-linux ./build_from_upstream.sh # fetch stock driver from Canonical's OEM repo + apply patches sudo ./install.sh # install driver + udev rule + firmware, restart fprintd fprintd-enroll # enroll a finger (press, lift, repeat ~4-8x) fprintd-verify # test recognition sudo pam-auth-update # (optional) enable fingerprint login & sudo ``` 如果操作系统 / `libfprint` 的更新将其覆盖清除，请再次运行 `./install.sh`（如果之前清理过构建文件，请先重新运行 `./build_from_upstream.sh`）。 ## 状态 | 功能 | 状态 | |---|---| | 设备被 `libfprint`/`fprintd` 识别 | ✅ 正常 | | 打开 / 通电 | ✅ 正常 | | 指纹**采集**（传感器亮起，抓取图像） | ✅ 正常 | | **录入** → `enroll-completed`（模板提交至芯片） | ✅ 正常 | | **验证 / 匹配**（芯片端匹配） | ✅ 已实现（补丁 4–5） — **请在你的设备上确认** | 最困难的部分是**芯片端匹配**：模板存储在芯片的安全 存储中。补丁 **4–5** 重新路由了 CV2 的录入/验证状态码，使得 模板能够真正提交，并报告匹配结果。这是最新的 部分 —— 如果 `fprintd-verify` 在你的笔记本上返回 `no-match`/`unknown-error`， 请提交一个 issue 并附上调试日志（见下文）；不同的 CV2 设备可能会使用略有不同的状态码，这些都很容易添加。 ## 故障排除 **启用调试日志**（以读取芯片返回的信息）： ``` sudo mkdir -p /etc/systemd/system/fprintd.service.d printf '[Service]\nEnvironment=G_MESSAGES_DEBUG=all\nEnvironment=LIBFPRINT_DEBUG=3\n' \ | sudo tee /etc/systemd/system/fprintd.service.d/debug.conf sudo systemctl daemon-reload && sudo systemctl restart fprintd # 复现，然后： sudo journalctl -u fprintd --since "2 min ago" -o cat ``` - 在录入期间显示 `Device status = (NN)`（十进制），或在验证期间显示 `identify failed 0xNN` → 这里的 `NN` 就是需要映射的 CV 状态。参见 `PATCHES.md` #4/#5。 - 重新列出 / 清除指纹：`fprintd-list "$USER"`, `fprintd-delete "$USER"`。 ## 工作原理 五个字节级别的补丁将 CV3 驱动变成了 CV2 驱动。完整的 逆向工程分析及精确的特征签名请参见 **[PATCHES.md](PATCHES.md)**。补丁脚本 (`patch_driver.py`) 通过 独特的字节签名来应用它们，因此能够抵御上游二进制文件的细微更改，并且 它会**逐字节**地复现可用的驱动程序。 ## 仓库结构 ``` install.sh install the prebuilt driver + assets build_from_upstream.sh fetch stock driver from Launchpad and patch it patch_driver.py the 5 byte-patches (signature based) uninstall.sh remove it prebuilt/ generated by build_from_upstream.sh (gitignored, proprietary) firmware/ generated by build_from_upstream.sh (gitignored, proprietary) udev/ rule binding 0a5c:5834 to the driver PATCHES.md reverse-engineering notes ``` ## 法律 / 许可 驱动程序和固件是 **Dell/Canonical/Broadcom 的专有** 组件，此处重新发布仅为了方便硬件拥有者。这些 二进制文件没有开源许可。如果你发布了分支版本，建议**仅** 分发补丁脚本 + `build_from_upstream.sh`，让用户自行从 Canonical 的 OEM 仓库中拉取原始 二进制文件。本仓库中的补丁、脚本和文档 基于 MIT 许可证发布。 ## 致谢 在 Dell Latitude 7490 上使用 `radare2` + `pyusb` 从自带的 `.so` 文件逆向工程得出。USB 传输的底层基础受到 [`jacekkow/controlvault2-nfc-enable`](https://github.com/jacekkow/controlvault2-nfc-enable) 中 NFC 相关工作的启发。

标签：C2日志可视化, Cutter, Dell硬件, Linux驱动, 指纹识别, 生物识别, 系统配置, 逆向工具