* **TPM 2.0**: Dispositivo TPM 2.0 de hardware (``/dev/tpmrm0`` ou ``/dev/tpm0``), ou ``swtpm`` para desenvolvimento com emulação por software.
* **Kernel Linux com /dev/uhid**: Suporte nativo do kernel para dispositivos HID em espaço de usuário (habilitado por padrão em distribuições modernas) para suportar passkeys FIDO2/CTAP2 virtuais no navegador.

Dependências de Runtime

* **Go 1.26** ou superior
* **GNU Make**
* **swtpm** (opcional, necessário para executar a suíte completa de testes de integração)

Instalação via Gerenciador de Pacotes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

No Fedora/RHEL/AlmaLinux:

.. code-block:: bash

   sudo dnf install golang make tpm2-tools zenity pinentry wl-clipboard swtpm

No Arch Linux:

.. code-block:: bash

   sudo pacman -S go make tpm2-tools zenity pinentry wl-clipboard swtpm

No Debian/Ubuntu:

.. code-block:: bash

   sudo apt install golang-go make tpm2-tools zenity pinentry-curses wl-clipboard swtpm

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

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

.. code-block:: bash

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

Ou instale em todo o sistema (requer root):

.. code-block:: bash

   sudo make install   # Instala em /usr/local/bin

Habilite e inicie a ativação por socket:

.. code-block:: bash

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

Inicialize seu cofre e verifique o status:

.. code-block:: bash

   ge status
   # Identidades são registradas automaticamente no primeiro uso pelos clientes 
   # (passkeys WebAuthn, SSH, age, GPG) ou via API do portal.

Pré-autentique o cache para scripts automatizados ou sessões headless:

.. code-block:: bash

   # Desbloqueie o cache interativamente via TTY:
   ge unlock

   # Ou pré-autentique via pipeline em scripts:
   echo "$PIN" | ge unlock --stdin

   # Limpe e bloqueie imediatamente ao terminar:
   ge lock


Passkeys WebAuthn no Navegador:

.. code-block:: bash

   # Abra o Firefox ou Chrome, vá para https://webauthn.io/
   # Clique em "Register" -> insira seu PIN no prompt do gEnclave -> Passkey criada!
   # Clique em "Authenticate" -> insira seu PIN -> Login instantâneo verificado!

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

.. code-block:: bash

   ge set-secret my-api-key "super-secret-value"
   ge 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 roadmaps:

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

Guias do Usuário
~~~~~~~~~~~~~~~~

* `User Quick Start`_ - Comece a usar em 5 minutos.
* `Installation Guide`_ - Configuração detalhada de build, udev e systemd.
* `OpenSSH Guide`_ - Integração com OpenSSH agent, jump hosts e chaves FIDO2.
* `GnuPG & Git Signing Guide`_ - Gerenciamento de chaves OpenPGP e assinatura de commits do Git.
* `Pluggable Factors Guide`_ - Keyfiles, YubiKeys, biometria e quóruns Shamir.
* `Security Guide`_ - Enclave de hardware TPM 2.0 e isolamento de memória "Wrap and Clear".
* `Configuration Guide`_ - Variáveis de ambiente e opções de serviço.
* `CLI Reference`_ - Documentação completa da interface de linha de comando.

.. _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
.. _OpenSSH Guide: docs/user/ssh.rst
.. _GnuPG & Git Signing Guide: docs/user/gpg.rst
.. _Pluggable Factors Guide: docs/user/factors.rst
.. _Security Guide: docs/user/security.rst
.. _Configuration Guide: docs/user/configuration.rst
.. _CLI Reference: docs/user/cli.rst

Fatores Plugáveis e Quórum Multi-Partes (Fase 7)
------------------------------------------------

**Fase 7: Motor de Múltiplos Fatores Plugáveis e Quórum Multi-Partes** entrega:

* **Hasher de Arquivos Arbitrários em Streaming**: Use qualquer arquivo (de um pequeno poema em texto a um master de áudio FLAC de 100GB ou imagem) como fator de autorização com consumo de memória constante :math:`\mathcal{O}(1)` (buffer :math:`\le 64\,\text{KB}`).
* **Quórum Multi-Partes ("A Receita da Coca-Cola")**: **Shamir Secret Sharing com Envelopamento de Chave** 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-Keying Dinâmico de Fatores**: Re-criptografia atômica em memória (``ge rekey``) para alternar a política de fatores de uma identidade em tempo real sem recriar chaves.
* **Modernização da CLI**: Interface de linha de comando simplificada no canônico ``ge``.
* **Desbloqueio Automático no Desktop**: Integração perfeita com o Freedesktop Secret Service (``org.freedesktop.secrets``).

Veja `Phase 7 Roadmap`_ e `ADR-006`_ para especificações completas.

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

Componentes
-----------

* **genclaved**: O enclave de segurança central e daemon de chave de segurança USB CTAP2/FIDO2 virtual (``man 8 genclaved``).
* **ge**: Ferramenta de linha de comando principal para administração de cofre, geração de chaves OpenSSH/GnuPG e configuração criptografada (``man 1 ge``).
* **age-plugin-ge**: Plugin para a ferramenta de criptografia ``age`` (``man 1 age-plugin-ge``).
* **genclave-gpg**: Ponte de emulação para assinatura e verificação compatíveis com GnuPG (``man 1 genclave-gpg``).
* **genclave-ui**: Auxiliar gráfico para entrada de PIN (``man 1 genclave-ui``).

Desenvolvimento
---------------

Execute os testes unitários:

.. code-block:: bash

   make test

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

.. code-block:: bash

   make integration-test

Suporte e Doações
-----------------

Se você acha o **gEnclave** ú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: Doar usando Liberapay

Licença
-------

Copyright 2026 EVALinux

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