jbaelaw/qshield
GitHub: jbaelaw/qshield
一款基于后量子混合加密的跨平台静态数据保护工具，提供抗量子计算的存储加密方案。
Stars: 0 | Forks: 0
QShield
Post-Quantum Hybrid Encryption for Files, Directories, and Whole Disks
QShield 将文件、目录和原始磁盘镜像/块设备加密为 `.qsv` 归档文件，采用 **混合后量子密钥封装** 方案。单个密码即可保护所有内容——无需 PKI 基础设施、无需密钥服务器、无需证书管理。
```
╔═══════════════════════════════════════════════════╗
║ QShield — Post-Quantum Storage Encryption ║
║ ML-KEM-768 + X25519 │ AES-256-GCM ║
╚═══════════════════════════════════════════════════╝
```
## 为何选择 QShield？
| 担忧 | QShield 的答案 |
|---|---|
| **量子威胁** | ML-KEM-768（NIST FIPS 203，安全等级 3）——可抵御未来量子计算机上的 Shor 算法 |
| **经典回退** | 混合模式下的 X25519 ECDH ——即使 ML-KEM 被经典算法破解，X25519 仍能保护密钥 |
| **仅密码保护** | Argon2id 将单个密码扩展为所有密钥材料 ——无需密钥文件、无需证书 |
| **整盘加密支持** | `encrypt-disk` / `decrypt-disk` 以零内存缓冲流式处理原始字节 ——可处理多 TB 外置硬盘 |
| **单一二进制文件** | 静态链接的 Rust 二进制文件，约 3 MB，无运行时依赖 |
| **跨平台支持** | macOS（Apple Silicon + Intel）、Linux x86_64、Windows x64 |
## 威胁模型
QShield 旨在保护 **静态数据**，防止针对便携式存储介质（外置 HDD、U盘、备份镜像）的攻击：
- **当前窃取，未来解密攻击** ——攻击者今天捕获加密数据，等待未来量子计算机进行解密
- **离线暴力破解** ——Argon2id 的 64 MiB 内存成本使 GPU/ASIC 攻击成本过高
- **单一原语密钥泄露** ——混合 KEM 确保 ML-KEM-768 和 X25519 **同时**被破解才可能危及卷密钥
**不在范围内：** QShield 不提供实时全磁盘加密（如 LUKS/BitLocker）、不可否认性，或在攻击者拥有实时系统访问权限时的保护。
## 安装
### 预构建二进制文件
从 [发布页面](https://github.com/jbaelaw/qshield/releases/latest) 下载：
| 平台 | 架构 | 文件 | SHA-256 |
|---|---|---|---|
| macOS | Apple Silicon（M1/M2/M3/M4） | `qshield-macos-aarch64.tar.gz` | `.sha256` |
| macOS | Intel x86_64 | `qshield-macos-x86_64.tar.gz` | `.sha256` |
| Linux | x86_64（glibc） | `qshield-linux-x86_64.tar.gz` | `.sha256` |
| Windows | x86_64 | `qshield-windows-x86_64.zip` | `.sha256` |
```
# macOS / Linux
tar xzf qshield-macos-aarch64.tar.gz
sudo mv qshield /usr/local/bin/
qshield --version
# Windows (PowerShell)
Expand-Archive qshield-windows-x86_64.zip -DestinationPath .
.\qshield.exe --version
```
### 从源码构建
需要 [Rust](https://rustup.rs/) 1.74 或更高版本：
```
git clone https://github.com/jbaelaw/qshield.git
cd qshield
cargo build --release
# Binary at target/release/qshield
```
### 验证下载完整性
每个发布版本均包含 SHA-256 校验和：
```
shasum -a 256 -c qshield-macos-aarch64.tar.gz.sha256
```
## 用法
### 交互式 TUI 模式
运行 `qshield`（不带参数）即可启动终端 UI：
```
qshield
```
TUI 提供菜单驱动界面，包含以下功能：
| 功能 | 描述 |
|---|---|
| 加密文件/文件夹 | 归档并加密文件或目录 |
| 解密文件/文件夹 | 解密并提取 `.qsv` 归档 |
| 整盘/块设备加密 | 按字节精确加密磁盘镜像或块设备 |
| 整盘/块设备解密 | 将加密磁盘镜像还原为原始内容 |
| 验证 | 不解压即可检查归档完整性 |
| 信息 | 显示加密元数据 |
所有操作均显示实时进度条和屏蔽式密码输入。
### CLI — 文件与文件夹加密
```
# Encrypt a file (interactive password prompt)
qshield encrypt secret.pdf
# Encrypt a directory with explicit output path
qshield encrypt ./confidential/ -o confidential.qsv
# Overwrite existing output
qshield encrypt ./docs/ -o docs.qsv --force
# Decrypt to a specific directory
qshield decrypt docs.qsv -o ./restored/
# Non-interactive mode (scripting / automation)
qshield encrypt data.zip -p "strong-passphrase-here" -o data.qsv
qshield decrypt data.qsv --password "strong-passphrase-here" -o ./output
# Verify integrity without extracting
qshield verify data.qsv --password "strong-passphrase-here"
# Inspect cryptographic metadata
qshield info data.qsv
```
### CLI — 整盘 / 块设备加密
使用 **流式 I/O** 加密原始磁盘镜像和块设备 ——无 tar 包装、无内存缓冲、字节级精确还原：
```
# Encrypt a disk image file
qshield encrypt-disk /path/to/backup.img -o backup.qsv
# macOS: encrypt an external drive (UNMOUNT FIRST)
diskutil unmountDisk /dev/disk4
sudo qshield encrypt-disk /dev/disk4 -o external_hdd.qsv
# Linux: encrypt a USB drive
sudo umount /dev/sdb
sudo qshield encrypt-disk /dev/sdb -o usb_drive.qsv
# Decrypt to an image file
qshield decrypt-disk backup.qsv -o restored.img --force
# Decrypt directly to a block device (CAUTION: overwrites entire device)
sudo qshield decrypt-disk external_hdd.qsv -o /dev/disk4 --force
# Verify and inspect
qshield verify backup.qsv --password "passphrase"
qshield info backup.qsv
```
**磁盘模式安全特性：**
| 功能 | 描述 |
|---|---|
| 块设备检测 | 通过操作系统文件类型元数据自动识别 |
| 卸载警告 | 在读取/写入设备前提示用户卸载 |
| 交互确认 | 执行设备操作前需显式输入 `y` |
| 字节级还原 | 头部存储原始大小 ——无填充伪影 |
| 平台原生尺寸 | macOS 使用 `diskutil`，Linux 使用 `blockdev`，支持回退到 seek 到末尾 |
| 跨命令防护 | `decrypt` 拒绝处理原始磁盘文件（建议改用 `decrypt-disk`） |
### 支持的输入类型
QShield 可加密 **任意文件、目录或块设备**。自动类型检测提供可读描述：
| 类别 | 扩展名 / 类型 |
|---|---|
| 磁盘镜像 | `.iso`, `.img`, `.dmg`, `.vhd`, `.vhdx`, `.vmdk`, `.qcow2` |
| 归档文件 | `.zip`, `.tar`, `.gz`, `.bz2`, `.xz`, `.zst`, `.7z`, `.rar` |
| 文档 | `.pdf`, `.doc(x)`, `.xls(x)`, `.ppt(x)`, `.txt`, `.csv` |
| 媒体 | `.jpg`, `.png`, `.gif`, `.mp4`, `.mkv`, `.mp3`, `.flac`, `.wav` |
| 数据 | `.json`, `.xml`, `.html`, `.sql`, `.db`, `.sqlite` |
| 可执行文件 | `.exe`, `.dll`, `.so`, `.dylib`, `.bin` |
| 加密文件 | `.key`, `.pem`, `.crt`, `.p12`, `.gpg` |
| 目录 | 任意文件夹（递归归档为 tar） |
| 块设备 | `/dev/diskN`（macOS）、`/dev/sdX`（Linux）——通过 `encrypt-disk` |
所有输入均按不透明字节流处理 ——QShield 不会解析或修改文件内容。
## 加密架构
### 密钥派生与封装流程
```
┌─────────────┐
│ Password │
└──────┬──────┘
│
Argon2id (64 MiB, 3 iter, 4 lanes)
│
┌──────▼──────┐
│ Master Key │──────┐
│ (256-bit) │ │
└──────┬──────┘ │
│ Encrypts KEM
┌────────────┴────────────┐ private keys
│ │ (AES-256-GCM)
┌──────▼──────┐ ┌───────▼───────┐
│ ML-KEM-768 │ │ X25519 ECDH │
│ (FIPS 203) │ │ (RFC 7748) │
└──────┬──────┘ └───────┬───────┘
│ shared secret │ shared secret
└────────────┬────────────┘
│
HKDF-SHA3-256 (SP 800-56C)
│
┌──────▼──────┐
│ Volume Key │
│ (256-bit) │
└──────┬──────┘
│
AES-256-GCM (SP 800-38D)
1 MiB streaming chunks
│
┌──────▼──────┐
│ Encrypted │
│ Data │
└─────────────┘
```
### 算法选择理由
| 层 | 算法 | 标准 | 安全等级 | 理由 |
|---|---|---|---|---|
| PQ 密钥封装 | ML-KEM-768 | NIST FIPS 203 | Level 3（相当于 AES-192） | 首个 NIST 标准化格基 KEM；安全与性能平衡 |
| 经典密钥协商 | X25519 | RFC 7748 | ~128 位经典 | 广泛部署、常数时间、无专利；格假设失效时的混合回退 |
| 密钥组合 | HKDF-SHA3-256 | SP 800-56C | 256 位 | 域分离提取确保 KEM 贡献相互独立 |
| 密码拉伸 | Argon2id | RFC 9106 | 内存硬 | 64 MiB 内存成本抵御 GPU/ASIC 暴力破解；抗侧信道 |
| 批量加密 | AES-256-GCM | SP 800-38D | 256 位 | 硬件加速（AES-NI），带每块独立 nonce 的认证加密 |
### 混合 KEM 设计
混合构造遵循 NIST 为过渡后量子部署推荐的 **组合器** 方法：
1. **独立密钥生成** ——分别生成 ML-KEM-768 与 X25519 密钥对
2. **独立封装** ——每个 KEM 产生自己的共享秘密
3. **域分离组合** ——使用 HKDF-SHA3-256 以不同上下文标签组合两个秘密 4. **纵深防御** ——单一原语泄露不足以恢复卷密钥
这确保在 **至少一个** KEM 原语保持安全的前提下整体安全。
### 流式加密
批量数据以 1 MiB 为块进行加密，每块使用带认证标签的独立加密：
```
For each chunk i:
nonce[0..8] = i as u64 (little-endian counter)
nonce[8..12] = random (4 bytes from OS CSPRNG)
ciphertext_i = AES-256-GCM(volume_key, nonce, plaintext_chunk_i)
```
计数器组件防止跨块 nonce 复用；随机组件确保同一密钥下的加密具有额外唯一性。
## 交互式 TUI 截图
TUI 特性：
| 功能 | 描述 |
|---|---|
| **步骤指示器** | 工作流程中的视觉面包屑导航 |
| **密码强度计** | 实时强度评估（弱/一般/良好/强）及可视化条 |
| **磁盘确认对话框** | 执行块设备操作前的显式 Yes/No 提示 |
| **动画进度** | 加密/解密时的旋转指示器与耗时显示 |
| **可滚动信息** | 使用 ↑↓ 键浏览加密元数据 |
| **上下文敏感帮助** | 底部栏根据当前屏幕动态变化 |
| **Vim 风格导航** | 全界面支持 `j`/`k` 与 ↑↓ 键操作 |
## `.qsv` 文件格式规范
```
Offset Size Field
────── ────── ──────────────────────────────────────────
0x00 4 B Magic number: "QSV1" (0x51 0x53 0x56 0x31)
0x04 1 B Format version (currently 0x01)
0x05 1 B KEM algorithm ID (0x01 = ML-KEM-768 + X25519)
0x06 1 B Content type (0x00 = Tar Archive, 0x01 = Raw Disk)
0x07 8 B Original plaintext size (u64 LE) — for byte-exact restore
0x0F 32 B Argon2id salt
0x2F var [u16 LE length] ML-KEM encapsulation key (1184 B for ML-KEM-768)
var [u16 LE length] ML-KEM decapsulation key (encrypted, ~2416 B + GCM overhead)
32 B X25519 public key
var [u16 LE length] ML-KEM ciphertext (1088 B for ML-KEM-768)
32 B X25519 ephemeral public key
var [u16 LE length] X25519 secret key (encrypted, 32 B + GCM overhead)
────────────────────────────────────────────────────────────
Data stream (repeating):
4 B Encrypted chunk length (u32 LE); 0x00000000 = end sentinel
12 B Nonce (8 B counter + 4 B random)
var Ciphertext + 16 B GCM authentication tag
```
**头部大小：** 对于 ML-KEM-768 + X25519，约为 4,817 字节。
**加密敏捷性：** KEM 算法标识字节允许未来版本引入新算法（例如 ML-KEM-1024、HQC），而无需破坏向后兼容性。
## 安全特性
### 保障
| 特性 | 机制 |
|---|---|
| **机密性** | 每块独立 nonce 的 AES-256-GCM |
| **完整性** | 每 1 MiB 块的 GCM 认证标签 |
| **真实性** | 密码派生的主密钥认证加密者 |
| **前向安全性** | 每次加密使用临时 KEP 密钥对 ——不存储长期私钥 |
| **密钥清零** | 所有敏感密钥材料（`master_key`、`volume_key`、密码）通过 `zeroize` 库在用后立即清零 |
| **反 DoS** | 解密拒绝超过 1 MiB + 64 字节的块 |
| **路径遍历防护** | Tar 提取验证所有入口路径，禁止 `../`、绝对路径及前缀组件 |
| **符号链接安全** | 符号链接以链接形式记录（不跟随）；符号链接输入将被拒绝 |
### 限制与注意事项
- **非实时 FDE：** QShield 将文件/镜像加密为 `.qsv` 容器，不提供类似 LUKS/BitLocker/FileVault 的透明块层加密
- **无密钥托管：** 若密码丢失，数据不可恢复。设计上无恢复机制
- **未审计的加密依赖：** 底层 RustCrypto 库（`ml-kem`、`aes-gcm`、`argon2`、`x25519-dalek`）尚未独立审计；未执行形式化侧信道分析
- **单线程加密：** 批量加密使用单线程，数据量与时间线性增长
- **GCM 随机数空间：** 8 字节计数器 + 4 字节随机 nonce，理论上限为 2^64 块（~16 EiB/加密）；实际无约束
## 性能
在 Apple M2 Pro（macOS 14，发布版）上的实测：
| 操作 | 数据量 | 耗时 | 吞吐 |
|---|---|---|---|
| 加密文件 | 100 MiB | ~1.0s | ~100 MiB/s |
| 解密文件 | 100 MiB | ~1.0s | ~100 MiB/s |
| 加密整盘 | 1 GiB | ~10s | ~100 MiB/s |
| Argon2id 密钥派生 | — | ~0.4s | — |
吞吐主要由带 AES-NI 硬件加速的 AES-256-GCM 决定；Argon2id 密钥派生增加固定 ~0.4s 开销，与数据量无关。
## 项目结构
```
qshield/
├── src/
│ ├── main.rs # CLI entry point, command handlers
│ ├── crypto/
│ │ ├── kem.rs # ML-KEM-768 + X25519 hybrid encapsulation
│ │ ├── kdf.rs # Argon2id password stretching, HKDF key combination
│ │ └── symmetric.rs # AES-256-GCM single-shot and streaming encryption
│ ├── volume/
│ │ └── format.rs # QSV header serialization and parsing
│ ├── tui/
│ │ ├── app.rs # Interactive terminal UI state machine
│ │ └── widgets.rs # Ratatui UI components
│ ├── error.rs # Error types
│ └── ui.rs # CLI progress bars and formatted output
├── .github/workflows/
│ ├── ci.yml # Test + Clippy + Format on every push/PR
│ └── release.yml # Cross-platform binary builds on tag push
├── CHANGELOG.md # All notable changes per version
├── SECURITY.md # Vulnerability reporting policy
├── CONTRIBUTING.md # Development setup and contribution guidelines
├── LICENSE # MIT License
└── Cargo.toml # Dependencies and build configuration
```
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发环境设置、编码规范与提交流程。
## 许可证
[MIT](LICENSE) —— 版权所有 (c) 2026 Jiho Bae
## 感谢
QShield 基于 [RustCrypto](https://github.com/RustCrypto) 生态构建：
- [`ml-kem`](https://crates.io/crates/ml-kem) —— ML-KEM (FIPS 203) 实现
- [`x25519-dalek`](https://crates.io/crates/x25519-dalek) —— X25519 迪菲-赫尔曼
- [`aes-gcm`](https://crates.io/crates/aes-gcm) —— AES-256-GCM 认证加密
- [`argon2`](https://crates.io/crates/argon2) —— Argon2id 密码哈希
- [`sha3`](https://crates.io/crates/sha3) / [`hkdf`](https://crates.io/crates/hkdf) —— SHA3-256 与 HKDF 密钥派生
- [`ratatui`](https://crates.io/crates/ratatui) —— 终端用户界面框架
标签：AES-256-GCM, Argon2id, CI, ML-KEM-768, NIST FIPS 203, ProjectDiscovery, .qsv, Rust, Shor算法, X25519, ZAP项目解析, 全盘加密, 加密存档, 单一可执行文件, 可视化界面, 后量子加密, 块设备加密, 存储加密, 密码保护, 密钥封装, 密钥派生, 数据保护, 文件加密, 文档结构分析, 无PKI, 混合加密, 目录加密, 磁盘加密, 网络流量审计, 蓝队防御, 软件发布, 通知系统, 量子安全