gpasskey

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

Die zentralisierte kryptografische Identitäts-Enklave für Linux.

.. caution::

PRE-ALPHA-SOFTWARE — VERWENDUNG AUF EIGENE GEFAHR!

Trotz der Release-Nummerierung handelt es sich bei gpasskey derzeit um experimentelle Pre-Alpha-Software mit rascher architektonischer Weiterentwicklung. Kryptografische Schemata, Tresorformate und Protokoll-Brücken können sich ohne Abwärtskompatibilität ändern.

Hohes Risiko von Schlüssel- und Datenverlust: Notieren und bewahren Sie Ihre 24-Wörter-BIP39-Wiederherstellungsphrase immer sicher auf.
Sekundäre 2FA vorhalten: Wenn Sie virtuelle FIDO2-Sicherheitsschlüssel für Produktionskonten registrieren, konfigurieren Sie immer eine sekundäre 2FA-Methode (z. B. TOTP oder Backup-Wiederherstellungscodes).
Keine Gewährleistung: Wird unter der GNU-GPLv3-Lizenz streng "as is" ohne jegliche Gewährleistung bereitgestellt.

Überblick

gpasskey stellt eine hardwaregestützte Sicherheits-Enklave bereit, die private Schlüssel in einem verschlüsselten Tresor speichert. Es fungiert als Multi-Protokoll-Brücke und unterstützt den SSH-Agent, das age-Verschlüsselungs-Plugin-Protokoll sowie die GnuPG-Emulation zum Signieren von Commits.

Hauptfunktionen

Multi-Protokoll-Unterstützung:
- FIDO2-/CTAP2-Passkeys: Virtueller USB-Sicherheitsschlüssel-Emulator über /dev/uhid für native Browser- (Firefox, Chrome, Chromium) und Betriebssystem-Passkey-Authentifizierung.
- SSH-Agent: OpenSSH-konformes Agent-Protokoll.
- age-plugin: Native Unterstützung für die age-Dateiverschlüsselung (v1).
- GnuPG-Brücke: Emuliert die GPG-CLI für nahtloses Git-Commit-Signieren und -Verifizieren.
Hardwaregestützte Sicherheit: Private Schlüssel werden mit AES-256-GCM verschlüsselt und primär mit SRK-Caching an TPM 2.0 gebunden.
Kryptografische PIN-Bindung & UV-Cache: Jede Operation ist an einen aus der PIN abgeleiteten Unterschlüssel gebunden, mit einem 15-sekündigen Sitzungscache im gesperrten RAM (mlock).
Argon2id-KDF: Speicherharte Schlüsselableitung für Master-Passphrase, Wiederherstellung und Unterschlüssel.
Brute-Force-Schutz: Automatischer exponentieller Backoff bei fehlgeschlagenen Autorisierungsversuchen.
Intelligentes UI-Routing: Automatische Sitzungserkennung (grafisch vs. TTY) für Autorisierungsabfragen.
Sicherer Speicher: Verwendet mmap/mlock und eine "Wrap-and-Clear"-Strategie, um zu verhindern, dass Schlüsselmaterial in Swap oder GC-Heap gelangt.
Identitätsverwaltung: Robuste CLI (gpasskey-cli) für die Tresorverwaltung und die Verwaltung verschlüsselter Geheimnisse.

TPM-2.0-Integration

gpasskey unterstützt hardwaregestützte Sicherheit über TPM 2.0. Dadurch wird sichergestellt, dass Ihr Masterschlüssel das TPM niemals unverschlüsselt verlässt und an den Boot-Zustand des Systems gebunden ist.

Voraussetzungen


* Ein TPM-2.0-kompatibles Gerät (oder ``swtpm`` für die Entwicklung).
* ``tpm2-tools`` auf dem System installiert.

Initialisierung

Der TPM-Speicher wird automatisch initialisiert, wenn Sie eine neue Identität erstellen. So überprüfen Sie den TPM-Status:

.. code-block:: bash

gpasskey-cli status

Verwendung


Nach der Initialisierung wird das TPM vom Daemon transparent genutzt. Alle sensiblen Daten sind gegen **PCR 0** (Core System Firmware) und **PCR 7** (Secure-Boot-Zustand) versiegelt. Jede Änderung an der Firmware oder der Secure-Boot-Konfiguration verhindert das Entsperren des Tresors und schützt so vor Offline-Angriffen und unbefugter Manipulation des Betriebssystems.

Schnellstart
------------

Erstellen und Installieren für Ihr Benutzerkonto (empfohlen, ohne Root)::

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

Oder systemweit installieren (erfordert Root)::

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

Socket-Aktivierung aktivieren und starten::

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

Initialisieren Sie Ihren Tresor und überprüfen Sie den 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 im 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!

Verwalten Sie verschlüsselte Geheimnisse im TPM-gestützten Konfigurationsspeicher::

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

Dokumentation & Spezifikationen
-------------------------------

Unsere umfassende technische Dokumentation ist in modulare Spezifikationen, Architekturaufzeichnungen und Roadmaps gegliedert:

* **Funktionale Spezifikationen**: `Functional Spec Index`_ — Definiert Benutzeranforderungen und Autorisierungsmodelle.
* **Technische Architekturpläne**: `Technical Spec Index`_ — Detaillierte Go-Architektur, Krypto-Primitive und Enklaven-Designs.
* **Architecture Decision Records (ADRs)**: `ADR Index`_ — Unveränderliches Protokoll architektonischer, kryptografischer und sicherheitsrelevanter Entscheidungen.
* **API- & Wire-Protokolle**: `API Spec Index`_ — Management-Socket, D-Bus-Portale und Bridge-Wire-Schemas.
* **Projekt-Roadmap**: `Roadmap Index`_ — Phasenbasierte technische Zeitpläne und Meilenstein-Lieferungen.

Benutzerhandbücher

User Quick Start_ - In 5 Minuten startklar.
Installation Guide_ - Detaillierte Build-, udev- und systemd-Einrichtung.
Security Guide_ - Hardware-TPM-2.0-Enklave und "Wrap-and-Clear"-Speicherisolation.
Configuration Guide_ - Umgebungsvariablen und Dienstoptionen.

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

Was wir planen (Phase 7)

Derzeit spezifizieren und entwerfen wir Phase 7: Plugbare Multi-Faktor- & Multi-Party-Quorum-Engine:

Streaming-Hasher für beliebige Dateien: Verwenden Sie eine beliebige Datei (von einem kurzen Textgedicht bis zu einem 100-GB-Audio-Master-FLAC oder -Bild) als Autorisierungsfaktor mit konstantem :math:\mathcal{O}(1)-Speicherverbrauch (:math:\le 64\,\text{KB}-Puffer).
Multi-Party-Quorum ("Das Coca-Cola-Rezept"): Key-Wrapped-Shamir-Secret-Sharing über :math:\text{GF}(2^8) mit HMAC-Verifizierungstags, das eine :math:k-of-:math:n-Split-Key-Autorisierung ermöglicht.
Hardware & Biometrie: Physischer YubiKey (Slot 2 HMAC-SHA1), physische FIDO2-Schlüssel (hmac-secret) und Linux-Biometrie (fprintd).
Dynamisches Faktor-Re-Keying: Atomare Neuverschlüsselung im Speicher (gpk rekey), um die Faktor-Richtlinie einer Identität im laufenden Betrieb zu wechseln, ohne Schlüssel neu zu erstellen.
CLI-Modernisierung: Straffung der Befehlszeilenschnittstelle zum kanonischen gpk (/usr/local/bin/gpk).
Desktop-Auto-Unlock: Nahtlose Integration in den Freedesktop Secret Service ().

Vollständige Spezifikationen finden Sie unter Phase 7 Roadmap_ und ADR-006_.

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

Komponenten

gpasskeyd: Die zentrale Sicherheits-Enklave und der virtuelle USB-CTAP2/FIDO2-Sicherheitsschlüssel-Daemon.
gpasskey-cli: Administrationswerkzeug für Tresorverwaltung und verschlüsselte Konfiguration.
age-plugin-gpasskey: Plugin für das age-Verschlüsselungswerkzeug.
gpasskey-gpg: Emulations-Brücke für GnuPG-kompatibles Signieren und Verifizieren.
gpasskey-ui: Grafischer Helfer für die PIN-Eingabe.

Entwicklung

Führen Sie die Unit-Tests aus::

make test

Führen Sie die vollständige Go-native Integrationssuite aus (erfordert swtpm)::

make integration-test

Support & Spenden

Wenn Sie gpasskey nützlich finden und seine weitere Entwicklung unterstützen möchten, erwägen Sie eine Spende über Liberapay:

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

Lizenz

Dieses Projekt ist unter der GNU General Public License v3.0 oder später lizenziert. Einzelheiten finden Sie in der LICENSE-Datei.

gpasskey

Beliebteste

gpasskey

Überblick

Hauptfunktionen

TPM-2.0-Integration

Was wir planen (Phase 7)

Komponenten

Entwicklung

Support & Spenden

Lizenz