git-remote-pqcrypt

ISTO É UM PROJETO EXPERIMENTAL, não passou por uma auditoria de segurança formal. NÃO confie nele para repositórios críticos.

git-remote-pqcrypt é um helper remoto Git criptografado similar ao gcrypt. Ele armazena packfiles Git e metadados do repositório criptografados em repouso. O acesso é feito com o wrapping pós-quântico XWing.

Versão atual da crate: 0.2.0.

Como funciona

1. git-remote-pqcrypt init cria uma chave mestra do repositório.
2. A chave mestra é encapsulada para cada usuário com sua chave pública.
3. Packfiles Git e manifesto são criptografados usando a chave mestra.
4. Git usa pqcrypt através do helper remoto git-remote-pqcrypt.
5. A chave mestra é decriptada localmente pelo helper e então os packfiles são decriptados para o repositório local.

Exemplo de arquivos do armazenamento remoto:

keys.json
manifest.enc
objects/
    pack-.....pack.enc

keys.json contém metadados e encapsulamentos criptografados da chave mestra.

Instalação

Instalação rápida com Cargo

Instale a build padrão a partir do Git:

cargo install --git https://github.com/Torm0r/git-remote-pqcrypt --locked

Isso instala git-remote-pqcrypt no diretório binário do Cargo, geralmente ~/.cargo/bin.

Certifique-se de que o diretório binário do Cargo está no seu PATH, então verifique se funciona:

git-remote-pqcrypt --help

A build padrão inclui suporte a armazenamento local via sistema de arquivos e via Git-backed.

Para instalar com suporte SFTP em sistemas Unix-like:

cargo install --git https://github.com/Torm0r/git-remote-pqcrypt --locked --features sftp

A funcionalidade sftp atualmente não é suportada no Windows.

Compilar a partir do código fonte

Compile com suporte de backend padrão:

cargo build --release

Isso inclui suporte a armazenamento local via sistema de arquivos e via Git-backed.

Para compilar com suporte SFTP em sistemas Unix-like:

cargo build --release --features sftp

Instale o binário no seu PATH:

sudo cp target/release/git-remote-pqcrypt /usr/local/bin/

O nome do binário deve permanecer git-remote-pqcrypt, pois o Git encontra os helpers remotos procurando por git-remote-[nome].

Verifique se funciona:

git-remote-pqcrypt --help

Requisitos

• Rust toolchain para compilar a partir do código fonte
• git deve estar instalado
• Para armazenamento via Git-backed, são necessárias credenciais Git funcionando e uma identidade Git configurada
• Para acesso SSH/SFTP, a autenticação SSH existente deve estar configurada
• O suporte SFTP requer compilação com --features sftp e atualmente é apenas para sistemas Unix-like

Início rápido

1. Vá para um repositório Git existente ou crie um.

2. Inicialize o armazenamento pqcrypt.

Caminho local:

git-remote-pqcrypt init pqcrypt:///caminho/para/armazenamento-criptografado

SFTP requer compilação com a funcionalidade sftp e atualmente é suportada apenas em sistemas Unix-like:

git-remote-pqcrypt init pqcrypt::sftp://[email protected]/caminho/para/armazenamento

Via Git-backed:

git-remote-pqcrypt init pqcrypt::[email protected]:org/armazenamento.git

Se nenhuma chave privada existir, uma é gerada em ~/.config/pqcrypt/key e a chave pública é exibida.

Você será solicitado a fornecer um comentário opcional para a chave, por exemplo pessoal ou laptop-trabalho.

Após o init, um remote Git chamado pqcrypt é adicionado:

git remote -v

Exemplo:

pqcrypt  pqcrypt::/caminho/para/armazenamento-criptografado (fetch)
pqcrypt  pqcrypt::/caminho/para/armazenamento-criptografado (push)

3. Push:

git push pqcrypt main

4. Clone ou fetch:

git clone pqcrypt::[email protected]:Torm0r/pqcrypt-test.git meu-clone

5. Adicione outro usuário.

Ele deve gerar um par de chaves com:

git-remote-pqcrypt keygen

Ele pode obter sua chave pública com:

git-remote-pqcrypt pubgen ~/.config/pqcrypt/key

Ou pode copiar a chave pública exibida por keygen.

Em seguida, um usuário autorizado existente o adiciona ao repositório:

git-remote-pqcrypt add-user <chave-publica-base64>

Execute para mais opções:

git-remote-pqcrypt add-user -h

Por padrão, add-user procura por um remote Git local cuja URL comece com pqcrypt e adiciona a chave pública lá.

Comportamento do Push

pqcrypt distingue pushes normais de force pushes pela refspec do Git.

Pushes normais são verificados como fast-forward e rejeitados se sobrescreveriam o histórico remoto.

Comportamento do Remote-helper

Git invoca pqcrypt como um helper remoto através do binário git-remote-pqcrypt.

Quando invocado pelo Git, o helper espera o formato de argumento remote-helper usado pelo Git, por exemplo:

git-remote-pqcrypt origin pqcrypt::/caminho/para/armazenamento

Subcomandos diretos da CLI como init, add-user, keygen, pubgen e help são tratados como comandos de usuário normais, não como invocações de remote-helper.

O ponto de entrada do binário delega para o runtime da biblioteca, então a lógica da aplicação é testável tanto através da crate da biblioteca quanto através do binário instalado.

Cache de armazenamento via Git-backed

Para URLs de armazenamento via Git-backed, pqcrypt mantém um cache local no diretório de cache do sistema, por exemplo:

~/.cache/pqcrypt/

pqcrypt busca o estado criptografado do repositório Git de apoio antes das operações e envia o estado criptografado após as atualizações.

Se for detectada corrupção ou perda do cache, pqcrypt tenta recriar o cache automaticamente, buscando novamente do repositório Git de apoio.

Formatos de URL

pqcrypt::, pqcrypt:// e pqcrypt: são todos aceitos e normalizados internamente para pqcrypt::.

Estes são equivalentes:

git-remote-pqcrypt init pqcrypt:///caminho/para/armazenamento
git-remote-pqcrypt init pqcrypt::/caminho/para/armazenamento
git-remote-pqcrypt init pqcrypt:/caminho/para/armazenamento

O backend é determinado pelo caminho de armazenamento:

Exemplos:

pqcrypt::/tmp/armazenamento
pqcrypt:///tmp/armazenamento
pqcrypt:/tmp/armazenamento
pqcrypt::[email protected]:org/armazenamento.git
pqcrypt::https://github.com/org/armazenamento.git
pqcrypt::sftp://[email protected]/caminho/para/armazenamento

Lógica de descoberta da chave privada

Durante a decriptação, pqcrypt procura uma chave privada nesta ordem:

1. Variável de ambiente PQCRYPT_KEY_PATH
2. git config pqcrypt.keypath
3. .pqcrypt/key no diretório atual
4. Qualquer arquivo de chave correspondente em ~/.config/pqcrypt, onde todos são testados

Para configurações com múltiplas chaves, por exemplo chave de trabalho e pessoal:

git config pqcrypt.keypath ~/.config/pqcrypt/chave-trabalho

A chave deve ser uma que foi usada durante init ou adicionada via add-user.

Desenvolvimento

Execute a suíte de testes completa:

cargo test

Execute com SFTP habilitado em sistemas Unix-like:

cargo test --features sftp

Alguns testes de ponta a ponta que dependem do comportamento de caminho local Unix-like são ignorados no Windows.

Builds CI

GitHub Actions compila o projeto no Linux, macOS e Windows. Os artefatos do workflow podem conter binários de execuções CI, mas estes não são lançamentos oficiais.

Informações de segurança

• O conteúdo do repositório é criptografado usando XChaCha20Poly1305.
• A chave mestra do repositório é encapsulada para os usuários usando HPKE com XWing.
• Cada chave pública autorizada recebe sua própria cópia criptografada da chave mestra.
• Comentários anexados às chaves são autenticados como dados associados HPKE. Isso significa que se os metadados do comentário forem corrompidos, a chave mestra pode não mais decriptar para aquele encapsulamento.
• As refs Git e os metadados do packfile são armazenados dentro do manifesto criptografado.
• Arquivos de chave privada são criados com permissões 0600 em sistemas Unix-like.

Limitações

• Este projeto é experimental e não passou por uma auditoria de segurança formal.
• Atualmente, apenas os backends de armazenamento local via sistema de arquivos, via Git-backed e SFTP opcional são suportados.
• O suporte SFTP está por trás da funcionalidade opcional sftp e atualmente não é suportado no Windows.
• Os backends SFTP/Git carecem de travamento distribuído robusto, então pushes concorrentes podem levar à perda de dados.
• O comportamento do remote-helper Git ainda é relativamente mínimo e pode não suportar todos os fluxos de trabalho Git ou operações CI/CD.
• Force pushes são suportados, mas podem reescrever o histórico remoto criptografado, assim como os force pushes normais do Git.
• A crate HPKE depende de uma fonte git porque o XWing ainda não é suportado nas versões publicadas da crate. Isso será alterado assim que HPKE for atualizada.
• Não há maneira de revogar ou remover o acesso do usuário. Como os usuários podem recuperar a chave mestra do histórico do Git, a melhor ação é reinicializar o repositório com uma nova chave mestra e limpar o remoto.
• O formato de armazenamento pode mudar em versões futuras.
• O armazenamento via Git-backed requer credenciais Git funcionando e uma identidade Git configurada para commits.
• Para autenticação Git, SSH ou SFTP, pqcrypt depende de credenciais SSH/Git existentes.
• ssh e git devem estar instalados.