rootkey-crypto
RootKey(小密盾) 密码管理器的加密核心,完整开源,欢迎审查。
English: This is the complete cryptographic core of the RootKey password manager,
published for public audit. Key derivation, key hierarchy, AEAD, signing and sealed
sharing — everything that touches your secrets — is in this repo, byte-for-byte
identical to what ships in the product. The UI and commercial layers stay closed;
per Kerckhoffs's principle, none of the security depends on them being secret.
为什么开源这一层
密码管理器卖的是信任,而"请相信我加密做对了"无法口头证明。
- 加密系统的安全性只应依赖密钥,不依赖算法保密(Kerckhoffs 原则)。公开这一层不减一分安全。
- 产品里所有接触明文与密钥的代码都在这个 crate 里 —— UI 只是它的调用方。审计了它,就审计了数据安全的全部命门。
- 本仓与商业产品逐字节同源:产品主仓以此为真源构建,发版时同步快照到这里(版本号一致)。
密钥层次
Master Password(用户记忆,UI 强制 ≥ 12 位 + zxcvbn ≥ 3)
│ Argon2id(salt 32B, m=128 MiB, t=3, p=4)
▼
MUK (Master Unlock Key)
│ AES-256-GCM-SIV
▼
KEK (Key Encryption Key) ← 账户模型下由 ARK(账户根密钥)包裹
│ AES-256-GCM-SIV
▼
VMK (Vault Master Key)
│ AES-256-GCM-SIV
▼
IKEK (Item KEK)
│ AES-256-GCM-SIV(per item)
▼
ItemKey (per item)
│ XChaCha20-Poly1305
▼
Item Plaintext
主密码永不落盘、永不上传;所有中间密钥在内存中以 Zeroizing 持有,离开作用域即擦除。
算法与参数
| 用途 | 选型 | 参数 |
|---|
| 口令派生 | Argon2id | m=128 MiB(OWASP 2024 最低档 19 MiB 的 6.7 倍),t=3,p=4,salt 32B |
| 密钥包裹 | AES-256-GCM-SIV(RFC 8452) | 随机 96-bit nonce,AAD 绑定层级与格式版本;nonce-misuse-resistant,适合长命包裹密钥 |
| 条目加密 | XChaCha20-Poly1305 | 随机 192-bit nonce |
| 文件签名 | Ed25519 | vault manifest 防篡改/回滚 |
| 共享密封 | libsodium crypto_box_seal(经 dryoc 1.0,纯 Rust) | X25519 + XSalsa20-Poly1305 匿名密封盒;不自实现,直接用审计过的 libsodium 构造(含低阶点公钥拒绝) |
| 口令预处理 | NFKD 归一化 | 跨平台输入一致性 |
完整规约见 docs/SECURITY_MODEL.md(红线、AAD 模板、错误处理、回归保护)。
为什么没有 1Password 那样的 Secret Key
1Password 的 Secret Key 是第二因子:密文托管在服务商那里,万一服务端数据库泄露,
攻击者拿到密文也因为缺 Secret Key 而无法离线爆破。它解决的是**「密文在别人手里」**的问题。
RootKey 不托管密文 —— 数据只在你的设备和你自己指定的同步位置。所以我们做了另一个取舍(ADR-001):
单因子主密码 + 高成本 KDF(Argon2id m=128 MiB / t=3 / p=4)+ 主密码门槛(≥ 12 位且 zxcvbn ≥ 3)。
代价要说清楚:如果你把同步位置(WebDAV / 网盘)里的密文和一个弱主密码同时交了出去,
理论上可被离线爆破。Secret Key 挡的就是这一步;我们靠 KDF 成本和密码强度门槛挡。
两者不是等价的 —— 前者是数学上的不可分辨,后者是把成本抬到不划算。我们认为对
「密文不离开自己掌控」的模型,这个取舍成立;如果将来加入第二因子,会作为可选项,不替换主密码。
不读代码也能验证
docs/crypto-vectors.md 提供了固定输入的测试向量 ——
用任何语言的标准 Argon2id / XChaCha20-Poly1305 实现都能独立复算,验证我们的
派生流程没有私货。这些向量同时被本仓测试(tests/)锁定,CI 里任何偏离都会红。
cargo test # 168 个测试,含 KAT 向量与跨语言契约
验证「与产品逐字节同源」
产品每次发版都会公布该版本 crypto_core/src 的源码树哈希(下载页与发布说明里),
本仓对应版本打同名 tag。你可以自己算一遍对比:
git checkout v0.4.0
find src -type f ! -name '.*' | LC_ALL=C sort | xargs shasum -a 256 | shasum -a 256
(! -name '.*' 排除 .DS_Store 之类点文件 —— 它们不是源码,却会让两台机器算出不同的值。)
目前验证的是源码同源。二进制级的可复现构建(从本仓编出与发行版逐字节相同的产物)
还在路线图上 —— Flutter + Rust FFI 的全链路确定性构建尚未完成,我们不假装已经做到。
为什么多个版本的 tag 指向同一份代码
因为那几版之间 crypto_core 一个字节都没改。
产品(App)的版本号和加密核心的改动节奏是脱钩的 —— 一次发版可能只动 UI、同步、
商店文案或别的 crate,完全不碰加密层。这种时候本仓仍然打上对应产品版本的 tag,
让你能用产品版本号直接 checkout,但它的 src/ 和上一个 tag 是同一份。
按 src/ 源码树哈希实算,至今只有五组:
| 产品版本区间 | src/ 树哈希 | 那一组里改了什么 |
|---|
v0.4.0 – v0.4.1 | 560cf8a94a610d11… | 格式硬化四件套、AEAD 与 dalek 升级 |
v0.6.0 – v0.17.0 | ffa1d8f419ca2cbd… | IKEK 旋转、格式版本区间检查、v2 库兼容 fixture |
v0.18.0 – v0.23.1 | 4f20b3d025acc6fc… | 锁定期间的写入暂存:密封盒支持任意字节载荷,收件密钥对由账户根密钥派生 |
v1.0.0 – v1.0.1 | 462c6db3cb49d263… | 远程确认中继认证密钥由账户根密钥派生;改主密码时可更换整条密钥链(rekey_account) |
v1.1.0 | 7ebf0bc1c42f7fda… | 远程放行:账户根密钥交接(export_ark_for_handoff / unlock_account_with_ark),供同账户电脑为 AI 开限时会话 |
(注意 v0.4.0 与 v0.4.1、v0.6.0 与 v0.6.2 之间各有一次提交,改的是
README 与 Cargo.lock,没有触及 src/ —— 所以树哈希不变。)
怎么自己核对:任取两个 tag 比较,同组的应当完全相同、跨组的应当不同 ——
for t in v0.4.1 v0.6.0 v0.17.0 v0.23.1 v1.0.1 v1.1.0; do
git checkout -q "$t"
printf '%-10s ' "$t"
find src -type f ! -name '.*' | LC_ALL=C sort | xargs shasum -a 256 | shasum -a 256
done
预期:v0.4.1 一个值,v0.6.0 与 v0.17.0 另一个值且彼此相同,v0.23.1、v1.0.1、v1.1.0 各是另外三个值。
⚠️ 跑之前先确保工作区干净(git status),否则 git checkout 会被未提交的改动挡下,
你会在同一个工作树状态下算出一串假的"相同哈希"。
文档
发现安全问题?
请不要提公开 issue,发邮件到 [email protected](标题注明 SECURITY)。
确认的问题会在修复发布后公开致谢。详见 SECURITY.md。
许可
MIT OR Apache-2.0,任选其一。
