pepedebicki/pqenc

# pqenc 学习型 CLI（命令行界面），用于后量子文件加密。使用 **ML-KEM-768**（FIPS 203， 前身为 Kyber）作为密钥封装机制，并使用 **AES-256-GCM** 作为数据封装机制。使用 Rust 实现。 ## 免责声明 这是一个**学习和实验工具**。请勿将其用于生产数据、第三方数据或任何您无法承受丢失的数据。磁盘上的 `.pqe` 格式为本项目私有；与 `age`、PGP、OpenSSL 或任何其他工具**没有互操作性保证**。该格式有版本控制，并且可能在不同版本之间发生变化。有关完整的立场声明，请参阅 `docs/superpowers/specs/2026-04-25-pqenc-design.md`（§1）。 ## 构建 ``` cargo build --release ``` MSRV：Rust 1.75。无需 C 工具链或外部构建依赖。 ### Windows 注意事项 在 Windows 上，`windows-msvc` Rust 目标需要带有 C++ 工作负载的 Visual Studio 2022 Build Tools （提供 `link.exe` 和 Windows SDK）。只需安装一次： ``` winget install Microsoft.VisualStudio.2022.BuildTools ` --override "--wait --quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" ``` 然后在任何新的 PowerShell 会话中，对 `setenv.ps1` 进行 dot-source 以导入 MSVC 环境并将 rustup 切换到 `stable-msvc`： ``` . .\setenv.ps1 cargo build --release ``` `windows-gnu` 目标（某些 rustup 安装中的默认目标）另外还需要 带有 `dlltool.exe` 的可用 MinGW；在 Windows 上使用 MSVC 是最省事的 路径。 ## 用法 ### 生成密钥对 ``` pqenc keygen --out alice # writes alice.pqpub + alice.pqsec pqenc keygen --out alice --password # secret key wrapped with Argon2id + AES-GCM pqenc keygen --from-password --out alice # only alice.pqpub is written; # the secret key is reconstructed # from the passphrase on demand ``` ### 使用公钥加密 ``` pqenc encrypt --pubkey alice.pqpub --in notes.md pqenc encrypt --pubkey alice.pqpub --in project/ --out project.pqe --explain ``` 如果 `--in` 是一个目录，则内容在加密前（`FLAGS.is_archive = 1`）会在内存中打包为 TAR 归档文件。 ### 使用密码派生密钥加密 ``` pqenc encrypt --from-password --in notes.md ``` 发送方和接收方必须共享该密码。不涉及任何密钥文件。 ### 解密 ``` pqenc decrypt --seckey alice.pqsec --in notes.md.pqe pqenc decrypt --from-password --in notes.md.pqe --out notes.md --force ``` ### 检查 `.pqe` 头部 ``` pqenc inspect notes.md.pqe ``` 仅读取头部；从不打开 AEAD 载荷，也不需要密钥。 ## 文件格式 `.pqe` 完整详情：`docs/superpowers/specs/2026-04-25-pqenc-design.md` §3。 | 偏移量 | 长度 | 字段 | 描述 | |---------|--------|------------------|--------------------------------------------| | 0 | 4 | `MAGIC` | ASCII `"PQE1"`（魔术数字 + 格式版本 1） | | 4 | 1 | `ALGO_ID` | `0x01` = ML-KEM-768 + AES-256-GCM | | 5 | 1 | `FLAGS` | 位 0 = `is_archive`（内含 TAR） | | 6 | 2 | `RESERVED` | `0x0000` | | 8 | 1088 | `KEM_CIPHERTEXT` | ML-KEM-768 密文 | | 1096 | 12 | `AEAD_NONCE` | GCM nonce，通过 HKDF 派生并存储 | | 1108 | 32 | `HKDF_SALT` | 每个文件随机生成 | | 1140 | 8 | `PAYLOAD_LEN` | u64 小端序（AEAD 密文长度） | | 1148 | N | `AEAD_CT` | AES-256-GCM 密文 | | 1148+N | 16 | `AEAD_TAG` | GCM 认证标签 | 总大小：`1164 + N` 字节。 ## 安全准则 （规格说明 §7，精简版。） - 密钥从不被记录日志；秘密类型既不实现 `Debug` 也不实现 `Display`，并在丢弃时进行清零。 - AEAD 标签比较委托给 `aes-gcm` crate；不对手工编写的密钥材料进行等值检查。 - 随机性完全来源于 `rand::rngs::OsRng`。 - 密码使用 Argon2id（`m = 19 MiB, t = 2, p = 1`）进行哈希处理，盐值为来自 `OsRng` 的 16 字节。上下文字符串：`b"pqenc v1 kdf"`（HKDF info）， `b"pqenc v1 seed"`（Argon2 secret）。 - 每次加密都使用新的 KEM 封装和新的 32 字节 HKDF 盐值；没有密钥重用。 - 密码通过 `rpassword` 以交互方式读取；从不通过 CLI 参数、 环境变量或文件读取。 - 输出写入是原子性的（`tempfile::NamedTempFile::persist`）。 - 如果没有 `--force`，现有输出永远不会被覆盖。 - 解密错误统一归并为单一的 `DecryptionFailed`，以避免 oracle 风格的侧信道攻击。 ## 非目标 （规格说明 §10。） - 针对大于 RAM 的文件进行流式/分块加密。 - 数字签名（ML-DSA、Falcon、SPHINCS+）。 - 多接收方加密。 - 与 `age`、PGP、OpenSSL 或任何其他工具的互操作性。 - 密钥服务器，信任网络，密钥分发。 - GUI，守护进程模式，文件监视。 - 来自环境变量、文件或 CLI 参数的密码。 - 混合方案（ML-KEM + X25519）。`ALGO_ID` 字节为此留有 空间；v1 未实现。 ## 测试 ``` cargo fmt --check cargo clippy --all-targets -- -D warnings cargo test --all cargo audit ``` `cargo audit` 已集成到 `.github/workflows/ci.yml` 的 CI 工作流中。 KAT 集成测试（`tests/kat.rs`）在缺少 NIST 响应文件 `tests/kat/ml_kem_768.rsp` 时将被跳过。有关从何处获取官方向量的信息，请参阅 `tests/kat/ml_kem_768_README.md`。 ## 许可证 根据以下任一许可证授权： - MIT 许可证 - Apache 许可证，版本 2.0 由您选择。

标签：AES-256-GCM, Argon2id, CLI, DEM, DNS 反向解析, FIPS 203, KEM, Kyber, meg, ML-KEM-768, PQC, ProjectDiscovery, Rust, WiFi技术, 云配置检测, 信息安全, 公钥加密, 加密解密, 可视化界面, 后量子密码学, 学习项目, 实验性工具, 密码学, 密钥封装机制, 对称加密, 手动系统调用, 抗量子加密, 数据保护, 数据封装机制, 文件加密, 混合加密, 网络流量审计, 自动化审计, 蓝队防御, 通知系统, 非对称加密