MDBX 安全规范

版本：MDBX-1-DRAFT

本文定义 Tiga 模型、必须采用的密码学能力、密钥层级、内存处理规则。

1. 安全目标

MDBX 必须防护以下风险：

• 文件离线失窃
• 不可信云存储
• 加密记录被篡改
• 正常工作流中明文长期驻留
• 默认 KDF 参数过弱

MDBX 不能完全隐藏文件大小、访问时间、同步活动这类元数据。

2. 必需算法

推荐基线：

• 密码 KDF：Argon2id
• 认证加密：XChaCha20-Poly1305 或 AES-256-GCM
• 密钥派生：HKDF-SHA-256
• 哈希：SHA-256
• 文件名或标识符 MAC：HMAC-SHA-256

推荐默认组合：

• Argon2id + HKDF-SHA-256 + XChaCha20-Poly1305

当前 committed AEAD envelope：

• 新写入的密文值必须使用 MDBXAE1\0 || commitment || nonce || ciphertext
• commitment 是基于 envelope 上下文、associated data、nonce 和加密载荷计算的 HMAC-SHA-256 commitment
• 解密器必须继续接受 committed envelope 出现前写入的 legacy nonce || ciphertext
• 加密器不得再写入新的 legacy envelope

随机 key 或 nonce 生成失败时，操作必须失败。实现不得退回到全零 key、确定性 nonce 或任何占位秘密。

3. Tiga 三模式

MDBX 必须暴露三档用户可选安全模式。

存储值与 API 名称如下：

• power

  • 对应最高防护模式

• multi

  • 对应平衡默认模式

• sky

  • 对应灵活便携但仍然安全的模式

兼容性显示名可以使用 Power Type、Multi Type、Sky Type，但存储和 API 值最好使用 power、multi、sky。

3.1 Power

目标：

• 尽可能增强离线暴力破解阻力与本地泄露防护

典型影响：

• 最高 Argon2id 成本
• 更短的秘密驻留时间
• 更少的明文缓存
• 导出、复制等行为的警告更严格
• 附件处理默认更保守
• 为完整满足 Power 策略，最好配置密码 + 安全密钥组合解锁
• 独立密码或 PIN 解锁不应满足完整 Power 策略，除非用户明确接受这是降级

3.2 Multi

目标：

• 作为推荐默认值，在安全与可用性之间平衡
• 适合网盘同步，同时保留清晰恢复路径

典型影响：

• 强度较高的 Argon2id 参数
• 允许适度缓存
• 在低风险场景启用一定便利性能力
• 应建议用户添加安全密钥
• 除非用户明确另选更严格策略，否则必须保留强密码等便携恢复路径

3.3 Sky

目标：

• 灵活、便携、恢复优先，适合网盘同步和多设备日常使用
• Sky 不是不安全模式

典型影响：

• 较低但仍然合格的 KDF 下限
• 更宽松的缓存策略
• 更快的解锁与日常操作
• 可以提供密码、PIN 包装、平台凭据包装或安全密钥解锁
• 所有解锁路径仍必须使用 MDBX 的 KDF、AEAD、keyring 和日志规则

4. Tiga 模式作用范围

Tiga 模式必须支持：

• 全局默认模式
• 可选的 project 级覆盖
• 可选的 entry 级覆盖，用于特别敏感的秘密

更窄范围的覆盖必须优先于更宽范围的覆盖。

5. 必需用户警告

当用户切换到更弱模式时，UI 必须：

• 清楚说明新风险画像
• 要求显式确认
• 明确展示哪些保护会变弱

6. 密钥层级

合规实现最好使用分层密钥结构：

• 用户输入的秘密因子
• 主解锁密钥
• vault 密钥
• 用途子密钥
• 记录或对象密钥

推荐链路：

• 由 Argon2id 导出解锁密钥
• 由 HKDF 派生 vault key
• 再为元数据、记录、附件、历史分别派生子密钥

7. 记录认证

MDBX 必须认证以下内容：

• 会影响解密的 vault 头部元数据
• project 记录
• entry 记录
• attachment 元数据
• attachment 内容或 chunk 内容
• 历史记录
• snapshot 记录

密文被移动到错误上下文后必须认证失败。

8. 附件安全规则

附件属于一等敏感数据。

因此 MDBX 必须：

• 认证附件元数据
• 认证附件内容
• 保证附件重命名只改元数据，不影响无关内容
• 在重建附件时先验证内容 hash

如果支持外部引用附件，那么外部内容也必须和数据库元数据建立完整性绑定。

9. 内存安全规则

实现最好做到：

• 尽量缩短明文在内存中的停留时间
• 在可行时擦除敏感 buffer
• 不记录秘密日志
• 尽量避免 crash dump 中残留原始秘密
• 对大附件采用流式处理，避免整份明文长期驻留内存

10. 解锁因子

MDBX 应明确区分“用户可见的解锁方式”和“底层实际参与加密的密钥模型”。

用户看到的解锁方式可以是：

• PIN
• 密码
• 安全密钥
• 平台支持下的生物识别封装

其中，底层真正保护 vault 的秘密材料仍应由主解锁密钥、vault 密钥及其派生链负责。

MDBX 最好支持以下组合：

• 主密码
• 密钥文件
• 安全密钥或硬件保护密钥材料
• 平台支持下的生物识别封装
• 密码 + 安全密钥组合解锁，表示为 password_security_key

10.1 PIN 解锁

PIN 可以作为用户可见的快速解锁方式。

但 PIN 不应直接等同于真正的 vault 主秘密。 更合适的做法是：

• PIN 用于解锁本地受保护的包装密钥
• 包装密钥再去解锁真正的 vault 密钥材料

这样可以避免把短 PIN 直接暴露为唯一安全边界。

10.2 密码解锁

密码 是 MDBX 必须重点支持的核心解锁方式。

密码输入必须支持 Unicode。 这意味着：

• 必须支持中文密码
• 不得假设密码只包含 ASCII
• 规范与实现都应明确字符编码与规范化策略

推荐要求：

• 密码在进入 KDF 前使用稳定的 Unicode 字符串处理流程
• 实现必须避免因为平台差异导致同一中文密码在不同设备上无法解锁

10.3 安全密钥解锁

安全密钥 应作为受支持的解锁方式之一。

安全密钥可以用于：

• 提供硬件保护的解锁因子
• 包装或释放本地保存的密钥材料
• 与密码或 PIN 组合形成更强的解锁方案

安全密钥不应被描述成“必须联网才能工作的云端依赖”。 MDBX 仍然必须保持本地优先。

支持硬件密钥本身并不会让网盘存储变得不安全或不可用。是否便携取决于 vault 配置了哪些解锁方式：

• password 和设计正确的便携恢复方式可以在新设备上打开网盘同步过来的 vault。
• 仅配置 security_key 的 vault 需要同一把硬件密钥或等价平台凭据。
• password_security_key 能增强离线爆破阻力，但会有意降低独立便携性。

客户端在禁用所有便携解锁路径前，必须向用户说明这些恢复后果。

生物识别最好只是包裹更强的底层秘密，而不是取代真正的 vault 加密模型。

10.4 最低解锁能力要求

一个面向最终用户的 MDBX 实现最好至少支持以下三种解锁方式中的两种，完整实现应支持全部三种：

• PIN
• 密码
• 安全密钥
• password_security_key

如果实现声明支持 密码，则其密码输入必须支持中文。

11. 最低参数哲学

MDBX 必须定义最低安全底线。 即使是 sky，也必须仍然是有意义的安全配置，而不是玩具参数。

具体参数表最好单独发布并带版本号。

12. 审计与日志规则

日志绝不能包含：

• 明文密码
• TOTP seed
• Passkey 私钥材料
• 解密后的附件名，除非用户显式导出诊断信息

13. 恢复与轮换

MDBX 最好支持：

• 密钥轮换
• 备份校验
• snapshot 校验
• 附件完整性扫描

轮换过程中必须保持旧记录可读，直到迁移完成。

14. 拒收规则

以下安全设计不符合规范：

• 没有认证加密
• 附件完整性规则未定义
• 新写入密文不使用 committed AEAD envelope
• 没有关键安全迁移说明却故意移除读取 legacy 有效密文或旧 vault 的能力
• RNG 失败后退回到全零 key、确定性 nonce 或占位秘密
• 切换到更弱模式时没有显式用户确认
• 默认长期存储明文秘密却没有充分理由
• 把生物识别当作唯一真实秘密