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 は、gcrypt と同様の暗号化 Git リモートヘルパーです。Git パックファイルとリポジトリメタデータを保存時に暗号化します。アクセスには耐量子 XWing ラッピングを使用します。

現在のクレートバージョン: 0.2.0。

仕組み

1. git-remote-pqcrypt init でリポジトリのマスターキーを作成します。
2. マスターキーは各ユーザーの公開鍵でラップされます。
3. Git パックファイルとマニフェストはマスターキーを使って暗号化されます。
4. Git は git-remote-pqcrypt リモートヘルパーを介して pqcrypt を使用します。
5. マスターキーはヘルパーによってローカルで復号され、その後パックファイルがローカルリポジトリに復号されます。

リモートストレージのファイル例:

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

keys.json にはメタデータと暗号化されたマスターキーのラッピングが含まれています。

インストール

Cargo を使用した高速インストール

Git からデフォルトビルドをインストール:

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

これにより git-remote-pqcrypt が Cargo のバイナリディレクトリ（通常は ~/.cargo/bin）にインストールされます。

Cargo のバイナリディレクトリが PATH に含まれていることを確認し、次に動作確認を行います:

git-remote-pqcrypt --help

デフォルトビルドには、ローカルファイルシステムと Git バックエンドストレージのサポートが含まれます。

Unix 系システムで SFTP サポートを有効にしてインストールする場合:

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

sftp 機能は現在 Windows ではサポートされていません。

ソースからビルド

デフォルトのバックエンドサポートでビルド:

cargo build --release

これにはローカルファイルシステムと Git バックエンドストレージのサポートが含まれます。

Unix 系システムで SFTP サポートを有効にしてビルドする場合:

cargo build --release --features sftp

バイナリを PATH にインストール:

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

バイナリ名は git-remote-pqcrypt のままである必要があります。なぜなら Git は git-remote-[name] という名前でリモートヘルパーを探すからです。

動作確認:

git-remote-pqcrypt --help

要件

• ソースからビルドする場合は Rust ツールチェーン
• git がインストールされていること
• Git バックエンドストレージを使用する場合、有効な Git 認証情報と、構成済みの Git アイデンティティが必要
• SSH/SFTP アクセスには、既存の SSH 認証設定が必要
• SFTP サポートは --features sftp フラグを付けてビルドする必要があり、現在は Unix 系のみ

クイックスタート

1. 既存の Git リポジトリに移動するか、新しく作成します。

2. pqcrypt ストレージを初期化します。

ローカルパス:

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

SFTP は sftp 機能を有効にしてビルドする必要があり、現在は Unix 系システムでのみサポートされています:

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

Git バックエンド:

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

秘密鍵が存在しない場合は、~/.config/pqcrypt/key に生成され、公開鍵が表示されます。

オプションの鍵コメント（例: personal や work-laptop）の入力を求められます。

初期化後、pqcrypt という名前の Git リモートが追加されます:

git remote -v

例:

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

3. プッシュ:

git push pqcrypt main

4. クローンまたはフェッチ:

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

5. 別のユーザーを追加します。

そのユーザーは以下で鍵ペアを生成する必要があります:

git-remote-pqcrypt keygen

公開鍵を取得するには:

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

または、keygen で表示された公開鍵をコピーすることもできます。

その後、既存の認証ユーザーがリポジトリにユーザーを追加します:

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

詳細なオプションは以下を実行:

git-remote-pqcrypt add-user -h

デフォルトでは、add-user は URL が pqcrypt で始まるローカル Git リモートを探し、そこに公開鍵を追加します。

プッシュ動作

pqcrypt は通常のプッシュとフォースプッシュを Git の refspec で区別します。

通常のプッシュは fast-forward チェックが行われ、リモートの履歴を上書きする場合は拒否されます。

リモートヘルパーの動作

Git は git-remote-pqcrypt バイナリを介して、pqcrypt をリモートヘルパーとして起動します。

Git によって呼び出された場合、ヘルパーは Git が使用するリモートヘルパー引数形式を期待します。例:

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

init、add-user、keygen、pubgen、help などの直接 CLI サブコマンドは、リモートヘルパーの呼び出しではなく、通常のユーザーコマンドとして扱われます。

バイナリのエントリポイントはライブラリのランタイムに委譲されるため、アプリケーションロジックはクレートライブラリ経由でもインストール済みバイナリ経由でもテスト可能です。

Git バックエンドストレージキャッシュ

Git バックエンドストレージ URL の場合、pqcrypt はシステムキャッシュディレクトリ（例: ~/.cache/pqcrypt/）にローカルキャッシュを保持します。

pqcrypt は操作前にバッキング Git リポジトリから暗号化状態をフェッチし、更新後に暗号化状態をプッシュします。

キャッシュの破損や損失が検出された場合、pqcrypt はバッキング Git リポジトリから再フェッチしてキャッシュを自動的に再作成しようとします。

URL 形式

pqcrypt::、pqcrypt://、pqcrypt: はすべて受け入れられ、内部で pqcrypt:: に正規化されます。

これらは同等です:

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

バックエンドはストレージパスによって決定されます:

例:

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

秘密鍵の検出ロジック

復号化の際、pqcrypt は以下の順序で秘密鍵を探します:

1. PQCRYPT_KEY_PATH 環境変数
2. git config pqcrypt.keypath
3. カレントディレクトリの .pqcrypt/key
4. ~/.config/pqcrypt 内の一致する鍵ファイル（すべてテストされます）

複数鍵の設定（例: 仕事用と個人用の鍵）の場合:

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

鍵は init 時に使用されたか、add-user で追加されたものでなければなりません。

開発

すべてのテストスイートを実行:

cargo test

Unix 系システムで SFTP を有効にして実行:

cargo test --features sftp

Unix 系のローカルパス動作に依存する一部のエンドツーエンドテストは、Windows では無視されます。

CI ビルド

GitHub Actions は Linux、macOS、Windows でプロジェクトをビルドします。ワークフローアーティファクトには CI 実行からのバイナリが含まれる場合がありますが、これらは公式リリースではありません。

セキュリティ情報

• リポジトリの内容は XChaCha20Poly1305 を使用して暗号化されます。
• リポジトリのマスターキーは、HPKE と XWing を使用してユーザーごとにラップされます。
• 承認された各公開鍵は、マスターキーの暗号化コピーを受け取ります。
• 鍵に付随するコメントは HPKE の関連データとして認証されます。つまり、コメントメタデータが破損すると、そのラッピングのマスターキーが復号できなくなる可能性があります。
• Git 参照やパックファイルのメタデータは、暗号化されたマニフェスト内に保存されます。
• 秘密鍵ファイルは Unix 系システムでは 0600 パーミッションで作成されます。

制限事項

• このプロジェクトは実験段階であり、正式なセキュリティ監査は受けていません。
• 現在サポートされているのは、ローカルファイルシステム、Git バックエンド、オプションの SFTP ストレージバックエンドのみです。
• SFTP サポートはオプションの sftp 機能の背後にあり、現在 Windows ではサポートされていません。
• SFTP/Git バックエンドには堅牢な分散ロックが欠けているため、同時プッシュによりデータが失われる可能性があります。
• Git リモートヘルパーの動作はまだ比較的最小限であり、すべての Git ワークフローや CI/CD 操作をサポートしているわけではありません。
• フォースプッシュはサポートされていますが、通常の Git フォースプッシュと同様に、暗号化されたリモート履歴を書き換える可能性があります。
• HPKE クレートは Git ソースに依存しています。これは、公開されているクレートリリースでは XWing がまだサポートされていないためです。HPKE が更新され次第、この状態は変更されます。
• ユーザーアクセスを失効または削除する方法はありません。ユーザーは Git 履歴からマスターキーを復元できるため、最善の方法は新しいマスターキーでリポジトリを再初期化し、リモートを消去することです。
• ストレージ形式は将来のバージョンで変更される可能性があります。
• Git バックエンドストレージでは、コミットのために有効な Git 認証情報と構成済みの Git アイデンティティが必要です。
• Git、SSH、SFTP の認証に関して、pqcrypt は既存の SSH/Git 認証情報に依存します。
• ssh と git がインストールされている必要があります。