LUKSbox

能够安然度过下一个十年的加密保险库。
开源、原生支持 FIDO2 + TPM 2.0、具备抗量子计算能力。
在云端或共享介质上存储敏感文件，无需信任宿主环境。

Built by

网站 · 文档 · 安全性 · Fuzzing · 对比

## 它解决了什么问题 您可能已经将敏感文件存储在您无法完全控制的存储位置：云同步（iCloud、Drive、Dropbox、OneDrive、S3、Backblaze）、NAS 设备、随身携带的 U 盘、最终被回收商处理的备份磁带。服务提供商承诺使用“他们的密钥”进行静态加密。而 LUKSbox 会在文件离开您的设备之前，使用**您的**密钥对其进行加密，并存放在一个对提供商来说不透明且在回传时能防篡改的单一容器中。 一个 LUKSbox 保险库就是一个文件（`.lbx`），可选择带有分离的头部文件（`.hdr`）和后量子辅助文件（`.kyber`），您可以将它们保存在不同的存储介质上。把它丢在任何云服务或共享介质上即可。服务提供商只能看到一个与随机数据无异的数据块，即使在法律强制要求下也无法解密。当您需要使用时，可以在本地将其挂载为一个真实的驱动器。 | 关注点 | 直接上传至云端 | 云端 + 服务商加密 | 云端上的 LUKSbox 保险库 | |---|---|---|---| | 服务商可以读取您的文件 | 是 | 是（他们持有密钥） | **否** | | 面向服务商的政府数据调令会暴露数据 | 是 | 是 | **否** | | 检测到静默文件篡改 | 否 | 有时（仅在 TLS 传输过程中） | **是**（基于每个数据块的 AEAD） | | 检测到整个保险库的回滚 | 否 | 否 | **是**（锚点辅助文件） | | “现在窃取，以后解密”（后量子威胁） | 脆弱 | 脆弱 | **ML-KEM-768/1024 混合插槽** | | 打开时需要硬件密钥 | 不适用 | 取决于服务商 | **FIDO2 / TPM / Windows Hello** | | 保险库文件看起来像随机数据 | 否 | 否 | **是**（带有分离的头部文件时） | | 可供审计的源代码 | 否 | 否 | **是**（Apache-2.0） | 完整的各工具对比（对比 LUKS2 / VeraCrypt / age / gocryptfs / Cryptomator / BitLocker / FileVault）位于 。 ## 状态 这是一个 **1.0 之前的版本**。磁盘格式已锁定，加密原语为基于 RustCrypto 构建的 NIST/RFC 标准，并且已发布了 9 轮内部审计。外部付费审计和更广泛的实际部署是下一个里程碑。云存储威胁模型——即服务提供商即使接到传票也无法读取您的数据——正是 LUKSbox 为之构建的目标，也是它目前所实现的功能。 | 方面 | 状态 | |---|---| | `cargo test --workspace` | 200+ 个通过，0 个失败，0 个忽略 | | `cargo audit` (Linux/macOS) | 0 个漏洞 / 0 个不健全 / 0 个无人维护 | | `cargo audit` (Windows) | 1 个无人维护（`registry`，通过 WinFsp 传递引入） | | 内部审计轮数 | 9 轮记录在 （每轮细节保密） | | 第三方审计 | 尚未进行；可通过邮件向 `security@penthertz.com` 索要评估范围包 | | 跨 10 个 libFuzzer harness 的模糊测试迭代 | 30M+ | ## 保险库的打开方式 ``` flowchart LR User[User knowledge
passphrase or PIN] --> Unlock[Unlock material] FIDO[FIDO2 authenticator
hmac-secret] --> Unlock TPM[TPM 2.0
sealed KEK] --> Unlock PQ[ML-KEM seed file
separate storage] --> Unlock Unlock --> KEK[Key encryption key] KEK --> MVK[Master volume key] MVK --> HeaderMac[Header HMAC key] MVK --> MetadataKey[Metadata AEAD key] MVK --> FileKeys[Per-file HKDF keys] MVK --> AnchorKey[Anchor HMAC key] HeaderMac --> Header[Authenticated header] MetadataKey --> Metadata[Encrypted metadata tree] FileKeys --> Chunks[Encrypted file chunks] AnchorKey --> Anchor[Rollback anchor] ``` 主卷密钥（MVK）是根密钥。密钥插槽并不直接加密文件；它们封装的是 MVK。一旦有效的密钥插槽解封装了 MVK，保险库中的所有其他密钥都会通过带有特定用途 `info` 字符串的 HKDF-SHA256 从中派生出来。丢失了密钥插槽的材料，就会丢失 MVK；撤销某个插槽后，该材料将永久无法从此保险库中恢复 MVK。 完整的架构图（磁盘结构图、解锁序列、并发/崩溃安全管线、磁盘占用空间）请参阅 。 ## 安全机制 | 机制 | 功能 | 所在位置 | |---|---|---| | AES-256-GCM-SIV（默认）/ AES-256-GCM / ChaCha20-Poly1305 | 对每个文件块和元数据 blob 进行 AEAD 保护 | `crates/luksbox-core/src/aead.rs` | | 覆盖整个 8 KiB 头部的 HMAC-SHA256 | 在密钥插槽解封装 MVK 后检测头部篡改 | `crates/luksbox-core/src/header.rs` | | 带有特定用途 `info` 字符串的 HKDF-SHA256 | 从 MVK 派生所有子密钥；唯一性通过回归测试验证 | `crates/luksbox-core/src/key.rs` | | Argon2id（默认 256 MiB / 3 / 4） | 拉伸口令；解析器限制成本参数以拒绝 DoS 攻击 | `crates/luksbox-core/src/kdf.rs` | | FIDO2 hmac-secret (CTAP2 §6.5) | 硬件支持的解锁、封装模式或直接模式 | `crates/luksbox-fido2/` | | TPM 2.0 密封的 KEK (Linux) | 将保险库绑定到本地芯片；可选 PIN；融合的 TPM+FIDO2 模式 | `crates/luksbox-tpm/` | | ML-KEM-768 / ML-KEM-1024 (FIPS 203) | 每个混合密钥插槽的后量子半部分；通过 HKDF 混合传统与后量子算法 | `crates/luksbox-pq/` | | 每个块的 AAD（`file_id ‖ chunk_index ‖ generation`） | 检测块替换、位置交换以及在相同位置重放旧块 | `crates/luksbox-vfs/src/chunk.rs` | | 分离式头部辅助文件（`.hdr`） | 仅保险库文件本身是不透明的随机数据，无 magic number、无版本、无密钥插槽 | `crates/luksbox-format/src/container.rs` | | 锚点辅助文件（`.anchor`） | 通过基于 MVK 密钥的 HMAC 对生成计数器进行外部回滚检测 | `crates/luksbox-format/src/anchor.rs` | | 读前锁定打开 | 并发的注册/撤销操作不会在密钥插槽表上发生竞争 | `crates/luksbox-format/src/container.rs::open` | | 锁定后的路径 inode 重新 stat | 通过 `Error::PathSubstituted` 捕获狭窄的先打开后重命名 TOCTOU 竞争条件 | `crates/luksbox-format/src/container.rs::verify_path_inode` | | 原子临时文件 + 重命名 + 父目录 fsync | 所有辅助文件的写入在断电后仍能存活；适用于 POSIX（目录句柄上的 `fsync`）和 Windows（`FILE_FLAG_BACKUP_SEMANTICS` + `FlushFileBuffers`） | `crates/luksbox-core/src/file_util.rs` | | 明文提取时的 `O_NOFOLLOW` | `luksbox get` 会拒绝预先存在的符号链接目标，以阻止攻击者预设的符号链接目标覆盖行为 | `crates/luksbox-core/src/file_util.rs::secure_create_or_truncate` | | 在 Linux 5.14+ 上针对已解锁 MVK 使用 `memfd_secret(2)` | 将 MVK 排除在核心转储和休眠镜像之外；在其他平台上使用 `mlock` + `Zeroize` 回退方案 | `crates/luksbox-core/src/secret_box.rs` | | 针对每个携带机密的中间变量进行工作区范围的 `Zeroizing` 审计 | AEAD 明文、HKDF I/O、ML-KEM 共享密钥、CLI/GUI PIN 副本均在 drop 时被清理 | 覆盖 `luksbox-core`、`luksbox-pq`、`luksbox-tpm`、`luksbox-cli` | 完整的攻击矩阵（已防御 vs 未防御）位于 。 ## 快速开始 ``` # 创建一个 vault (默认: AES-256-GCM-SIV, Argon2id interactive) luksbox create my-vault.lbx # 将其挂载到 drive letter / mountpoint luksbox mount my-vault.lbx /mnt/v # Linux/macOS luksbox mount my-vault.lbx Z: # Windows # 添加 FIDO2 硬件因子 luksbox enroll my-vault.lbx --kind fido2 # 添加绑定到本机的 TPM 2.0 keyslot (Linux) luksbox enroll my-vault.lbx --kind tpm2 # Hybrid post-quantum：需要单独的 `.kyber` seed 文件 luksbox create my-vault.lbx --kind hybrid-pq \ --pq-hybrid /media/usb/my.kyber # Interactive walkthrough，无需记住 flags luksbox wizard ``` 三种接口，同一种磁盘格式：用于脚本的 `luksbox` CLI、交互式 TUI 的 `luksbox wizard` 以及 `luksbox-gui` 桌面应用程序。请参阅 获取各项流程的操作指南。 ## 安装 | 平台 | 方法 | |---|---| | Debian / Ubuntu / Mint | 来自[发布页](https://github.com/penthertz/LUKSbox/releases)的 `.deb` 包，`sudo apt install ./luksbox_*_amd64.deb` | | Fedora / RHEL / Rocky | 来自发布页的 `.rpm` 包，`sudo dnf install ./luksbox-*.x86_64.rpm` | | macOS | 来自发布页的 `.dmg` 包，拖入 /Applications，首次运行时安装 macFUSE | | Windows | 来自发布页的 `.msi` 包，自动安装 WinFsp | | 从源码构建 | 按照 [`BUILDING.md`](BUILDING.md) 中的依赖说明后，执行 `cargo build --release -p luksbox-cli -p luksbox-gui` | Linux 发布 tarball 中的 `dist/install.sh` 可以选择配置 TPM 权限（创建 `tss` 组，添加 udev 规则），这样您就可以在不使用 root 的情况下使用 TPM 密钥插槽。 ## 帮助发现 Bug LUKSbox 是一个年轻的代码库。其密码学基于标准化的原语和经过充分审计的 Rust 库（RustCrypto、libfido2、tss-esapi），但集成层和磁盘格式是我们自己开发的。我们**希望**有外部的目光来审查它。 ### 运行 Fuzzer 每个处理攻击者可控字节的解析器都在 [`fuzz/`](fuzz/) 中有一个 libFuzzer harness，并在 [`fuzz-afl/`](fuzz-afl/) 中有一个 AFL++ harness。PR CI 会在持久化语料库上运行每个 libFuzzer 目标 5 分钟；一台专用服务器会在每次发布前运行 AFL++ 活动长达数小时。 ``` cargo install cargo-fuzz cd fuzz cargo +nightly fuzz run header_parse -- -max_total_time=300 ``` 当前的目标列表（`header_parse`、`keyslot_parse`、`metadata_parse`、`hybrid_sidecar_parse`、`seed_file_parse`、`auth_then_process`、`header_roundtrip`、`winfsp_path_parse`、`webauthn_device_path`、`vfs_ops`）以及各目标的恒定断言位于 [`FUZZING.md`](FUZZING.md) 中。 ### 添加语料库种子 推动模糊测试进一步发展的最快方法是将真实世界的输入文件放入 [`fuzz/corpus//`](fuzz/corpus/) 并提交 PR。目前有帮助的示例包括： - 来自旧保险库结构（V1 / V2）的真实头部，用于 `header_parse` - 特定于验证器的 cred ID（Google Titan、SoloKey stateless、Trezor），用于 `keyslot_parse` - 边缘情况的 Windows 路径（UNC、网络共享、带有设备命名空间前缀的长路径），用于 `winfsp_path_parse` - 截断或扩展的 `.hybrid` 辅助文件，用于 `hybrid_sidecar_parse` ### 添加新的模糊测试目标 如果某个解析器还没有 harness，并且您可以想象攻击者会塑造其输入，请添加一个。请参阅 [`FUZZING.md`](FUZZING.md) 中的 harness 模板。 ### 提出回归测试建议 如果您发现某个代码路径的恒定断言没有被测试，但觉得应该被，请提交一个常规的 GitHub issue（标记为 `security-regression`），并用纯文本描述该恒定断言。我们会编写测试并在更新日志中致谢您的建议。 ### 运行 AFL++ 活动 [`scripts/fuzz_server.sh`](scripts/fuzz_server.sh) 会无限期地对任何目标运行 AFL++ 活动。如果您有空闲的计算资源，并且想找出 libFuzzer 在 5 分钟 PR 运行中遗漏的问题，这就是您的机会。 ## 报告问题 | 类别 | 渠道 | 优先级 | |---|---|---| | **疑似漏洞**（密钥恢复、明文泄露、身份验证绕过、FUSE/WinFsp 沙箱逃逸、可通过构造的保险库文件触发的整数/内存不安全） | 发送邮件至 `security@penthertz.com`（PGP 密钥见 [`SECURITY.md`](SECURITY.md)）。72 小时确认 SLA。**切勿**公开创建 issue。 | **P0**，修复 + 公告 + 协调披露 | | **格式错误的输入导致崩溃**，且您可以复现 | 附带输入文件和崩溃目标名称的 GitHub issue。使用 `fuzz-crash` 标签。 | **P1**，在下个版本中提供复现器 + 回归测试 | | **功能错误**（CLI/GUI/wizard 行为异常、挂载问题、恢复流程缺失、磁盘格式边缘情况） | 带有复现步骤的 GitHub issue。使用 `bug` 标签。 | **P2**，一周内进行分类 | | **文档问题**（错误声明、缺失说明、链接失效、措辞不清） | GitHub issue 或 PR。使用 `docs` 标签。 | **P3**，在下次文档更新中修复 | | **功能请求** | GitHub issue。使用 `feature` 标签。说明您的威胁模型，以便我们决定其是否符合项目范围。 | **P3**，进行讨论；可能列入[路线图](docs/TPM_FUTURE_IMPROVEMENTS.md)或附因拒绝 | | **审计任务**（您希望获得特定范围的任务来审查某个具体攻击面） | 发送邮件至 `security@penthertz.com`。我们将为您提供聚焦的范围（例如 FIDO2 FFI 中的 unsafe Rust、CLI 参数解析器、FUSE 适配器）以及撰写模板。 | 已排期 | 疑似漏洞的优先级高于一切。我们会在 72 小时内回复，并在公开更新日志及我们发布的任何公告中致谢报告者。 ## 仓库结构 ``` luksbox/ ├── crates/ # Rust workspace: core crypto, format, VFS, │ │ # FIDO2/TPM/PQ, mount, CLI, GUI │ ├── luksbox-core/ # Crypto primitives + on-disk header │ ├── luksbox-format/ # Container I/O, anchor, hybrid sidecar │ ├── luksbox-vfs/ # In-memory directory tree atop a Container │ ├── luksbox-fido2/ # FIDO2 hmac-secret + libfido2 / webauthn FFI │ ├── luksbox-tpm/ # Linux TPM 2.0 wrap/unwrap (gated) │ ├── luksbox-pq/ # ML-KEM-768 / 1024 + .kyber seed file │ ├── luksbox-mount/ # FUSE3 (Linux/macOS) + WinFsp (Windows) │ ├── luksbox-cli/ # `luksbox` binary + `luksbox wizard` TUI │ └── luksbox-gui/ # `luksbox-gui` egui desktop app ├── fuzz/ # cargo-fuzz harnesses (libFuzzer) ├── fuzz-afl/ # cargo-afl harnesses (AFL++) ├── assets/ # Repo-level branding (LUKSbox + Penthertz logos used by the README) ├── dist/ # Packaging metadata + install.sh ├── scripts/ # Operational scripts (release, fuzz, audit) ├── docs/ # Public docs: spec, architecture, side-channel notes, roadmaps ├── BUILDING.md # Per-platform build instructions ├── DEVELOPMENT.md # Maintainer dev workflow + release process ├── FUZZING.md # Fuzz harness setup + target list ├── TESTING.md # Test taxonomy + how to run each tier ├── SECURITY.md # Threat model, disclosure policy, known limitations ├── TRADEMARK.md # LUKSbox / Penthertz trademark policy ├── LICENSE # Apache License 2.0 └── NOTICE # Attribution notice (per Apache 2.0 §4) ``` ## 文档 完整文档位于 ： | 章节 | 内容 | |---|---| | [文档中心](https://luksbox.penthertz.com/docs/) | 安装 + 各流程操作指南（CLI / TUI / GUI） | | [密钥插槽](https://luksbox.penthertz.com/docs/keyslots/) | 口令、FIDO2、TPM 2.0、混合后量子 | | [安全性](https://luksbox.penthertz.com/docs/security/) | 架构（含图表）、威胁模型、密码学、测试、审计、披露 | | [对比](https://luksbox.penthertz.com/compare/) | LUKSbox vs LUKS2 / VeraCrypt / age / gocryptfs / Cryptomator / BitLocker / FileVault | | [常见问题](https://luksbox.penthertz.com/docs/faq/) | 云端使用、成熟度、许可协议、硬件支持、恢复 | 面向贡献者的仓库内参考资料： - [`SECURITY.md`](SECURITY.md)，披露策略 + 威胁模型摘要 - [`BUILDING.md`](BUILDING.md)，各平台构建说明 - [`TESTING.md`](TESTING.md)，测试分类 + 如何运行各项测试 - [`FUZZING.md`](FUZZING.md)，模糊测试 harness 设置 + 目标列表 - [`DEVELOPMENT.md`](DEVELOPMENT.md)，维护者开发工作流 + 发布流程 - [`docs/CRYPTO_SPEC.md`](docs/CRYPTO_SPEC.md)，逐操作的密码学详解 - [`docs/SECURITY_ARCHITECTURE.md`](docs/SECURITY_ARCHITECTURE.md)，安全架构图（网站页面的镜像） - [`docs/HARDWARE_SIDE_CHANNEL_NOTES.md`](docs/HARDWARE_SIDE_CHANNEL_NOTES.md)，针对 FIDO2 芯片的已公开侧信道攻击 - [`docs/TPM_LINUX_PERMISSIONS.md`](docs/TPM_LINUX_PERMISSIONS.md)，面向终端用户的 `/dev/tpmrm0` 访问操作手册 - [`docs/PROJECT_OVERVIEW.md`](docs/PROJECT_OVERVIEW.md)，项目概述 + 与 LUKS2 / VeraCrypt 的对比 - [`docs/TPM_FUTURE_IMPROVEMENTS.md`](docs/TPM_FUTURE_IMPROVEMENTS.md)，TPM 路线图（Windows TBS、PCR 密封） ## 许可协议 源代码在 [Apache License, Version 2.0](LICENSE) 下授权。LUKSbox 是 **OSI 批准的开源软件**：您可以阅读源码、审计密码学、自行构建、进行修改、重新分发，并在包括与 LUKSbox 竞争的任何商业产品中使用它。Apache 2.0 授权包含来自每位贡献者的明确专利许可，这对于密码学项目至关重要。 版权许可明确未授予的权限是，在您的衍生作品中使用 LUKSbox 或 Penthertz **商标**的权利；请参阅 [TRADEMARK.md](TRADEMARK.md)。您可以派生代码并发布它；但您不能将您的派生版本称为“LUKSbox”，也不能暗示得到 Penthertz 的认可。 [NOTICE](NOTICE) 文件包含下游再分发者必须保留的归属说明（根据许可协议的通知部分）。 [DISCLAIMER](DISCLAIMER.md) 重申了无担保/无责任条款（许可协议的第 7 和第 8 节）、任何加密容器面临的数据丢失现实，以及出口管制责任，均以通俗英文表述。在依赖 LUKSbox 保护重要信息之前，请务必仔细阅读一遍。 ## 作者 由 **Sébastien Dudek**，Penthertz 维护（[penthertz.com](https://penthertz.com)、[@PentHertz](https://x.com/PentHertz)、`security@penthertz.com` / `sebastien.dudek@penthertz.com`）。 负责任的披露流程请参阅 [`SECURITY.md`](SECURITY.md) §1。

标签：DNS 反向解析, FIDO2, LUKS, ML-KEM, Nitrokey, Rust, TPM 2.0, Windows Hello, YubiKey, 云存储安全, 加密容器, 可视化界面, 后量子密码学, 安全文件共享, 开源安全工具, 抗量子计算, 数据加密, 数据防泄露, 文件加密, 混合加密, 硬件安全密钥, 网络安全, 网络扫描, 网络流量审计, 蓝队防御, 虚拟硬盘, 逆向工程平台, 通知系统, 隐私保护, 零信任存储