gpasskey

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

The centralized cryptographic identity enclave for Linux.

.. caution::

PRE-ALPHA SOFTWARE — USE AT YOUR OWN RISK!

Despite the release numbering, gpasskey is currently experimental pre-alpha software undergoing rapid architectural development. Cryptographic schemas, vault formats, and protocol bridges may change without backwards compatibility.

High Risk of Key & Data Loss: Always record and securely store your 24-word BIP39 Recovery Phrase.
Maintain Secondary 2FA: When enrolling virtual FIDO2 security keys on production accounts, always configure a secondary 2FA method (such as TOTP or backup recovery codes).
No Warranty: Provided strictly "as is" without warranties of any kind under the GNU GPLv3 license.

Overview

gpasskey provides a hardware-backed security enclave that stores private keys in an encrypted vault. It acts as a multi-protocol bridge, supporting SSH Agent, the age encryption plugin protocol, and GnuPG commit signing emulation.

Key Features

Multi-Protocol Support:
- FIDO2 / CTAP2 Passkeys: Virtual USB security key emulator over /dev/uhid for native browser (Firefox, Chrome, Chromium) and OS Passkey authentication.
- SSH Agent: OpenSSH-compliant agent protocol.
- age-plugin: Native support for age (v1) file encryption.
- GnuPG Bridge: Emulates GPG CLI 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.
Cryptographic PIN Binding & UV Cache: Every operation is bound to a PIN-derived subkey with a 15-second secure session cache in locked RAM (mlock).
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 (gpasskey-cli) for vault administration and encrypted secret management.

TPM 2.0 Integration

gpasskey supports hardware-backed security via TPM 2.0. This ensures that your master key never leaves the TPM unencrypted and is bound to the system's boot state.

Requirements


* A TPM 2.0 compatible device (or ``swtpm`` for development).
* ``tpm2-tools`` installed on the system.

Initialization

The TPM storage is initialized automatically when you create a new identity. To verify TPM status:

.. code-block:: bash

gpasskey-cli status

Usage


Once initialized, the TPM is used transparently by the daemon. All sensitive data is sealed against **PCR 0** (Core System Firmware) and **PCR 7** (Secure Boot State). Any modification to the firmware or Secure Boot configuration will prevent the vault from being unlocked, protecting against offline attacks and unauthorized OS tampering.

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

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

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

Or install system-wide (requires root)::

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

Enable & start socket activation::

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

Initialize your vault and verify status::

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

WebAuthn Passkeys in Browser::

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

Manage encrypted secrets in the TPM-backed config store::

   gpasskey-cli set-secret my-api-key "super-secret-value"
   gpasskey-cli 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.
Security Guide_ - Hardware TPM 2.0 enclave and "Wrap and Clear" memory isolation.
Configuration Guide_ - Environment variables and service options.

.. _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 .. _Security Guide: docs/user/security.rst .. _Configuration Guide: docs/user/configuration.rst

What We're Planning (Phase 7)

We are currently specifying and architecting Phase 7: Pluggable Multi-Factor & Multi-Party Quorum Engine:

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 (gpk rekey) to switch an identity's factor policy on the fly without recreating keys.
CLI Modernization: Streamlining the command-line interface into canonical gpk (/usr/local/bin/gpk).
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

gpasskeyd: The core security enclave and virtual USB CTAP2/FIDO2 security key daemon.
gpasskey-cli: Administrative tool for vault management and encrypted configuration.
age-plugin-gpasskey: Plugin for the age encryption tool.
gpasskey-gpg: Emulation bridge for GnuPG-compatible signing and verification.
gpasskey-ui: Graphical helper for PIN entry.

Development

Run the unit tests::

make test

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

make integration-test

Support & Donations

If you find gpasskey 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

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

gpasskey

Most Popular

gpasskey

Overview

Key Features

TPM 2.0 Integration

What We're Planning (Phase 7)

Components

Development

Support & Donations

License