Yumeii0/goodix-27c6-5125-chicagohs

# Goodix 27c6:5125 ChicagoHS Linux 指纹驱动 本项目中使用了人工智能来加速协议分析、实现、测试、调试和文档编写。硬件验证和最终的工程决策均基于真实硬件进行。 该项目为经过测试的 Goodix USB 指纹读取器提供了实验性的原生 Linux 支持，并与以下组件集成： - `libfprint` - `fprintd` - PAM - systemd 安装后，它不需要 Wine、Windows 虚拟机、供应商 DLL 或任何其他专有运行时组件。 本项目与 Goodix 或 Huawei 没有任何关联、认可或支持关系。 ## 测试过的硬件 开发与实际测试基于以下设备进行： ``` Laptop: Huawei MateBook D15 Fingerprint vendor: Goodix USB ID: 27c6:5125 Sensor family: ChicagoHS Expected chip ID: 0x2504 Expected internal profile: 0x0c Capture geometry: 64 x 80 pixels Raw frame size: 10240 bytes ``` 使用以下命令检查已连接的 USB 设备： ``` lsusb ``` 输出结果必须包含： ``` 27c6:5125 ``` 此 USB 检查仅是第一道过滤。理论上，其他设备也可能暴露相同的 USB ID，但却使用了不同的内部传感器系列、固件、协议、几何尺寸、TLS 配置或指纹算法。 ## ChicagoHS 兼容性检查 安装程序不仅依赖 USB 产品 ID。 在安全安装或重用设备 PSK 后，它会暂时停止 `fprintd` 并通过原生实现直接打开传感器。在进行任何系统驱动更改之前，它会验证受支持的 ChicagoHS 配置应具备的预期行为： - USB ID `27c6:5125` - 预期的 USB 接口和端点 - Chip ID `0x2504` - 预期的内部配置 `0x0c` - ChicagoHS OTP 布局和可用的 DAC 校准数据 - ChicagoHS 传感器初始化和配置序列 - 有效的 TLS-PSK 传感器身份 - 预期的 `64 x 80` 几何尺寸 - 预期的 `10240` 字节原始帧大小 在此兼容性探测过程中不会捕获任何指纹图像。 成功的探测会输出： ``` GOODIX_BETA_CHICAGOHS_PROBE=PASS family:ChicagoHS GOODIX_BETA_HARDWARE_PROFILE=PASS family:ChicagoHS ``` 如果探测失败，安装程序将在替换系统 `libfprint` 配置之前停止。 该设备并未暴露标准化的、人类可读的 USB 字符串来作为制造商认证的系列证书。因此，探测程序会验证与本 ChicagoHS 实现的精确协议及硬件兼容性，而不是仅仅信任 USB ID。 ## 当前状态 以下功能在经过测试的 Huawei MateBook D15 上正常工作： - 原生 USB 通信 - 加密的 TLS-PSK 传感器会话 - 严格的 ChicagoHS 硬件兼容性探测 - 自动手指触摸检测 - 自动手指抬起检测 - 原生图像预处理 - 原生指纹特征提取 - 原生录入 - 原生指纹匹配 - 通过 `fprintd` 进行持久化存储 - AES-256-GCM 加密的原生模板 - 十二次扫描的多样化录入 - 通过 `fprintd` 进行指纹验证 - 可选的 `sudo` 指纹认证 - 密码回退前的三次指纹尝试 这仍是测试版软件。它尚未经过生产规模的生物识别认证或独立的安全审计。 ## 不支持的硬件 请勿为以下设备安装此驱动： - Goodix Milan 传感器 - 其他具名的 Goodix 传感器系列 - 具有其他 USB ID 的设备 - 仅共享 Goodix 供应商 ID 的设备 - 未通过 ChicagoHS 兼容性探测的 `27c6:5125` 设备 为其他传感器系列添加支持需要单独进行协议分析、硬件验证、捕获处理、预处理和校准。重命名设备或绕过兼容性探测并不能使其他系列变得安全或兼容。 ## 支持的发行版 自动安装程序目前针对： - Arch Linux - CachyOS - 具有足够兼容性的基于 Arch 的发行版 安装程序需要： - `pacman` - systemd - PAM - `fprintd` 其他 Linux 发行版在手动调整后也许可以运行，但目前不被自动安装程序支持。 ## 要求 您需要： - 受支持的 Goodix ChicagoHS `27c6:5125` 读取器 - 属于该传感器的正确 64 位十六进制 PSK - 兼容 Arch 的 Linux 安装 - 安装期间的互联网访问权限 - 具有 `sudo` 权限的普通用户账户 请勿在现有的 root shell 中运行安装程序。 ## 获取设备 PSK 传感器使用特定于设备的 32 字节 PSK 进行加密通信会话。如果没有正确的 PSK，Linux 驱动程序将无法与读取器通信。 本仓库不包含 PSK，且绝不应被发布。 ### 推荐方法 从同一台计算机上正常工作的 Windows 安装中提取现有的 PSK。 此方法读取官方 Goodix Windows 驱动程序已使用的 PSK。它不会故意重置传感器 PSK，也不需要删除现有的 Windows 指纹录入。 ### Windows 准备工作 1. 在包含指纹读取器的计算机上安装或启动 Windows。 2. 安装由 Windows Update 或笔记本制造商提供的官方 Goodix 指纹驱动程序。 3. 打开 Windows 设置。 4. 配置 Windows Hello 指纹认证。 5. 录入至少一根手指。 6. 确认指纹认证在 Windows 中有效。 7. 找到以下文件： ``` Goodix_Cache.bin ``` 它的位置可能因 Windows 驱动程序版本和笔记本制造商而异。 要搜索它，请以管理员身份打开 PowerShell 并运行： ``` Get-ChildItem -Path C:\ -Filter Goodix_Cache.bin -File -Recurse -Force -ErrorAction SilentlyContinue ``` 搜索可能需要几分钟。 ### 运行提取脚本 本仓库包含： ``` windows/psk_extractor.ps1 ``` 在包含脚本的目录中打开 PowerShell 并运行： ``` Set-ExecutionPolicy -Scope Process Bypass .\psk_extractor.ps1 ``` 执行策略更改仅适用于当前的 PowerShell 进程。 该脚本会要求输入 `Goodix_Cache.bin` 的完整路径。 示例： ``` C:\path\to\Goodix_Cache.bin ``` 提取成功后，它会在 Windows 桌面上创建： ``` goodix_psk.txt ``` 该文件必须包含确切的 64 个十六进制字符，代表 32 字节的 PSK。 ### 保护 PSK 请将 PSK 视为机密。 绝不要： - 将其上传到 GitHub - 将其包含在公开的 issue 中 - 将其包含在日志中 - 在截图中分享它 - 将其存储在此仓库中 - 将其发送给其他用户 - 使用从另一台计算机提取的 PSK 请通过私密方法将 PSK 传输到 Linux。 在安装期间，仅在提示时提供这 64 位十六进制字符。 确认 Linux 驱动程序正常工作后： 1. 保留一份加密的脱机副本以备将来安装。 2. 删除不必要的明文副本。 3. 清空 Windows 回收站。 4. 从剪贴板历史记录、临时笔记和云同步文本文件中移除该 PSK。 提取助手适用于经过测试的 Windows Goodix 缓存格式。其他 Goodix 设备或截然不同的驱动程序版本可能使用其他格式。 ## 安装说明 解压或克隆完整的仓库并运行： ``` ./scripts/install.sh ``` 安装程序将： 1. 验证 USB 设备 `27c6:5125` 是否已连接。 2. 安装所需的 Arch Linux 软件包。 3. 重用现有的有效 PSK 或通过隐藏的终端输入请求一个。 4. 验证 PSK 是否恰好包含 64 位十六进制字符。 5. 将 PSK 存储在： ``` /etc/goodix-27c6-5125/psk.hex ``` 6. 将其所有者和权限设置为： ``` root:root 0600 ``` 7. 在严格的编译器警告下构建原生实现。 8. 运行原生的脱机自检。 9. 执行严格的 ChicagoHS 硬件兼容性探测。 10. 如果探测失败，则中止安装且不安装系统驱动程序。 11. 下载并验证锁定的 `libfprint 1.94.10` 源码。 12. 将 Goodix ChicagoHS 驱动程序添加到 `libfprint`。 13. 构建自定义运行时并将其安装到以下位置： ``` /opt/goodix-27c6-5125 ``` 14. 配置 `fprintd.service` 以加载自定义的 `libfprint`。 15. 重用现有的录入或开始新的录入。 16. 验证录入的指纹。 17. 安装通用的英文 PAM 包装器。 18. 为 `sudo` 配置三次指纹尝试。 19. 保留密码认证作为回退方式。 安装程序不会在其日志中打印 PSK 值。 ## 十二次扫描录入 录入会要求您将选定的手指放在传感器上十二次。 程序**不会**告诉您每次扫描应该使用手指的哪个区域。您必须自行改变放置方式。 在这十二次扫描中，请使用同一根手指的不同区域和角度。例如，包括中心、侧面、上部、下部、略微旋转的放置、局部边缘放置，以及日常使用中常见的自然位置。 您可以按任何顺序使用任何区域，并根据需要多次重复某个位置。但是，如果所有十二次扫描都完全在相同的中心小区域进行，当以后只有手指的侧面、顶部或底部接触传感器时，可能会降低识别率。 所有十二次扫描请使用同一根手指。 每次扫描被接受后： 1. 完全移开手指。 2. 让传感器短暂留空。 3. 使用另一个位置或角度再次放置同一根手指。 被拒绝的扫描不会推进录入进度。请完全移开手指并重试。 ## 常用命令 ### 检查安装 ``` ./scripts/status.sh ``` 这将检查： - 受支持的 USB 设备检测 - PSK 文件的所有者和权限 - 自定义 `libfprint` 安装 - systemd 配置 - 活动的 `fprintd` 服务 - D-Bus 设备发现 - 现有的指纹录入 - `sudo` PAM 集成 它不会打印 PSK 或指纹模板内容。 ### 运行源码自检 ``` ./scripts/selftest.sh ``` ### 验证已录入的手指 ``` ./scripts/verify.sh ``` ### 录入另一根手指 ``` ./scripts/enroll.sh ``` ### 移除自定义驱动程序 ``` ./scripts/uninstall.sh ``` 这会移除自定义运行时和托管的 PAM 集成，同时保留已安装的 PSK 和加密的指纹录入。 ### 恢复到全新安装状态 ``` ./scripts/fresh-reset.sh ``` 这将移除： - 自定义 `libfprint` - systemd drop-in 配置 - 托管的 `sudo` PAM 配置 - Goodix 指纹录入 - 已安装的设备 PSK - 本地构建和下载缓存 在运行全新重置之前，请确保您拥有正确 PSK 的另一份副本。 该脚本不会移除不相关的系统软件包或个人文件。 ## 运行时位置 安装程序使用以下位置： ``` /opt/goodix-27c6-5125/ Custom libfprint runtime and PAM wrapper /etc/goodix-27c6-5125/psk.hex Device PSK stored as root:root with mode 0600 /etc/systemd/system/fprintd.service.d/ Managed fprintd service configuration /var/lib/fprint/ fprintd fingerprint enrollment database /var/lib/goodix-27c6-5125/beta/ Saved PAM state used for safe recovery and uninstall /etc/pam.d/sudo Managed sudo fingerprint authentication block ``` ## 安全模型 ### 传感器通信 与传感器的通信使用设备 PSK 和加密的 TLS 会话。 ### 指纹数据 驱动程序不会故意将以下内容保存到磁盘： - 原始传感器帧 - 灰度指纹图像 - PNG 或 JPEG 指纹图像 - 明文原生模板 - 明文原生特征记录 通过 `fprintd` 存储的原生指纹模板使用以下方式保护： - AES-256-GCM - HKDF-SHA256 - 随机盐 - 随机 nonce - 已认证的 GCM 标签 模板加密密钥是从设备 PSK 派生的。 ### PSK 存储 PSK 存储在： ``` /etc/goodix-27c6-5125/psk.hex ``` 具有以下配置： ``` root:root 0600 ``` 普通用户不应能够读取它。 ### 密码回退 `sudo` 的指纹认证是一种附加的认证方式。密码认证仍然可用。 在身份验证过程继续进入正常的密码路径之前，允许进行三次指纹尝试。 ### 安全限制 - 拥有 root 权限的攻击者可以读取已安装的 PSK。 - 获取了 PSK 和加密指纹数据库的脱机攻击者也许能够解密原生模板。 - PSK 当前未受 TPM 封装保护。 - 独立的活体检测或呈现攻击检测尚未得到验证。 - 指纹模板是永久性的敏感生物识别数据。 - 指纹不能像密码那样被替换。 - 当前的匹配器阈值是实验性的。 - 该实现尚未经过认证的 FAR 或 FRR 测试。 - 指纹认证不能替代全盘加密。 - 指纹认证不能替代强账户密码。 有关详细的威胁模型，请参见 `SECURITY.md`。 ## 仓库内容 本仓库包含构建、测试、安装、维护和记录该驱动程序所需的文件： - 原生 USB 通信 - TLS 会话实现 - Goodix 协议处理 - ChicagoHS 兼容性探测 - 传感器捕获 - 手指存在检测 - 图像预处理 - 特征提取 - 录入 - 指纹匹配 - 模板加密 - Libfprint 集成 - PAM 集成 - 安装和恢复脚本 - 脱机自检 - Windows PSK 提取助手 - 项目文档 本仓库不包含： - 设备 PSK - 用户指纹模板 - 原始生物识别捕获数据 - 私人安装日志 - Windows 驱动程序二进制文件 - 专有的 Goodix DLL 文件 - Wine 运行时依赖项 - 历史开发存档 旧的 Phase 包 - 本地构建输出 - 下载缓存 部分源码注释包含逆向工程的功能标签和算法名称。这些注释保留了对独立重实现行为的技术可追溯性。 ## 故障排除 运行： ``` ./scripts/status.sh ``` 然后检查以下位置的最新日志： ``` logs/ ``` 安装程序和管理脚本会以以下形式打印最终的状态标记： ``` GOODIX_BETA_...=PASS ``` 或者： ``` GOODIX_BETA_...=FAIL ``` 配置文件不匹配或兼容性探测失败将以以下内容结束： ``` GOODIX_BETA_CHICAGOHS_PROBE=FAIL GOODIX_BETA_INSTALL=FAIL stage:chicagohs-compatibility-probe ``` 请勿针对 Milan 或其他不受支持的传感器系列绕过此失败。 以下位置提供了额外的恢复信息： ``` docs/TROUBLESHOOTING.md ``` 在发布日志之前，请检查其中是否包含私人机器信息。 切勿发布： - 设备 PSK - 来自 `/var/lib/fprint` 的文件 - 指纹模板内容 - 原始生物识别数据 ## 开发方法 本项目是一项 AI 辅助的逆向工程工作，旨在为不受支持的硬件提供 Linux 互操作性。 人工智能被用作工程工具以加速： - 逆向工程分析 - 源码实现 - 测试生成 - 日志分析 - 调试 - 文档编写 该实现通过在真实的 Huawei MateBook D15 上进行反复测试而得到验证。 本项目不分发或不需要： - 反编译的供应商源码 - Goodix Windows 二进制文件 - 专有的 Goodix DLL 文件 - Wine - Windows 运行时组件 该 Linux 实现是基于观察到的设备和软件行为独立编写的。 Goodix 和 Huawei 的名称可能是其各自所有者的商标。 ## 项目成熟度 目前的验证包括： - 原生 USB 通信 - 加密的 TLS-PSK 会话 - 严格的 ChicagoHS 兼容性探测 - 脱机协议自检 - 原生预处理和特征提取 - 录入和匹配器测试 - Libfprint 集成 - 持久化的加密模板 - 自动手指触摸和手指抬起检测 - fprintd 集成 - PAM 集成 - `sudo` 认证 - 服务重启持久化 - 全新安装工作流 - 十二次扫描的多样化录入 这并不能使该驱动程序成为经过认证的生物识别安全产品。 测试主要在一台 Huawei MateBook D15 上进行。即使在具有 USB ID `27c6:5125` 的其他计算机上，也无法保证结果。 ## 许可证 独立实现的项目源码在以下许可下分发： ``` LGPL-2.1-or-later ``` 有关完整的 GNU Lesser General Public License version 2.1 文本，请参见 `LICENSE` 文件。“或更新版本”选项由项目许可证标识符和源码声明进行声明。 该许可证仅适用于本仓库中包含的独立实现的源代码和项目材料。它不授予对专有的 Goodix 或 Huawei 软件、固件、驱动程序、DLL 文件、商标或其他第三方组件的权利。 贡献者不得提交： - 反编译的专有源代码 - 供应商二进制文件 - 专有 DLL 文件 - 设备 PSK - 指纹模板 - 原始生物识别捕获数据 - 他们无权分发的材料 第三方组件保留其原始许可证。

标签：AI合规, C2日志可视化, libfprint, PAM, 客户端加密, 指纹识别, 硬件逆向, 网络安全监控, 驱动开发