git-remote-pqcrypt

THIS IS AN EXPERIMENTAL PROJECT, there hasnt been a formal security audit. DO NOT rely on this for any critical repositories.

git-remote-pqcrypt est un assistant distant Git chiffré similaire à gcrypt. Il stocke les fichiers pack Git et les métadonnées de dépôt chiffrés au repos. L'accès se fait avec le post-quantum XWing wrapping.

Version actuelle de la crate : 0.2.0.

Comment ça marche

1. git-remote-pqcrypt init crée une clé maîtresse du dépôt.
2. La clé maîtresse est encapsulée pour chaque utilisateur avec sa clé publique.
3. Les fichiers pack Git et le manifeste sont chiffrés en utilisant la clé maîtresse.
4. Git utilise pqcrypt via l'assistant distant git-remote-pqcrypt.
5. La clé maîtresse est déchiffrée localement par l'assistant, puis les fichiers pack sont déchiffrés vers le dépôt local.

Exemples de fichiers du stockage distant :

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

keys.json contient les métadonnées et les encapsulations de la clé maîtresse chiffrées.

Installation

Installation rapide avec Cargo

Installer la version par défaut depuis Git :

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

Ceci installe git-remote-pqcrypt dans le répertoire binaire de Cargo, généralement ~/.cargo/bin.

Assurez-vous que le répertoire binaire de Cargo est dans votre PATH, puis vérifiez que cela fonctionne :

git-remote-pqcrypt --help

La version par défaut inclut le support du système de fichiers local et du stockage Git.

Pour installer avec le support SFTP sur les systèmes de type Unix :

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

La fonctionnalité sftp n'est actuellement pas prise en charge sur Windows.

Compiler depuis les sources

Compiler avec le support du backend par défaut :

cargo build --release

Ceci inclut le support du système de fichiers local et du stockage Git.

Pour compiler avec le support SFTP sur les systèmes de type Unix :

cargo build --release --features sftp

Installer le binaire dans votre PATH :

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

Le nom du binaire doit rester git-remote-pqcrypt, car Git trouve les assistants distants en cherchant git-remote-[nom].

Vérifiez que cela fonctionne :

git-remote-pqcrypt --help

Prérequis

• Chaîne d'outils Rust pour compiler depuis les sources
• git doit être installé
• Pour le stockage Git, des identifiants Git fonctionnels et une identité Git configurée sont requis
• Pour l'accès SSH/SFTP, une authentification SSH existante doit être configurée
• Le support SFTP nécessite une compilation avec --features sftp et est actuellement réservé aux systèmes de type Unix

Démarrage rapide

1. Allez dans un dépôt Git existant ou créez-en un.

2. Initialisez le stockage pqcrypt.

Chemin local :

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

SFTP nécessite une compilation avec la fonctionnalité sftp et n'est actuellement pris en charge que sur les systèmes de type Unix :

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

Backend Git :

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

Si aucune clé privée n'existe, une est générée dans ~/.config/pqcrypt/key et la clé publique est affichée.

Il vous sera demandé un commentaire de clé optionnel, par exemple personal ou work-laptop.

Après l'initialisation, un dépôt distant Git nommé pqcrypt est ajouté :

git remote -v

Exemple :

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

3. Pousser (push) :

git push pqcrypt main

4. Cloner ou récupérer (fetch) :

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

5. Ajouter un autre utilisateur.

Ils doivent générer une paire de clés avec :

git-remote-pqcrypt keygen

Ils peuvent obtenir leur clé publique avec :

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

Ou ils peuvent copier la clé publique affichée par keygen.

Ensuite, un utilisateur autorisé existant les ajoute au dépôt :

git-remote-pqcrypt add-user <base64-public-key>

Exécutez ceci pour plus d'options :

git-remote-pqcrypt add-user -h

Par défaut, add-user cherche un dépôt distant Git local dont l'URL commence par pqcrypt et y ajoute la clé publique.

Comportement de push

pqcrypt distingue les push normaux des force push par le refspec Git.

Les push normaux sont vérifiés en fast-forward et rejetés s'ils écraseraient l'historique distant.

Comportement de l'assistant distant

Git invoque pqcrypt en tant qu'assistant distant via le binaire git-remote-pqcrypt.

Lorsqu'il est invoqué par Git, l'assistant s'attend à la forme des arguments d'assistant distant utilisée par Git, par exemple :

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

Les sous-commandes CLI directes telles que init, add-user, keygen, pubgen et help sont traitées comme des commandes utilisateur normales, et non comme des invocations d'assistant distant.

Le point d'entrée du binaire délègue au runtime de la bibliothèque, de sorte que la logique applicative est testable à la fois via la bibliothèque de la crate et via le binaire installé.

Cache de stockage Git

Pour les URL de stockage Git, pqcrypt maintient un cache local dans le répertoire de cache système, par exemple :

~/.cache/pqcrypt/

pqcrypt récupère l'état chiffré depuis le dépôt Git sous-jacent avant les opérations et pousse l'état chiffré après les mises à jour.

Si une corruption ou une perte du cache est détectée, pqcrypt tente de recréer le cache automatiquement en récupérant à nouveau depuis le dépôt Git sous-jacent.

Formats d'URL

pqcrypt::, pqcrypt:// et pqcrypt: sont tous acceptés et normalisés en interne en pqcrypt::.

Ceux-ci sont équivalents :

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

Le backend est déterminé par le chemin de stockage :

Exemples :

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

Logique de découverte de la clé privée

Lors du déchiffrement, pqcrypt cherche une clé privée dans cet ordre :

1. Variable d'environnement PQCRYPT_KEY_PATH
2. git config pqcrypt.keypath
3. .pqcrypt/key dans le répertoire courant
4. Tout fichier de clé correspondant dans ~/.config/pqcrypt, où tous sont testés

Pour les configurations multi-clés, par exemple clés professionnelles et personnelles :

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

La clé doit être celle qui a été utilisée lors de init ou ajoutée via add-user.

Développement

Exécuter la suite de tests complète :

cargo test

Exécuter avec SFTP activé sur les systèmes de type Unix :

cargo test --features sftp

Certains tests de bout en bout qui dépendent du comportement des chemins locaux de type Unix sont ignorés sur Windows.

Compilations CI

GitHub Actions compile le projet sur Linux, macOS et Windows. Les artefacts du workflow peuvent contenir des binaires issus des exécutions CI, mais ceux-ci ne sont pas des versions officielles.

Informations de sécurité

• Les contenus du dépôt sont chiffrés avec XChaCha20Poly1305.
• La clé maîtresse du dépôt est encapsulée pour les utilisateurs en utilisant HPKE avec XWing.
• Chaque clé publique autorisée reçoit sa propre copie chiffrée de la clé maîtresse.
• Les commentaires attachés aux clés sont authentifiés en tant que données associées HPKE. Cela signifie que si les métadonnées du commentaire sont corrompues, la clé maîtresse pourrait ne plus se déchiffrer pour cette encapsulation.
• Les références Git et les métadonnées des fichiers pack sont stockées dans le manifeste chiffré.
• Les fichiers de clé privée sont créés avec les permissions 0600 sur les systèmes de type Unix.

Limitations

• Ce projet est expérimental et n'a pas reçu d'audit de sécurité formel.
• Actuellement, seuls les backends de stockage système de fichiers local, Git, et SFTP optionnel sont pris en charge.
• Le support SFTP est derrière la fonctionnalité optionnelle sftp et n'est actuellement pas pris en charge sur Windows.
• Les backends SFTP/Git manquent de verrouillage distribué robuste, donc les poussées concurrentes pourraient entraîner une perte de données.
• Le comportement de l'assistant distant Git est encore relativement minimal et peut ne pas prendre en charge tous les workflows Git ou opérations CI/CD.
• Les force pushes sont pris en charge, mais ils peuvent réécrire l'historique distant chiffré tout comme les force pushes Git normaux.
• La crate HPKE dépend d'une source git car XWing n'est pas encore pris en charge dans les versions publiées de la crate. Cela sera modifié une fois HPKE mis à jour.
• Aucun moyen de révoquer ou supprimer l'accès d'un utilisateur. Étant donné que les utilisateurs peuvent récupérer la clé maîtresse depuis l'historique Git, la meilleure action est de réinitialiser le dépôt avec une nouvelle clé maîtresse et d'effacer le dépôt distant.
• Le format de stockage pourrait changer dans les futures versions.
• Le stockage Git nécessite des identifiants Git fonctionnels et une identité Git configurée pour les commits.
• Pour l'authentification Git, SSH ou SFTP, pqcrypt s'appuie sur les identifiants SSH/Git existants.
• ssh et git doivent être installés.