git-remote-pqcrypt

QUESTO È UN PROGETTO SPERIMENTALE, non è stato sottoposto a un audit formale di sicurezza. NON fare affidamento su di esso per repository critici.

git-remote-pqcrypt è un helper remoto Git crittografato simile a gcrypt. Memorizza i packfile Git e i metadati del repository crittografati a riposo. L'accesso avviene tramite l'avvolgimento post-quantistico XWing.

Versione attuale del crate: 0.2.0.

Come funziona

1. git-remote-pqcrypt init crea una chiave master del repository.
2. La chiave master viene avvolta per ogni utente con la sua chiave pubblica.
3. I packfile Git e il manifest vengono crittografati usando la chiave master.
4. Git utilizza pqcrypt attraverso l'helper remoto git-remote-pqcrypt.
5. La chiave master viene decifrata localmente dall'helper e poi i packfile vengono decifrati nel repository locale.

Esempi di file nell'archivio remoto:

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

keys.json contiene metadati e gli avvolgimenti crittografati della chiave master.

Installazione

Installazione rapida con Cargo

Installa la build predefinita da Git:

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

Questo installa git-remote-pqcrypt nella directory dei binari di Cargo, di solito ~/.cargo/bin.

Assicurati che la directory dei binari di Cargo sia nel tuo PATH, quindi verifica che funzioni:

git-remote-pqcrypt --help

La build predefinita include il supporto per filesystem locale e archivio basato su Git.

Per installare con supporto SFTP su sistemi Unix-like:

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

La feature sftp attualmente non è supportata su Windows.

Compilazione dal sorgente

Compila con il supporto backend predefinito:

cargo build --release

Questo include il supporto per filesystem locale e archivio basato su Git.

Per compilare con supporto SFTP su sistemi Unix-like:

cargo build --release --features sftp

Installa il binario nel tuo PATH:

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

Il nome del binario deve rimanere git-remote-pqcrypt, perché Git trova gli helper remoti cercando git-remote-[nome].

Verifica che funzioni:

git-remote-pqcrypt --help

Requisiti

• Toolchain Rust per la compilazione dal sorgente
• git deve essere installato
• Per l'archivio basato su Git, sono necessarie credenziali Git funzionanti e un'identità Git configurata
• Per l'accesso SSH/SFTP, deve essere configurata l'autenticazione SSH esistente
• Il supporto SFTP richiede la compilazione con --features sftp ed è attualmente solo per sistemi Unix-like

Avvio rapido

1. Vai in un repository Git esistente o creane uno.

2. Inizializza l'archivio pqcrypt.

Percorso locale:

git-remote-pqcrypt init pqcrypt:///path/to/encrypted-store

SFTP richiede la compilazione con la feature sftp ed è attualmente supportata solo su sistemi Unix-like:

git-remote-pqcrypt init pqcrypt::sftp://[email protected]/path/to/store

Basato su Git:

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

Se non esiste una chiave privata, ne viene generata una in ~/.config/pqcrypt/key e viene stampata la chiave pubblica.

Ti verrà chiesto un commento opzionale per la chiave, ad esempio personale o laptop-lavoro.

Dopo l'inizializzazione, viene aggiunto un remote Git chiamato pqcrypt:

git remote -v

Esempio:

pqcrypt  pqcrypt::/path/to/encrypted-store (fetch)
pqcrypt  pqcrypt::/path/to/encrypted-store (push)

3. Push:

git push pqcrypt main

4. Clona o fetch:

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

5. Aggiungi un altro utente.

Deve generare una coppia di chiavi con:

git-remote-pqcrypt keygen

Può ottenere la sua chiave pubblica con:

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

Oppure può copiare la chiave pubblica stampata da keygen.

Poi un utente autorizzato esistente lo aggiunge al repository:

git-remote-pqcrypt add-user <chiave-pubblica-base64>

Esegui questo per ulteriori opzioni:

git-remote-pqcrypt add-user -h

Per impostazione predefinita, add-user cerca un remote Git locale il cui URL inizi con pqcrypt e vi aggiunge la chiave pubblica.

Comportamento del push

pqcrypt distingue i push normali dai force push in base al refspec di Git.

I push normali vengono controllati per fast-forward e vengono rifiutati se sovrascriverebbero la cronologia remota.

Comportamento dell'helper remoto

Git invoca pqcrypt come helper remoto attraverso il binario git-remote-pqcrypt.

Quando viene invocato da Git, l'helper si aspetta la forma degli argomenti dell'helper remoto utilizzata da Git, ad esempio:

git-remote-pqcrypt origin pqcrypt::/path/to/store

I sottocomandi diretti della CLI come init, add-user, keygen, pubgen e help vengono trattati come comandi utente normali, non come invocazioni dell'helper remoto.

Il punto di ingresso del binario delega al runtime della libreria, quindi la logica dell'applicazione è testabile sia attraverso la libreria del crate che attraverso il binario installato.

Cache dell'archivio basato su Git

Per gli URL di archivio basati su Git, pqcrypt mantiene una cache locale nella directory di cache di sistema, ad esempio:

~/.cache/pqcrypt/

pqcrypt recupera lo stato crittografato dal repository Git di appoggio prima delle operazioni e invia lo stato crittografato dopo gli aggiornamenti.

Se viene rilevata una corruzione o una perdita della cache, pqcrypt tenta di ricrearla automaticamente recuperando nuovamente dal repository Git di appoggio.

Formati URL

pqcrypt::, pqcrypt:// e pqcrypt: vengono tutti accettati e normalizzati internamente a pqcrypt::.

Questi sono equivalenti:

git-remote-pqcrypt init pqcrypt:///path/to/store
git-remote-pqcrypt init pqcrypt::/path/to/store
git-remote-pqcrypt init pqcrypt:/path/to/store

Il backend viene determinato dal percorso di archiviazione:

Esempi:

pqcrypt::/tmp/store
pqcrypt:///tmp/store
pqcrypt:/tmp/store
pqcrypt::[email protected]:org/store.git
pqcrypt::https://github.com/org/store.git
pqcrypt::sftp://[email protected]/path/to/store

Logica di individuazione della chiave privata

Durante la decifratura, pqcrypt cerca una chiave privata in quest'ordine:

1. Variabile d'ambiente PQCRYPT_KEY_PATH
2. git config pqcrypt.keypath
3. .pqcrypt/key nella directory corrente
4. Qualsiasi file di chiave corrispondente in ~/.config/pqcrypt, dove vengono testati tutti

Per configurazioni con più chiavi, ad esempio chiave di lavoro e personale:

git config pqcrypt.keypath ~/.config/pqcrypt/work-key

La chiave deve essere quella utilizzata durante init o aggiunta tramite add-user.

Sviluppo

Esegui l'intera suite di test:

cargo test

Esegui con SFTP abilitato su sistemi Unix-like:

cargo test --features sftp

Alcuni test end-to-end che dipendono dal comportamento del percorso locale Unix-like vengono ignorati su Windows.

Build CI

GitHub Actions compila il progetto su Linux, macOS e Windows. Gli artefatti del workflow possono contenere binari da esecuzioni CI, ma non sono rilasci ufficiali.

Informazioni sulla sicurezza

• I contenuti del repository vengono crittografati usando XChaCha20Poly1305.
• La chiave master del repository viene avvolta per gli utenti usando HPKE con XWing.
• Ogni chiave pubblica autorizzata riceve la propria copia crittografata della chiave master.
• I commenti allegati alle chiavi sono autenticati come dati associati HPKE. Ciò significa che se i metadati del commento vengono corrotti, la chiave master potrebbe non decifrare più per quell'avvolgimento.
• I ref Git e i metadati dei packfile sono memorizzati all'interno del manifest crittografato.
• I file delle chiavi private vengono creati con permessi 0600 sui sistemi Unix-like.

Limitazioni

• Questo progetto è sperimentale e non ha ricevuto un audit formale di sicurezza.
• Attualmente sono supportati solo i backend di archiviazione per filesystem locale, basato su Git e SFTP opzionale.
• Il supporto SFTP è dietro la feature opzionale sftp e attualmente non è supportato su Windows.
• I backend SFTP/Git mancano di un robusto blocco distribuito, quindi push concorrenti potrebbero causare perdita di dati.
• Il comportamento dell'helper remoto Git è ancora relativamente minimo e potrebbe non supportare tutti i workflow Git o le operazioni CI/CD.
• I force push sono supportati, ma possono riscrivere la cronologia remota crittografata proprio come i normali force push Git.
• Il crate HPKE dipende da una fonte git perché XWing non è ancora supportato nelle versioni pubblicate del crate. Questo verrà cambiato una volta che HPKE verrà aggiornato.
• Non esiste un modo per revocare o rimuovere l'accesso degli utenti. Poiché gli utenti possono recuperare la chiave master dalla cronologia Git, la soluzione migliore è reinizializzare il repository con una nuova chiave master e cancellare il remoto.
• Il formato di archiviazione potrebbe cambiare in versioni future.
• L'archivio basato su Git richiede credenziali Git funzionanti e un'identità Git configurata per i commit.
• Per l'autenticazione Git, SSH o SFTP, pqcrypt si basa sulle credenziali SSH/Git esistenti.
• ssh e git devono essere installati.