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

3. Tiga 三模式

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

命名约定如下：

• Power Type

  • 对应最高防护模式

• Multi Type

  • 对应平衡默认模式

• Sky Type

  • 对应更快更轻便模式

3.1 Power Type

目标：

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

典型影响：

• 最高 Argon2id 成本
• 更短的秘密驻留时间
• 更少的明文缓存
• 导出、复制等行为的警告更严格
• 附件处理默认更保守

3.2 Multi Type

目标：

• 作为推荐默认值，在安全与可用性之间平衡

典型影响：

• 强度较高的 Argon2id 参数
• 允许适度缓存
• 在低风险场景启用一定便利性能力

3.3 Sky Type

目标：

• 在较低风险环境中追求更快、更方便的日常使用

典型影响：

• 较低但仍然合格的 KDF 下限
• 更宽松的缓存策略
• 更快的解锁与日常操作

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 最好支持以下组合：

• 主密码
• 密钥文件
• 安全密钥或硬件保护密钥材料
• 平台支持下的生物识别封装

10.1 PIN 解锁

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

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

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

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

10.2 密码解锁

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

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

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

推荐要求：

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

10.3 安全密钥解锁

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

安全密钥可以用于：

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

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

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

10.4 最低解锁能力要求

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

• PIN
• 密码
• 安全密钥

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

11. 最低参数哲学

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

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

12. 审计与日志规则

日志绝不能包含：

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

13. 恢复与轮换

MDBX 最好支持：

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

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

14. 拒收规则

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

• 没有认证加密
• 附件完整性规则未定义
• 切换到更弱模式时没有显式用户确认
• 默认长期存储明文秘密却没有充分理由
• 把生物识别当作唯一真实秘密