VMax / 设计档案

外观

ADR-007 备份格式与恢复 ​

状态 ​

提案，待总控决策。.vmaxbak 扩展名是说明书建议，不代表容器编码、KDF 或兼容策略已经冻结。

背景 ​

首版需要让用户导出加密备份，并在新设备恢复身份、联系人验证状态、会话恢复材料和设置。消息历史由用户单独选择，默认不包含。备份是可离线猜测的长期密文，也是会把设备内秘密带出 Keychain 的高风险边界。

已验证的仓库事实 ​

截至 2026-09-23，当前仓库没有备份 schema、测试向量、KDF 实现或恢复代码；本文只定义格式与恢复不变量、候选方案和验证方法。

说明书 MUST ​

  • 备份密码不得上传、同步或进入日志、崩溃报告、分析和诊断导出。
  • 导出到 Files/iCloud Drive 的始终是加密包；检查包内容不得出现私钥、昵称或消息明文。
  • 备份完整性验证通过后才可开始恢复。
  • 恢复后提示旧设备风险；MVP 不自动吊销无法访问的旧设备。
  • 消息历史默认不包含，只有用户明确选择才加入。
  • 本地格式化不删除 App 外部备份，产品必须明确说明该边界。
  • 密码协议、序列化和存储格式必须有版本策略，不得静默降级或复用不兼容状态。

建议决策 ​

采用“最小明文前导 + 单个认证加密主体”的版本化容器：前导只包含识别和解密所必需的魔数、容器版本、KDF 标识/参数、随机盐、AEAD 标识、nonce 与密文长度；其余清单、Profile 元数据、私钥、联系人、验证状态、会话材料、设置和可选消息全部位于认证加密主体内。

建议扩展名为 .vmaxbak。建议使用内存困难 KDF（优先验证 Argon2id）从独立备份密码派生 KEK，再解封随机生成的备份内容密钥；具体 KDF、参数、AEAD 和规范化编码均待总控、许可评审和独立审计，不在本文冻结。

格式选项 ​

选项 A 单文件二进制版本化容器 ​

  • 优点：原子导出；明文元数据容易最小化；长度、版本和认证边界明确。
  • 缺点：需要自行定义容器 framing、流式处理和规范化测试向量。
  • 推荐：首版优先验证。

选项 B ZIP 类容器，条目分别加密 ​

  • 优点：流式与大附件组织直观。
  • 缺点：文件名、条目数、大小和目录结构易泄露；路径穿越、重复条目、压缩炸弹和部分认证增加攻击面。
  • 建议：仅在大规模消息/附件备份确有需求且完成解析器加固后考虑。

选项 C 依赖系统文件加密而不做应用层加密 ​

  • 不采用。Files/iCloud Drive 和跨设备复制不保证维持 VMax 所需的密码与完整性边界。

候选容器结构 ​

text
CleartextHeader {
  magic
  container_version
  kdf_id
  kdf_parameters
  salt
  aead_id
  nonce
  ciphertext_length
}

Ciphertext = AEAD_Encrypt(
  key = random_backup_content_key,
  plaintext = CanonicalPayload,
  aad = canonical(CleartextHeader)
)

实际还需定义内容密钥如何由备份密码派生材料封装、长度上限、分块规则和认证标签位置。若采用分块 AEAD，每块必须绑定备份 ID、版本、序号、总块数和前导摘要，防止重排、截断和跨备份拼接。

CanonicalPayload 建议包含：

  • payload schema 版本、创建时间的粗粒度值、源 App 版本；
  • 一个或多个 Profile 的不透明备份 ID 与实例信任材料；
  • 身份与设备私钥、联系人身份公钥、验证等级和密钥变化历史；
  • 恢复会话所必需的协议不透明状态；
  • 用户设置的允许列表；
  • 可选消息历史及其明确选择标志；
  • 完整性与迁移所需的记录计数和 schema 版本。

不包含：APNs token、Push 路由、设备绑定 Secure Enclave 私钥、Keychain access-control 对象、短期网络 token、Outbox 中结果未知的提交任务、诊断日志、缓存和可重新获取的数据。

服务端虽然确定提供 S3 兼容对象存储，但其默认职责是保存经批准的密文对象，不构成用户备份服务。首版 .vmaxbak 由用户显式导出到系统文档位置；除非未来另行完成产品、隐私、协议与恢复设计，客户端不得把备份自动上传到服务端 S3。产品没有 Web 管理后台，恢复流程也不得依赖管理员后台解密、改库或人工修复。

密码与密钥边界 ​

  • 备份密码与主/假密码是独立凭据；不得默认复用，也不得由其中一个派生另一个。
  • 备份 KDF 使用每个备份独立随机盐和版本化参数。参数需在最低支持设备上校准，并设置解析上限，防止恶意包诱发内存/CPU 拒绝服务。
  • 错误密码与认证失败对用户使用同类中性错误；内部可区分阶段，但日志不记录密码、派生值或敏感路径。
  • 明文密码、KEK、内容密钥和解密缓冲使用最短生命周期；Swift/平台能否可靠清零需验证，不作绝对保证。
  • 设备绑定包装密钥不进入备份。恢复时在目标设备重新生成本地数据库密钥和封装材料。

导出流程 ​

  1. 在已解锁的真实 Profile 内要求显式用户操作；敏感设置可再次要求主密码或设备认证，但不把主密码作为备份密码。
  2. 展示备份包含项，消息历史默认关闭；明确外部备份不会被本地格式化删除。
  3. 获取并确认备份密码，在受控内存中派生备份 KEK。
  4. 从数据库一致性快照生成规范化 payload，不直接复制活动 SQLCipher 文件、WAL/SHM 或 Keychain 数据库。
  5. 加密到 App 私有临时文件，完成认证自检后再通过系统文档导出。
  6. 导出成功、取消或失败后清理 App 私有临时文件；系统分享目标的副本由用户和目标系统控制。

不得先生成明文归档再加密。进度、文件名和错误信息不得包含 Profile 地址、联系人或消息摘要。

恢复流程 ​

text
选择文件
 -> 仅解析有界明文前导
 -> 校验版本、算法允许列表、长度与资源上限
 -> 输入备份密码并完成整体/分块认证
 -> 解密到受保护暂存区
 -> 校验 payload schema、记录关系、协议版本与实例信任材料
 -> 展示去敏恢复计划和旧设备风险
 -> 创建新的目标 Profile 容器
 -> 事务导入并生成目标设备本地封装材料
 -> 完整性检查
 -> 原子注册新 Profile
 -> 清理暂存区

在完整认证与结构校验前，不修改现有 Profile、Keychain 或通知路由。恢复失败删除暂存材料并保持原状态。不得把不兼容协议状态降级导入；可恢复的子集和丢弃项必须在用户提交前说明。

冲突策略选项 ​

选项 A 总是恢复为新 Profile ​

  • 优点：不覆盖活动数据，回滚和审计简单，最符合隔离原则。
  • 缺点：可能出现同一身份的多个本地副本，需要明确旧设备/重复身份风险。
  • 推荐：MVP 采用。

选项 B 合并到现有 Profile ​

  • 优点：用户体验连续。
  • 缺点：联系人验证等级、会话 ratchet、消息 ID、删除状态和设置冲突复杂，错误可能导致消息丢失或密钥状态回退。
  • 建议：首版不做，除非协议与数据模型提供可证明的合并规则。

选项 C 覆盖现有 Profile ​

  • 优点：概念直观。
  • 缺点：失败半径最大；容易破坏当前会话与 Outbox。
  • 建议：不直接提供。若未来需要，先导入新容器并验证，再以显式切换替代原地覆盖。

版本与迁移 ​

  • 容器版本、payload schema、协议状态版本和应用数据库 schema 分开编号。
  • 解析器先验证固定前导与长度，再分派明确版本；未知版本拒绝，不“尽力读取”。
  • 迁移采用纯输入到新输出，不原地修改用户备份文件。
  • 保留固定测试向量：正确密码、错误密码、篡改、截断、超长参数、未知版本、重复字段、乱序分块和跨版本迁移。
  • 旧格式支持窗口与删除计划需要产品决策；不得为了兼容而启用弱 KDF 或未批准算法。

与 Profile 隔离和格式化的关系 ​

  • 每个恢复出的 Profile 获得新的本地随机内部 ID、数据库密钥、Keychain 命名空间和通知路由。
  • 恢复不自动复制 APNs token，也不自动复用原设备的 Push route。
  • Decoy 不展示、枚举或恢复真实备份；备份入口只在真实空间出现。
  • 本地格式化只清理 App 可控的本机真实空间，不能承诺删除 Files、iCloud Drive、AirDrop 或其他设备中的备份。
  • 若格式化后再导入旧备份，用户应看到旧状态与旧设备风险提示；是否允许恢复已撤销身份属于协议/产品待决事项。

验证计划 ​

  • 机密性：十六进制、字符串和文件元数据扫描无私钥、昵称、地址、消息明文或敏感路径。
  • 完整性：单字节篡改、截断、追加、分块重排、跨包拼接全部在写入前失败。
  • 密码：错误密码、边界长度、Unicode 规范化、取消、后台、强杀和重复尝试；规范化策略必须固定并有向量。
  • 资源：恶意 KDF 参数、超大长度、压缩炸弹候选、磁盘满和内存压力不破坏现有数据。
  • 恢复：新设备、相同实例、实例指纹变化、未知协议、旧 schema、重复身份、消息历史开/关。
  • 中断：导出和恢复每一步强杀，确认无可用明文临时文件，且现有 Profile 不变。
  • 真机：最低支持设备上的 KDF 时间/内存、后台行为、文件保护和系统文档导出。
  • 互操作：固定容器向量由至少两个独立实现解析；独立安全评审与模糊测试通过。

待总控决策 ​

  • 是否选择单文件二进制容器；推荐选项 A。
  • 规范化 payload 使用 CBOR、Protobuf 或其他格式；由 ADR-004 决定。
  • KDF、参数校准、AEAD、分块与密钥封装；需与密码任务、许可评审和独立审计共同决定。
  • MVP 是否允许多 Profile 备份；推荐首版一次只导出一个 Profile，降低误选和恢复冲突。
  • 旧备份支持窗口、身份已撤销时的恢复政策和旧设备吊销流程。
  • 消息历史的容量上限、附件是否进入备份，以及流式格式何时进入范围。

系统初步设计 · 待决事项不代表批准 · 安全方案尚未完成独立审计

VMax 文档站仅发布 docs/ 范围内的评审材料