gpasskey

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

L'enclave di identità crittografica centralizzata per Linux.

.. caution::

PRE-ALPHA SOFTWARE — UTILIZZO A PROPRIO RISCHIO!

Nonostante la numerazione delle release, gpasskey è attualmente un software sperimentale pre-alpha in fase di rapido sviluppo architetturale. Gli schemi crittografici, i formati del vault e i bridge di protocollo possono cambiare senza compatibilità retroattiva.

Alto rischio di perdita di chiavi e dati: registra e conserva sempre in modo sicuro la tua frase di recupero BIP39 di 24 parole.
Mantenere un secondo fattore 2FA: quando registri chiavi di sicurezza virtuali FIDO2 su account di produzione, configura sempre un metodo 2FA secondario (come TOTP o codici di recupero di backup).
Nessuna garanzia: fornito rigorosamente "così com'è", senza garanzie di alcun tipo, sotto licenza GNU GPLv3.

Panoramica

gpasskey fornisce un'enclave di sicurezza basata su hardware che archivia le chiavi private in un vault crittografato. Funge da bridge multi-protocollo, supportando SSH Agent, il protocollo plugin di crittografia age e l'emulazione della firma dei commit GnuPG.

Caratteristiche Principali

Supporto Multi-Protocollo:
- Passkey FIDO2 / CTAP2: emulatore di chiave di sicurezza USB virtuale su /dev/uhid per l'autenticazione Passkey nativa nel browser (Firefox, Chrome, Chromium) e nel sistema operativo.
- SSH Agent: protocollo agent compatibile con OpenSSH.
- age-plugin: supporto nativo per la crittografia di file age (v1).
- Bridge GnuPG: emula la CLI GPG per la firma e la verifica fluida dei commit Git.
Sicurezza Basata su Hardware: chiavi private crittografate con AES-256-GCM, principalmente sigillate al TPM 2.0 con cache SRK.
Binding PIN Crittografico e Cache UV: ogni operazione è legata a una sottochiave derivata dal PIN con una cache di sessione sicura di 15 secondi in RAM bloccata (mlock).
KDF Argon2id: derivazione delle chiavi resistente alla memoria per passphrase principale, recupero e sottochiavi.
Protezione da Forza Bruta: backoff esponenziale automatico per tentativi di autorizzazione falliti.
Instradamento UI Intelligente: rilevamento automatico della sessione (Grafica vs. TTY) per i prompt di autorizzazione.
Memoria Sicura: utilizza mmap/mlock e una strategia "Wrap and Clear" per impedire che il materiale chiave venga disperso nello swap o nell'heap del GC.
Gestione delle Identità: CLI robusta (gpasskey-cli) per l'amministrazione del vault e la gestione di segreti crittografati.

Integrazione TPM 2.0

gpasskey supporta la sicurezza basata su hardware tramite TPM 2.0. Ciò garantisce che la tua chiave principale non lasci mai il TPM non crittografata e sia vincolata allo stato di avvio del sistema.

Requisiti


* Un dispositivo compatibile con TPM 2.0 (o ``swtpm`` per lo sviluppo).
* ``tpm2-tools`` installato sul sistema.

Inizializzazione

Lo storage TPM viene inizializzato automaticamente quando crei una nuova identità. Per verificare lo stato del TPM:

.. code-block:: bash

gpasskey-cli status

Utilizzo


Una volta inizializzato, il TPM viene usato in modo trasparente dal demone. Tutti i dati sensibili sono sigillati contro **PCR 0** (firmware di sistema core) e **PCR 7** (stato Secure Boot). Qualsiasi modifica al firmware o alla configurazione di Secure Boot impedirà lo sblocco del vault, proteggendo da attacchi offline e manomissioni non autorizzate del sistema operativo.

Avvio Rapido
------------

Compila e installa per il tuo account utente (consigliato, non root)::

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

Oppure installa a livello di sistema (richiede root)::

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

Abilita e avvia l'attivazione via socket::

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

Inizializza il tuo vault e verifica lo stato::

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

Passkey WebAuthn nel 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!

Gestisci i segreti crittografati nell'archivio di configurazione basato su TPM::

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

Documentazione e Specifiche
---------------------------

La nostra documentazione ingegneristica completa è organizzata in specifiche modulari, record di architettura e roadmap:

* **Specifiche Funzionali**: `Indice delle Specifiche Funzionali`_ — Definisce i requisiti utente e i modelli di autorizzazione.
* **Blueprint Tecnici**: `Indice delle Specifiche Tecniche`_ — Architettura Go dettagliata, primitive crittografiche e design delle enclave.
* **Architecture Decision Records (ADR)**: `Indice ADR`_ — Registro immutabile delle scelte architetturali, crittografiche e di sicurezza.
* **API e Protocolli Wire**: `Indice delle Specifiche API`_ — Socket di gestione, portali D-Bus e schemi wire dei bridge.
* **Roadmap di Esecuzione del Progetto**: `Indice della Roadmap`_ — Tempistiche ingegneristiche a fasi e deliverable di tappa.

Guide Utente

Avvio Rapido Utente_ - Per iniziare in 5 minuti.
Guida all'Installazione_ - Configurazione dettagliata di build, udev e systemd.
Guida alla Sicurezza_ - Enclave hardware TPM 2.0 e isolamento della memoria "Wrap and Clear".
Guida alla Configurazione_ - Variabili d'ambiente e opzioni di servizio.

.. _Indice delle Specifiche Funzionali: docs/functional/spec.rst .. _Indice delle Specifiche Tecniche: docs/technical/spec.rst .. _Indice ADR: docs/adrs/index.rst .. _Indice delle Specifiche API: docs/api/spec.rst .. _Indice della Roadmap: docs/project/roadmap.rst .. _Avvio Rapido Utente: docs/user/quickstart.rst .. _Guida all'Installazione: docs/user/installation.rst .. _Guida alla Sicurezza: docs/user/security.rst .. _Guida alla Configurazione: docs/user/configuration.rst

Cosa Stiamo Pianificando (Fase 7)

Stiamo attualmente specificando e architettando Fase 7: Motore Quorum Multi-Fattore e Multi-Parte Pluggabile:

Hasher Streaming di File Arbitrari: usa qualsiasi file (da una breve poesia testuale a un master audio FLAC da 100GB o un'immagine) come fattore di autorizzazione con consumo di memoria costante :math:\mathcal{O}(1) (buffer di :math:\le 64\,\text{KB}).
Quorum Multi-Parte ("La Ricetta della Coca-Cola"): Shamir Secret Sharing con Chiave Avvolta su :math:\text{GF}(2^8) con tag di verifica HMAC, che abilita l'autorizzazione con chiave suddivisa :math:k-di-:math:n.
Hardware e Biometria: YubiKey fisica (Slot 2 HMAC-SHA1), chiavi FIDO2 fisiche (hmac-secret) e biometria Linux (fprintd).
Ri-Keying Dinamico dei Fattori: ri-crittografia atomica in memoria (gpk rekey) per cambiare al volo la policy dei fattori di un'identità senza ricreare le chiavi.
Modernizzazione della CLI: semplificazione dell'interfaccia a riga di comando nel canonico gpk (/usr/local/bin/gpk).
Sblocco Automatico del Desktop: integrazione fluida con il Freedesktop Secret Service ().

Vedi Roadmap della Fase 7_ e ADR-006_ per le specifiche complete.

.. _Roadmap della Fase 7: docs/project/roadmaps/phase-7-pluggable-factors.rst .. _ADR-006: docs/adrs/2026-08-25-pluggable-auth-factors.rst

Componenti

gpasskeyd: l'enclave di sicurezza principale e il demone di chiave di sicurezza USB virtuale CTAP2/FIDO2.
gpasskey-cli: strumento amministrativo per la gestione del vault e la configurazione crittografata.
age-plugin-gpasskey: plugin per lo strumento di crittografia age.
gpasskey-gpg: bridge di emulazione per firma e verifica compatibili con GnuPG.
gpasskey-ui: helper grafico per l'inserimento del PIN.

Sviluppo

Esegui i test unitari::

make test

Esegui la suite di integrazione completa Go-native (richiede swtpm)::

make integration-test

Supporto e Donazioni

Se trovi gpasskey utile e vorresti supportare il suo sviluppo continuo, valuta di fare una donazione tramite Liberapay:

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

Licenza

Questo progetto è concesso in licenza secondo la GNU General Public License v3.0 o successive. Vedi il file LICENSE per i dettagli.

gpasskey

Più Popolari

gpasskey

Panoramica

Caratteristiche Principali

Integrazione TPM 2.0

Cosa Stiamo Pianificando (Fase 7)

Componenti

Sviluppo

Supporto e Donazioni

Licenza