PHILIPPDEV5396/libfprint-egis0576

# EgisTec EH576 (`1c7a:0576`) 的 libfprint 驱动 一个原生的 Linux [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint) 驱动，适用于 **EgisTec (LighTuning) EH576** 指纹传感器 —— 这是一款主机端匹配的 图像传感器，搭载于多款笔记本电脑中，但**没有官方的 Linux 驱动**。 有了这款驱动，该传感器可以真正发挥作用：在原生的 GNOME/KDE 环境下，支持 `fprintd` 录入，以及通过 PAM 进行指纹 登录 / `sudo` / 解锁屏幕。 ## 状态 | | | |---|---| | 录入 / 验证 / 识别 | ✅ 通过 `fprintd` 正常工作 | | PAM 登录，`sudo`，解锁 | ✅ 正常工作 (`sufficient`，保留密码回退) | | 跨重启匹配 | ✅ (每次启动进行平场校正) | | 安全性 | 真实手指匹配；其他手指 (包括同手相邻手指) 在严格阈值下被拒绝 | | 验证基于 | **单个**实体设备 (Lenovo Yoga 7 14ARB7, Fedora)。参见下文的“通用性”。 | ## 关于该传感器简介 EH576 是一款位于 **TLS-PSK** 安全通道 (主机作为 TLS *服务器*，设备作为客户端) 之后的 小型 **70×57 px** 电容/光学图像传感器。 握手完成后，它会通过简单的 `EGIS`/`SIGE` 命令协议进行通信；主机 提取原始帧，并在软件中进行特征提取 + 匹配。 本驱动原生实现了整个链路：TLS-PSK (OpenSSL) → 传感器初始化 → 帧捕获 → 每次启动的平场校正 + 预处理 → Egis 的提取器/匹配器 → libfprint 录入/验证。设计细节位于源码注释和 [`PROVENANCE.md`](PROVENANCE.md) 中。 ## 通用性 (它能在*其他* EH576 设备上工作吗？) 该驱动在设计上做到了**设备无关**，并且所有针对特定设备的 依赖都在运行时处理，而不是硬编码在其中： - **PSK / 初始化 / 协议** — 基于**型号**的常量，对每台 EH576 都相同。 - **增益 (Gain)** — 每个设备在打开时会运行一次闭环校准 (在细粒度增益寄存器上进行二分查找，以达到固定的无手指曝光目标)，因此每个单元都会自动调整。 - **固定模式噪声** — 通过每次启动时为每个设备新捕获的主机端平场数据来移除。 - **片上背景/vdm** — 中和至型号级别的常量，因此不会嵌入任何 单一设备的校准数据。 **诚实的警告：** 以上所有内容均仅在作者的单台设备上经过验证。如果没有 第二台物理 EH576 设备，就无法*证明*其具备真正的跨设备操作能力。如果你有 这样一台设备，**请带着你的测试结果提交一个 issue** —— 无论成功或失败。在拥有净室匹配器 (clean-room matcher) 之外，这份报告是你所能贡献的最有价值的信息。 ## 构建 libfprint 驱动会被编译*进* `libfprint-2.so` (它不是一个可动态加载的 模块)，因此这里会构建一个包含该驱动的完整 libfprint。它**不会** 重新编译 `fprintd` —— 原生的系统守护进程会通过未更改的 ABI 加载新库。 ### 1. 安装构建依赖 你需要常见的 libfprint 构建栈，以及 **OpenSSL/libcrypto ≥ 3.0**： - **Fedora:** `sudo dnf install git meson ninja-build gcc pkgconf-pkg-config glib2-devel libgusb-devel openssl-devel gobject-introspection-devel nss-devel systemd-devel libgudev-devel pixman-devel cairo-gobject-devel` - **Arch:** `sudo pacman -S --needed git meson ninja gcc pkgconf glib2 libgusb openssl gobject-introspection nss systemd-libs libgudev pixman cairo` - **Debian/Ubuntu:** `sudo apt install git meson ninja-build build-essential pkg-config libglib2.0-dev libgusb-dev libssl-dev libgirepository1.0-dev libnss3-dev libsystemd-dev libgudev-1.0-dev libpixman-1-dev libcairo2-dev` - **openSUSE:** `sudo zypper install git meson ninja gcc pkgconf glib2-devel libgusb-devel libopenssl-devel gobject-introspection-devel mozilla-nss-devel systemd-devel libgudev-1_0-devel pixman-devel cairo-devel` ### 2. 编译 + 安装 ``` ./install.sh ``` 这会克隆 libfprint **1.94.10**，应用驱动，构建完整的默认 驱动集 (这样你拥有的任何其他指纹硬件仍能继续工作)，并安装 到 `/usr/local` (可通过 `PREFIX=/usr ./install.sh` 覆盖)。 **确保 fprintd 加载的是*这个* libfprint**，而不是发行版自带的： ``` ldconfig -p | grep libfprint-2 # should point at your PREFIX sudo systemctl restart fprintd ``` 如果它仍然指向发行版的副本，请将 `PREFIX/lib` (或 `lib64`) 添加到 `/etc/ld.so.conf.d/`，运行 `sudo ldconfig`，然后重启 fprintd。(使用 `PREFIX=/usr` 安装会直接替换发行版的库 —— 这是最简单的做法，但发行版更新 可能会覆盖它，因此你需要在 libfprint 更新后重新运行一次 `install.sh`。) ## 录入 ``` fprintd-enroll # or: Settings → Users → Fingerprint Login fprintd-verify # test it ``` **带覆盖率地录入：** 在录入阶段，有意在不同的位置 (中心、上/下、左/右、轻微旋转) 按下同一个手指。在 这么小的传感器上，仅从一个位置构建的模板匹配效果会很差。 ## 启用指纹认证 ### PAM 指纹认证的工作原理 (请先阅读) 启用指纹登录意味着要在 PAM 的 **auth** 栈中添加一行： ``` auth sufficient pam_fprintd.so ``` - 它必须位于 **`pam_unix.so`** (密码模块) **之上**。PAM 会自上而下评估 auth 模块。 - **`sufficient`** = 如果指纹匹配成功，认证立即成功；如果它 失败、超时或没有录入任何内容，PAM 会**向下转入 (fall through)** 密码认证。 这使得你的密码成为一个有效的回退方案。 - **不要为** `pam_fprintd` **使用 `required`**，除非你*想要* 指纹+密码 (双因素) 认证，并且接受缺失或损坏的读卡器可能会将你锁在外面的风险。对于普通的“指纹或密码”模式，请使用 `sufficient` 并保留 `pam_unix` 这行。 - `fprintd` 在所有发行版上都是 **D-Bus/systemd 激活** 的 —— 它会按需启动，因此通常不需要 `systemctl enable --now fprintd`。 - **密钥环 (Keyrings) 仍然需要你的密码。** GNOME Keyring / KWallet 会在登录时通过密码解锁，因此仅凭指纹登录时仍会提示输入一次密钥环密码。 ### Fedora ``` sudo authselect enable-feature with-fingerprint ``` (`fprintd-pam` 提供了该模块。) 将 `pam_fprintd.so` 接入用于登录、sudo 和显示管理器的 system-auth / password-auth 栈中。 ### Arch Linux (以及 Manjaro, EndeavourOS, …) - **软件包：** `fprintd` (提供守护进程**和** `pam_fprintd.so`) + `libfprint`。 - Arch 没有 PAM 助手 —— 需手动编辑。在 `/etc/pam.d/system-local-login` 的 **auth 部分的顶部** 添加： auth sufficient pam_fprintd.so auth include system-login 对于 `sudo`，在 `/etc/pam.d/sudo` 的 auth 部分顶部添加相同的 `auth sufficient pam_fprintd.so`。 - GDM 和 KDE/Plasma 具有内置的指纹处理功能 (无需编辑 `kde-fingerprint`)。 - **在编辑 PAM 时保持一个打开的 root shell**，这样即使出现错误也不会将你锁在外面。 - 参考：[ArchWiki – fprint](https://wiki.archlinux.org/title/Fprint) ### Debian / Ubuntu (以及 Mint, Pop!\_OS, …) ``` sudo apt install fprintd libpam-fprintd sudo pam-auth-update --enable fprintd # or run `sudo pam-auth-update` and tick the box ``` 安装 `libpam-fprintd` 会*注册*该配置文件，但**不会**启用它 —— 上面的命令会将 `auth sufficient pam_fprintd.so` 插入到 `/etc/pam.d/common-auth` 中 (被 login、sudo 和 DM 包含)。如果由于本地的 PAM 编辑而拒绝执行，请添加 `--force`；稍后若要禁用，请使用 `--remove fprintd`。 参考：[Debian Wiki – 指纹认证](https://wiki.debian.org/SecurityManagement/fingerprint%20authentication) ### openSUSE (Tumbleweed / Leap) ``` sudo zypper install fprintd fprintd-pam sudo pam-config -a --fprintd # disable later: pam-config -d --fprintd ``` 将 `auth sufficient pam_fprintd.so` 添加到由 `pam-config` 管理的通用 auth 栈中。 优先使用 `pam-config` 而不是手动编辑 (它会重新生成这些文件)。 参考：[openSUSE SDB – 使用指纹认证](https://en.opensuse.org/SDB:Using_fingerprint_authentication) ## 易用性与安全性说明 - **用力、平整、居中按下，并保持约 2 秒。** 验证会对手指按下时的每一帧进行评分 并取最佳值；在 70×57 传感器上的轻微或短暂触碰 得分为零。 - 匹配**阈值非常严格**，且在设计上不允许用户调整 —— 优先考虑的是 拒绝冒名者 (包括同手相邻的手指)，而不是追求极致的便利性。 - 模板由 fprintd 存储在 `/var/lib/fprint/` 下，受文件系统权限保护 (与所有其他的 libfprint 驱动一样)。 - 在任何实质性改变捕获条件的情况发生后，请重新录入 (增益校准在每次启动时是确定的，因此正常的重启没有问题)。 ## 故障排除 - **`fprintd` 仍在使用旧驱动 / 找不到设备：** 确认 `ldconfig -p | grep libfprint-2` 指向你的 `PREFIX`，然后 `sudo systemctl restart fprintd`。 - **录入“无法捕获” (fails to capture)：** 请用力按下并保持；确保在最初的 ~2 秒内传感器上没有手指 (此时会运行基线和增益校准)。 - **在曾成功运行后验证总是失败：** 带覆盖率地重新录入 (参见“录入”)。 - **调试日志：** `sudo G_MESSAGES_DEBUG=all fprintd` (请先停止该服务) 或 `journalctl -u fprintd -f`。 ## 许可证与法律声明 原始驱动代码：**LGPL-2.1-or-later** (参见 [`LICENSE`](LICENSE))，与 libfprint 保持一致。逆向工程部分的代码以及完整的法律声明细节： [`PROVENANCE.md`](PROVENANCE.md)。原始的 Egis Windows 驱动程序及其 反编译代码**不**包含在内，也不得在此处提交。 ## 致谢 由该仓库作者逆向工程并移植到 libfprint，旨在 使已经拥有的硬件能在 Linux 上使用。基于出色的 [libfprint](https://gitlab.freedesktop.org/libfprint/libfprint) 和 `fprintd` 构建。

标签：libfprint, 安全测试工具, 客户端加密, 指纹识别驱动, 生物识别, 硬件互操作性, 预握手