gpasskey

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

O enclave central de identidade criptográfica para Linux.

.. caution::

SOFTWARE PRÉ-ALFA — USE POR SUA CONTA E RISCO!

Apesar da numeração de versões, o gpasskey é atualmente um software experimental de pré-alfa em rápido desenvolvimento arquitetural. Esquemas criptográficos, formatos de cofre e pontes de protocolo podem mudar sem compatibilidade retroativa.

Alto Risco de Perda de Chaves e Dados: Sempre registre e armazene com segurança a Frase de Recuperação BIP39 de 24 palavras.
Mantenha um 2FA Secundário: Ao cadastrar chaves de segurança virtuais FIDO2 em contas de produção, configure sempre um método 2FA secundário (como TOTP ou códigos de recuperação de backup).
Sem Garantias: Fornecido estritamente "como está", sem garantias de qualquer tipo, sob a licença GNU GPLv3.

Visão Geral

O gpasskey fornece um enclave de segurança com suporte a hardware que armazena chaves privadas em um cofre criptografado. Ele atua como uma ponte multiprotocolo, oferecendo suporte ao SSH Agent, ao protocolo de plugin de criptografia age e à emulação de assinatura de commits do GnuPG.

Principais Recursos

Suporte Multiprotocolo:
- Chaves de acesso FIDO2 / CTAP2: Emulador virtual de chave de segurança USB via /dev/uhid para autenticação nativa por Passkey em navegadores (Firefox, Chrome, Chromium) e no sistema operacional.
- SSH Agent: Protocolo de agente compatível com OpenSSH.
- age-plugin: Suporte nativo à criptografia de arquivos do age (v1).
- Ponte GnuPG: Emula a CLI do GPG para assinatura e verificação de commits Git de forma transparente.
Segurança com Suporte a Hardware: Chaves privadas criptografadas com AES-256-GCM, seladas principalmente ao TPM 2.0 com cache de SRK.
Vinculação de PIN Criptográfico e Cache de UV: Cada operação é vinculada a uma subchave derivada do PIN, com cache de sessão segura de 15 segundos em RAM bloqueada (mlock).
KDF Argon2id: Derivação de chave com uso intensivo de memória para a frase-senha mestra, recuperação e subchaves.
Proteção contra Força Bruta: Backoff exponencial automático para tentativas de autorização com falha.
Roteamento Inteligente de Interface: Detecção automática de sessão (Gráfica vs. TTY) para solicitações de autorização.
Memória Segura: Usa mmap/mlock e a estratégia "Wrap and Clear" para impedir que o material da chave vaze para swap ou para o heap do GC.
Gerenciamento de Identidades: CLI robusta (gpasskey-cli) para administração do cofre e gerenciamento de segredos criptografados.

Integração com TPM 2.0

O gpasskey oferece suporte à segurança baseada em hardware por meio do TPM 2.0. Isso garante que sua chave mestra nunca saia do TPM sem criptografia e permaneça vinculada ao estado de inicialização do sistema.

Requisitos


* Um dispositivo compatível com TPM 2.0 (ou ``swtpm`` para desenvolvimento).
* ``tpm2-tools`` instalado no sistema.

Inicialização

O armazenamento do TPM é inicializado automaticamente quando você cria uma nova identidade. Para verificar o status do TPM:

.. code-block:: bash

gpasskey-cli status

Uso


Uma vez inicializado, o TPM é usado de forma transparente pelo daemon. Todos os dados confidenciais são selados contra **PCR 0** (Firmware do Sistema Central) e **PCR 7** (Estado do Secure Boot). Qualquer modificação no firmware ou na configuração do Secure Boot impedirá que o cofre seja desbloqueado, protegendo contra ataques offline e adulteração não autorizada do SO.

Início Rápido
-------------

Compile e instale para sua conta de usuário (recomendado, sem root)::

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

Ou instale em todo o sistema (requer root)::

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

Ative e inicie a ativação por socket::

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

Inicialize seu cofre e verifique o status::

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

Chaves de acesso WebAuthn no navegador::

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

Gerencie segredos criptografados no armazenamento de configuração com suporte a TPM::

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

Documentação e Especificações
------------------------------

Nossa documentação de engenharia abrangente está organizada em especificações modulares, registros de arquitetura e roteiros:

* **Especificações Funcionais**: `Índice de Especificações Funcionais`_ — Define os requisitos do usuário e os modelos de autorização.
* **Projetos Técnicos**: `Índice de Especificações Técnicas`_ — Arquitetura Go detalhada, primitivas criptográficas e projetos de enclave.
* **Registros de Decisões de Arquitetura (ADRs)**: `Índice de ADRs`_ — Registro imutável das escolhas arquiteturais, criptográficas e de segurança.
* **API e Protocolos de Comunicação**: `Índice de Especificações de API`_ — Socket de gerenciamento, portais D-Bus e esquemas de comunicação das pontes.
* **Roteiro de Execução do Projeto**: `Índice de Roteiros`_ — Cronogramas de engenharia em fases e entregas de marcos.

Guias do Usuário

Início Rápido do Usuário_ - Comece a usar em 5 minutos.
Guia de Instalação_ - Configuração detalhada de build, udev e systemd.
Guia de Segurança_ - Enclave de hardware TPM 2.0 e isolamento de memória "Wrap and Clear".
Guia de Configuração_ - Variáveis de ambiente e opções de serviço.

.. _Índice de Especificações Funcionais: docs/functional/spec.rst .. _Índice de Especificações Técnicas: docs/technical/spec.rst .. _Índice de ADRs: docs/adrs/index.rst .. _Índice de Especificações de API: docs/api/spec.rst .. _Índice de Roteiros: docs/project/roadmap.rst .. _Início Rápido do Usuário: docs/user/quickstart.rst .. _Guia de Instalação: docs/user/installation.rst .. _Guia de Segurança: docs/user/security.rst .. _Guia de Configuração: docs/user/configuration.rst

O Que Estamos Planejando (Fase 7)

Atualmente estamos especificando e arquitetando a Fase 7: Mecanismo de Quórum Multifator e Multipartidário Plugável:

Hasher de Streaming de Arquivos Arbitrários: Use qualquer arquivo (de um poema curto a um master FLAC de áudio de 100GB ou imagem) como fator de autorização com consumo de memória constante :math:\mathcal{O}(1) (buffer de :math:\le 64\,\text{KB}).
Quórum Multipartidário ("A Receita da Coca-Cola"): Compartilhamento de Segredo Shamir com Chave Envolvida sobre :math:\text{GF}(2^8) com tags de verificação HMAC, permitindo autorização de chave dividida :math:k-de-:math:n.
Hardware e Biometria: YubiKey físico (Slot 2 HMAC-SHA1), chaves FIDO2 físicas (hmac-secret) e biometria Linux (fprintd).
Re-Chaveamento Dinâmico de Fatores: Re-criptografia atômica em memória (gpk rekey) para alternar a política de fatores de uma identidade em tempo real, sem recriar chaves.
Modernização da CLI: Simplificação da interface de linha de comando no gpk canônico (/usr/local/bin/gpk).
Desbloqueio Automático no Desktop: Integração transparente com o Freedesktop Secret Service ().

Consulte Roteiro da Fase 7_ e ADR-006_ para especificações completas.

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

Componentes

gpasskeyd: O daemon central do enclave de segurança e chave de segurança virtual USB CTAP2/FIDO2.
gpasskey-cli: Ferramenta administrativa para gerenciamento do cofre e configuração criptografada.
age-plugin-gpasskey: Plugin para a ferramenta de criptografia age.
gpasskey-gpg: Ponte de emulação para assinatura e verificação compatíveis com GnuPG.
gpasskey-ui: Auxiliar gráfico para entrada de PIN.

Desenvolvimento

Execute os testes unitários::

make test

Execute a suíte completa de integração nativa em Go (requer swtpm)::

make integration-test

Suporte e Doações

Se você acha o gpasskey útil e gostaria de apoiar seu desenvolvimento contínuo, considere doar via Liberapay:

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

Licença

Este projeto é licenciado sob a GNU General Public License v3.0 ou posterior. Consulte o arquivo LICENSE para obter detalhes.

gpasskey

Mais Populares

gpasskey

Visão Geral

Principais Recursos

Integração com TPM 2.0

O Que Estamos Planejando (Fase 7)

Componentes

Desenvolvimento

Suporte e Doações

Licença