Centralized, TPM 2.0 hardware-backed cryptographic identity enclave and multi-protocol bridge for Linux (FIDO2/CTAP2 WebAuthn Passkeys, OpenSSH Agent, GnuPG LibAssuan, age-plugin, encrypted config store).
.. image:: https://gitlab.com/renich/genclave/-/raw/master/assets/banner.svg :width: 100% :align: center :alt: gEnclave banner
|
.. image:: https://gitlab.com/renich/genclave/badges/master/pipeline.svg :target: https://gitlab.com/renich/genclave/-/commits/master :alt: pipeline status .. image:: https://img.shields.io/gitlab/v/release/renich/genclave?logo=gitlab&label=release :target: https://gitlab.com/renich/genclave/-/releases :alt: GitLab Release .. image:: https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat&logo=go :target: https://golang.org/ :alt: Go Version .. image:: https://img.shields.io/badge/License-GPLv3-blue.svg?logo=gnu :target: https://www.gnu.org/licenses/gpl-3.0 :alt: License
|
.. image:: https://img.shields.io/badge/FIDO2-CTAP2%20Virtual%20HID-4285F4?logo=fido :target: docs/technical/specs/ctap2-virtual-hid.rst :alt: FIDO2 CTAP2 .. image:: https://img.shields.io/badge/Hardware-TPM%202.0%20Sealed-4CAF50?logo=security :target: docs/technical/specs/tpm-binding.rst :alt: TPM 2.0 .. image:: https://img.shields.io/badge/Bridges-SSH%20%7C%20GPG%20%7C%20Age%20%7C%20D--Bus-8b5cf6 :target: docs/technical/specs/protocol-bridges.rst :alt: Multi-Protocol Bridges .. image:: https://img.shields.io/badge/Donate-Liberapay-f6c915.svg?logo=liberapay&logoColor=black :target: https://liberapay.com/Renich/donate :alt: Donate using Liberapay
.. caution::
PRE-ALPHA SOFTWARE — USE AT YOUR OWN RISK!
Despite the release numbering, gEnclave (formerly gpasskey) is currently experimental pre-alpha software undergoing rapid architectural development. Cryptographic schemas, vault formats, and protocol bridges may change without backwards compatibility.
gEnclave provides a unified hardware-backed security enclave that stores private keys and secrets in a TPM-sealed encrypted vault.
It acts as a multi-protocol bridge, supporting WebAuthn/FIDO2 Passkeys, OpenSSH Agent, the age encryption plugin protocol, GnuPG commit signing emulation, and encrypted secret configuration.
Multi-Protocol Support:
/dev/uhid for native browser (Firefox, Chrome, Chromium) and OS Passkey authentication.age (v1) file encryption (age-plugin-ge/age-plugin-gpasskey).genclave-gpg/gpasskey-gpg) for seamless Git commit signing and verification.Hardware-Backed Security: Private keys encrypted with AES-256-GCM, primarily sealed to TPM 2.0 with SRK caching and automatic Argon2id software fallback.
Cryptographic PIN Binding & Auth Cache: Every operation is bound to a PIN-derived subkey with an in-memory authorization cache in kernel-locked RAM (mlock). Supports configurable burst duration (default 5s) or persistent/unlimited caching (configured in vault or via GENCLAVE_SSH_CACHE_TTL), with instant zeroization on system suspend or manual lock.
CLI Pre-Authentication & Lock Control: Unlock or lock the in-memory cache directly from the terminal (ge unlock [--stdin], ge lock) for automated batch scripts and headless workflows.
Argon2id KDF: Memory-hard key derivation for master passphrase, recovery, and subkeys.
Brute-Force Protection: Automatic exponential backoff for failed authorization attempts.
Intelligent UI Routing: Automatic session detection (Graphical vs. TTY) for authorization prompts.
Secure Memory: Uses mmap/mlock and a "Wrap and Clear" strategy to prevent key material from leaking to swap or GC heap.
Identity Management: Robust CLI (ge) for vault administration and encrypted secret management.
Hardware & Kernel
* **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
wl-copy): Recommended for one-click clipboard copying in the disaster recovery dialog.Build & Development 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
make install-user # Installs binaries, systemd units, man pages, and activates services
Or install system-wide (requires root):
.. code-block:: bash
sudo make install # Installs to /usr/local/bin, /usr/share/man, etc.
Inspect enclave and daemon status:
.. code-block:: bash
ge status
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
Manage OpenSSH keys in the vault:
.. code-block:: bash
# Generate a new hardware-sealed Ed25519 SSH key:
ge ssh generate --name personal-github
# Or import your existing keys from ~/.ssh/:
ge ssh import ~/.ssh/
# Export OpenSSH public key for GitHub/GitLab:
ge ssh public personal-github
Manage GnuPG identities & Git commit signing:
.. code-block:: bash
# Generate an OpenPGP signing key:
ge gpg generate --user-name "Your Name" --email "[email protected]"
# List registered keys and Libgcrypt keygrips:
ge gpg list
Manage 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 hardware-bound configuration store:
.. code-block:: bash
ge secret set my-api-key "super-secret-value"
ge secret get my-api-key
Documentation & Specifications
------------------------------
Our comprehensive engineering documentation is organized into modular specifications, architecture records, and roadmaps: