git-remote-pqcrypt

这是一个实验性项目，尚未经过正式安全审计。请勿将其用于任何关键仓库。

git-remote-pqcrypt 是一个加密的 Git 远程助手，类似于 gcrypt。它以加密形式存储 Git packfile 和仓库元数据。访问时使用抗量子 XWing 封装。

当前 crate 版本：0.2.0。

工作原理

1. git-remote-pqcrypt init 创建仓库主密钥。
2. 每个用户的主密钥用其公钥进行封装。
3. Git packfile 和清单文件使用主密钥加密。
4. Git 通过 git-remote-pqcrypt 远程助手使用 pqcrypt。
5. 主密钥由助手在本地解密，然后 packfile 被解密到本地仓库。

远程存储的示例文件：

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 区分普通推送和强制推送。

普通推送会进行快进检查，如果会覆盖远程历史则会被拒绝。

远程助手行为

Git 通过 git-remote-pqcrypt 二进制文件将 pqcrypt 作为远程助手调用。

当被 Git 调用时，助手期望使用 Git 使用的远程助手参数格式，例如：

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

直接 CLI 子命令，如 init、add-user、keygen、pubgen 和 help，被视为普通用户命令，而非远程助手调用。

二进制入口点将任务委托给库运行时，因此应用程序逻辑可通过 crate 库以及已安装的二进制文件进行测试。

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 引用和 packfile 元数据存储在加密的清单文件中。
• 在类 Unix 系统上，私钥文件的权限设置为 0600。

局限性

• 本项目是实验性的，尚未经过正式安全审计。
• 目前仅支持本地文件系统、Git 后端和可选的 SFTP 存储后端。
• SFTP 支持位于可选的 sftp 功能之后，目前不支持 Windows。
• SFTP/Git 后端缺乏健壮的分布式锁定，因此并发推送可能导致数据丢失。
• Git 远程助手行为仍相对基础，可能不支持所有 Git 工作流或 CI/CD 操作。
• 支持强制推送，但与其他 Git 强制推送一样，可以重写加密的远程历史。
• HPKE crate 依赖于 Git 源，因为 XWing 在已发布的 crate 版本中尚不支持。一旦 HPKE 更新，此情况将改变。
• 没有撤销或移除用户访问的方法。由于用户可以从 Git 历史中恢复主密钥，最佳做法是使用新主密钥重新初始化仓库并清除远程。
• 存储格式可能在未来的版本中发生变化。
• Git 后端存储需要有效的 Git 凭据和已配置的 Git 身份以进行提交。
• 对于 Git、SSH 或 SFTP 身份验证，pqcrypt 依赖于现有的 SSH/Git 凭据。
• 必须安装 ssh 和 git。