* **TPM 2.0**: Hardware TPM 2.0 device (``/dev/tpmrm0`` or ``/dev/tpm0``), or ``swtpm`` for software-emulated development.
* **Linux Kernel with /dev/uhid**: Native kernel support for user-space HID devices (enabled by default in modern distributions) to support virtual FIDO2/CTAP2 browser passkeys.

Runtime Dependencies

* **Go 1.26** or later
* **GNU Make**
* **swtpm** (optional, required to execute the full integration test suite)

Package Manager Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Fedora/RHEL/AlmaLinux:

.. code-block:: bash

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

On Arch Linux:

.. code-block:: bash

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

On Debian/Ubuntu:

.. code-block:: bash

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

Quick Start
-----------

Build and install for your user account (recommended, non-root):

.. code-block:: bash

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

Or install system-wide (requires root):

.. code-block:: bash

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

Enable & start socket activation:

.. code-block:: bash

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

Initialize your vault and verify status:

.. code-block:: bash

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

Pre-authenticate the cache for automated scripts or headless sessions:

.. 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 Passkeys in Browser:

.. 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!

Manage encrypted secrets in the TPM-backed config store:

.. code-block:: bash

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

Documentation & Specifications
------------------------------

Our comprehensive engineering documentation is organized into modular specifications, architecture records, and roadmaps:

* **Functional Specifications**: `Functional Spec Index`_ — Defines user requirements and authorization models.
* **Technical Blueprints**: `Technical Spec Index`_ — Detailed Go architecture, crypto primitives, and enclave designs.
* **Architecture Decision Records (ADRs)**: `ADR Index`_ — Immutable log of architectural, crypto, and security choices.
* **API & Wire Protocols**: `API Spec Index`_ — Management socket, D-Bus portals, and bridge wire schemas.
* **Project Execution Roadmap**: `Roadmap Index`_ — Phased engineering timelines and milestone deliverables.

User Guides
~~~~~~~~~~~

* `User Quick Start`_ - Get up and running in 5 minutes.
* `Installation Guide`_ - Detailed build, udev, and systemd setup.
* `OpenSSH Guide`_ - OpenSSH agent integration, jump hosts, and FIDO2 keys.
* `GnuPG & Git Signing Guide`_ - OpenPGP key management and Git commit signing.
* `Pluggable Factors Guide`_ - Keyfiles, YubiKeys, biometrics, and Shamir quorums.
* `Security Guide`_ - Hardware TPM 2.0 enclave and "Wrap and Clear" memory isolation.
* `Configuration Guide`_ - Environment variables and service options.
* `CLI Reference`_ - Full command-line interface documentation.

.. _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

Pluggable Factors & Multi-Party Quorum (Phase 7)
------------------------------------------------

**Phase 7: Pluggable Multi-Factor & Multi-Party Quorum Engine** delivers:

* **Streaming Arbitrary File Hasher**: Use any file (from a short text poem to a 100GB audio master FLAC or image) as an authorization factor with constant :math:`\mathcal{O}(1)` memory consumption (:math:`\le 64\,\text{KB}` buffer).
* **Multi-Party Quorum ("The Coca-Cola Recipe")**: **Key-Wrapped Shamir Secret Sharing** over :math:`\text{GF}(2^8)` with HMAC verification tags, enabling :math:`k`-of-:math:`n` split-key authorization.
* **Hardware & Biometrics**: Physical YubiKey (Slot 2 HMAC-SHA1), physical FIDO2 keys (``hmac-secret``), and Linux biometrics (``fprintd``).
* **Dynamic Factor Re-Keying**: Atomic in-memory re-encryption (``ge rekey``) to switch an identity's factor policy on the fly without recreating keys.
* **CLI Modernization**: Streamlined command-line interface into canonical ``ge``.
* **Desktop Auto-Unlock**: Seamless integration with the Freedesktop Secret Service (``org.freedesktop.secrets``).

See `Phase 7 Roadmap`_ and `ADR-006`_ for full specifications.

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

Components
----------

* **genclaved**: The core security enclave and virtual USB CTAP2/FIDO2 security key daemon (``man 8 genclaved``).
* **ge**: Primary command-line tool for vault administration, OpenSSH/GnuPG key generation, and encrypted configuration (``man 1 ge``).
* **age-plugin-ge**: Plugin for the ``age`` encryption tool (``man 1 age-plugin-ge``).
* **genclave-gpg**: Emulation bridge for GnuPG-compatible signing and verification (``man 1 genclave-gpg``).
* **genclave-ui**: Graphical helper for PIN entry (``man 1 genclave-ui``).

Development
-----------

Run the unit tests:

.. code-block:: bash

   make test

Run the full Go-native integration suite (requires ``swtpm``):

.. code-block:: bash

   make integration-test

Support & Donations
-------------------

If you find **gEnclave** useful and would like to support its ongoing development, consider donating via Liberapay:

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

License
-------

Copyright 2026 EVALinux

This project is licensed under the GNU General Public License v3.0 or later.
See LICENSE file for details.