gpasskey

.. image:: https://gitlab.com/renich/gpasskey/-/raw/master/assets/logo.svg :width: 140px :align: center :alt: gpasskey logo

面向 Linux 的集中式加密身份安全飞地（enclave）。

.. caution::

预 Alpha 软件——使用风险自负！

尽管有发布版本号，gpasskey 目前仍是实验性的预 Alpha 软件，正在进行快速的架构开发。加密方案、保险库格式和协议桥可能会在不保证向后兼容的情况下发生变化。

密钥与数据丢失风险高：请务必记录并安全保管您的 24 词 BIP39 恢复助记词。
保留备用双因素认证：在为生产账户注册虚拟 FIDO2 安全密钥时，请始终配置备用 2FA 方式（如 TOTP 或备份恢复码）。
无任何担保：根据 GNU GPLv3 许可证，本软件严格按“原样”提供，不附带任何形式的担保。

概述

gpasskey 提供硬件支撑的安全飞地，将私钥存储在加密保险库中。它充当多协议桥，支持 SSH Agent、age 加密插件协议，以及 GnuPG 提交签名模拟。

主要特性

多协议支持：
- FIDO2 / CTAP2 通行密钥：通过 /dev/uhid 模拟虚拟 USB 安全密钥，用于原生浏览器（Firefox、Chrome、Chromium）及操作系统的 Passkey 认证。
- SSH Agent：兼容 OpenSSH 的 agent 协议。
- age-plugin：原生支持 age（v1）文件加密。
- GnuPG 桥：模拟 GPG CLI，实现无缝的 Git 提交签名与验证。
硬件支撑的安全：私钥使用 AES-256-GCM 加密，主要密封至 TPM 2.0 并带 SRK 缓存。
加密 PIN 绑定与 UV 缓存：每次操作都绑定到由 PIN 派生的子密钥，并在锁定内存（mlock）中提供 15 秒的安全会话缓存。
Argon2id KDF：用于主口令、恢复和子密钥的内存困难型密钥派生。
暴力破解防护：对失败的授权尝试自动进行指数退避。
智能 UI 路由：自动检测会话类型（图形界面 vs. TTY）以决定授权提示方式。
安全内存：使用 mmap/mlock 和“封装并清除”（Wrap and Clear）策略，防止密钥材料泄漏到交换分区或 GC 堆。
身份管理：健壮的 CLI（gpasskey-cli），用于保险库管理和加密机密管理。

TPM 2.0 集成

gpasskey 通过 TPM 2.0 提供硬件支撑的安全性。这确保您的主密钥绝不会以未加密形式离开 TPM，并且与系统的启动状态绑定。

要求


* 兼容 TPM 2.0 的设备（开发环境可使用 ``swtpm``）。
* 系统已安装 ``tpm2-tools``。

初始化

当您创建新身份时，TPM 存储会自动初始化。要验证 TPM 状态：

.. code-block:: bash

gpasskey-cli status

使用方法


初始化后，守护进程会透明地使用 TPM。所有敏感数据都密封至 **PCR 0**（核心系统固件）和 **PCR 7**（安全启动状态）。固件或安全启动配置的任何修改都会阻止保险库解锁，从而防范离线攻击和未经授权的操作系统篡改。

快速入门
-----------

为您的用户账户构建并安装（推荐，非 root）::

   make clean && make all
   make install-user   # Installs to ~/.local/bin, ~/.config/systemd/user, ~/.local/share/dbus-1

或进行系统级安装（需要 root）::

   sudo make install   # Installs to /usr/local/bin

启用并启动 socket 激活::

   systemctl --user enable --now gpasskey-ssh.socket gpasskey-gpg.socket

初始化您的保险库并验证状态::

   gpasskey-cli status
   # Identities are enrolled automatically on first use by clients 
   # (WebAuthn passkeys, SSH, age, GPG) or via the portal API.

在浏览器中使用 WebAuthn 通行密钥::

   # Open Firefox or Chrome, go to https://webauthn.io/
   # Click "Register" -> enter your PIN in the gpasskey prompt -> Passkey is created!
   # Click "Authenticate" -> enter your PIN -> Instant login verified!

管理 TPM 支撑的配置存储中的加密机密::

   gpasskey-cli set-secret my-api-key "super-secret-value"
   gpasskey-cli get-secret my-api-key

文档与规范
------------------------------

我们全面的工程文档按模块化的规范、架构记录和路线图组织：

* **功能规范**：`功能规范索引`_ — 定义用户需求和授权模型。
* **技术蓝图**：`技术规范索引`_ — 详细的 Go 架构、加密原语和飞地设计。
* **架构决策记录（ADR）**：`ADR 索引`_ — 架构、加密和安全决策的不可变日志。
* **API 与线路协议**：`API 规范索引`_ — 管理 socket、D-Bus 门户和桥接线路模式。
* **项目执行路线图**：`路线图索引`_ — 分阶段的工程时间线和里程碑交付物。

用户指南

用户快速入门_ - 5 分钟内上手。
安装指南_ - 详细的构建、udev 和 systemd 配置。
安全指南_ - 硬件 TPM 2.0 安全飞地及“封装并清除”内存隔离。
配置指南_ - 环境变量和服务选项。

.. _功能规范索引: docs/functional/spec.rst .. _技术规范索引: docs/technical/spec.rst .. _ADR 索引: docs/adrs/index.rst .. _API 规范索引: docs/api/spec.rst .. _路线图索引: docs/project/roadmap.rst .. _用户快速入门: docs/user/quickstart.rst .. _安装指南: docs/user/installation.rst .. _安全指南: docs/user/security.rst .. _配置指南: docs/user/configuration.rst

我们正在规划的内容（第 7 阶段）

我们目前正在规范和架构设计 第 7 阶段：可插拔多因素与多方仲裁引擎：

流式任意文件哈希器：将任何文件（从一首短诗到 100GB 的音频母带 FLAC 或图像）用作授权因素，内存消耗恒定 :math:\mathcal{O}(1)（:math:\le 64\,\text{KB} 缓冲区）。
多方仲裁（“可口可乐配方”）：基于 :math:\text{GF}(2^8) 的 密钥封装 Shamir 秘密共享，带 HMAC 验证标签，实现 :math:k-of-:math:n 拆分密钥授权。
硬件与生物识别：实体 YubiKey（Slot 2 HMAC-SHA1）、实体 FIDO2 密钥（hmac-secret）以及 Linux 生物识别（fprintd）。
动态因素重密钥：原子化的内存内重新加密（gpk rekey），无需重新创建密钥即可即时切换身份的因素策略。
CLI 现代化：将命令行界面精简为规范的 gpk（/usr/local/bin/gpk）。
桌面自动解锁：与 Freedesktop Secret Service（org.freedesktop.secrets）无缝集成。

完整规范请参阅 第 7 阶段路线图_ 和 ADR-006_。

.. _第 7 阶段路线图: docs/project/roadmaps/phase-7-pluggable-factors.rst .. _ADR-006: docs/adrs/2026-08-25-pluggable-auth-factors.rst

组件

gpasskeyd：核心安全飞地与虚拟 USB CTAP2/FIDO2 安全密钥守护进程。
gpasskey-cli：用于保险库管理和加密配置的管理工具。
age-plugin-gpasskey：age 加密工具的插件。
gpasskey-gpg：兼容 GnuPG 的签名与验证模拟桥。
gpasskey-ui：用于 PIN 输入的图形辅助程序。

开发

运行单元测试::

make test

运行完整的 Go 原生集成测试套件（需要 swtpm）::

make integration-test

支持与捐赠

如果您觉得 gpasskey 有用并希望支持其持续开发，欢迎通过 Liberapay 捐赠：

.. image:: https://liberapay.com/assets/widgets/donate.svg :target: https://liberapay.com/Renich/donate :alt: Donate using Liberapay

许可证

本项目采用 GNU 通用公共许可证 v3.0 或更高版本授权。详情请参阅 LICENSE 文件。

gpasskey

最受欢迎

gpasskey

概述

主要特性

TPM 2.0 集成

我们正在规划的内容（第 7 阶段）

组件

开发

支持与捐赠

许可证