* **TPM 2.0**：硬件 TPM 2.0 设备（``/dev/tpmrm0`` 或 ``/dev/tpm0``），或用于软件模拟开发的 ``swtpm``。
* **支持 /dev/uhid 的 Linux 内核**：内核对用户空间 HID 设备的原生支持（在现代发行版中默认启用），以支持虚拟 FIDO2/CTAP2 浏览器通行密钥。

运行时依赖

* **Go 1.26** 或更高版本
* **GNU Make**
* **swtpm**（可选，运行完整集成测试套件所需）

包管理器安装
~~~~~~~~~~~~

在 Fedora/RHEL/AlmaLinux 上：

.. code-block:: bash

   sudo dnf install golang make tpm2-tools zenity pinentry wl-clipboard swtpm

在 Arch Linux 上：

.. code-block:: bash

   sudo pacman -S go make tpm2-tools zenity pinentry wl-clipboard swtpm

在 Debian/Ubuntu 上：

.. code-block:: bash

   sudo apt install golang-go make tpm2-tools zenity pinentry-curses wl-clipboard swtpm

快速开始
--------

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

.. code-block:: bash

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

或系统范围安装（需要 root）：

.. code-block:: bash

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

启用并启动套接字激活：

.. code-block:: bash

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

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

.. code-block:: bash

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

为自动化脚本或无头会话预认证缓存：

.. code-block:: bash

   # Unlock cache interactively via TTY:
   ge unlock

   # Or pre-authenticate via pipeline in scripts:
   echo "$PIN" | ge unlock --stdin

   # Purge and lock immediately when finished:
   ge lock


浏览器中的 WebAuthn 通行密钥：

.. code-block:: bash

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

在 TPM 支持的配置存储中管理加密机密：

.. code-block:: bash

   ge set-secret my-api-key "super-secret-value"
   ge get-secret my-api-key

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

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

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

用户指南
~~~~~~~~

* `User Quick Start`_ - 5 分钟内快速上手。
* `Installation Guide`_ - 详细的构建、udev 和 systemd 设置。
* `OpenSSH Guide`_ - OpenSSH 代理集成、跳板主机和 FIDO2 密钥。
* `GnuPG & Git Signing Guide`_ - OpenPGP 密钥管理和 Git 提交签名。
* `Pluggable Factors Guide`_ - 密钥文件、YubiKey、生物识别和 Shamir 法定人数。
* `Security Guide`_ - 硬件 TPM 2.0 飞地和“包装并清除”内存隔离。
* `Configuration Guide`_ - 环境变量和服务选项。
* `CLI Reference`_ - 完整的命令行界面文档。

.. _Functional Spec Index: docs/functional/spec.rst
.. _Technical Spec Index: docs/technical/spec.rst
.. _ADR Index: docs/adrs/index.rst
.. _API Spec Index: docs/api/spec.rst
.. _Roadmap Index: docs/project/roadmap.rst
.. _User Quick Start: docs/user/quickstart.rst
.. _Installation Guide: docs/user/installation.rst
.. _OpenSSH Guide: docs/user/ssh.rst
.. _GnuPG & Git Signing Guide: docs/user/gpg.rst
.. _Pluggable Factors Guide: docs/user/factors.rst
.. _Security Guide: docs/user/security.rst
.. _Configuration Guide: docs/user/configuration.rst
.. _CLI Reference: docs/user/cli.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``）。
* **动态因素重新加密**：原子内存重新加密（``ge rekey``），无需重新创建密钥即可动态切换身份的因素策略。
* **CLI 现代化**：将命令行界面精简为规范的 ``ge``。
* **桌面自动解锁**：与 Freedesktop Secret Service（``org.freedesktop.secrets``）无缝集成。

完整规范请参见 `Phase 7 Roadmap`_ 和 `ADR-006`_。

.. _Phase 7 Roadmap: docs/project/roadmaps/phase-7-pluggable-factors.rst
.. _ADR-006: docs/adrs/2026-08-25-pluggable-auth-factors.rst

组件
----

* **genclaved**：核心安全飞地和虚拟 USB CTAP2/FIDO2 安全密钥守护进程（``man 8 genclaved``）。
* **ge**：用于保险库管理、OpenSSH/GnuPG 密钥生成和加密配置的主要命令行工具（``man 1 ge``）。
* **age-plugin-ge**：``age`` 加密工具的插件（``man 1 age-plugin-ge``）。
* **genclave-gpg**：用于 GnuPG 兼容签名和验证的模拟桥接（``man 1 genclave-gpg``）。
* **genclave-ui**：用于 PIN 输入的图形化助手（``man 1 genclave-ui``）。

开发
----

运行单元测试：

.. code-block:: bash

   make test

运行完整的 Go 原生集成套件（需要 ``swtpm``）：

.. code-block:: bash

   make integration-test

支持与捐赠
----------

如果您觉得 **gEnclave** 有用，并希望支持其持续开发，请考虑通过 Liberapay 捐赠：

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

许可证
------

Copyright 2026 EVALinux

本项目根据 GNU General Public License v3.0 或更高版本许可。
详情请参见 LICENSE 文件。