VMax / 设计档案

外观

ADR-002 iOS 最低版本与后量子能力 ​

状态 ​

部分已决、部分待决。Swift + SwiftUI 已确定；iOS 最低版本、Swift 语言模式的最终工具链基线和后量子能力仍待总控决策与实测。本文不冻结密码套件，也不证明任何平台 API 或协议实现达到生产安全。

背景 ​

v1.1 说明书把 iOS 26.0、Swift 6、SwiftUI 和严格并发作为客户端参考路线，并要求未来若支持更低系统，不得静默降低密码套件。说明书同时提出 CryptoKit 量子安全 API 与混合后量子协议方向，但明确要求协议组合、实现、许可和审计另行确认。

已验证的仓库事实 ​

截至 2026-09-23，当前仓库没有 Xcode 工程或 Swift 实现。因此下述平台能力、API 签名、部署目标行为、设备性能和可用性标注均未在本 worktree 验证。

已确认的技术决策 ​

  • iOS 客户端使用 Swift 实现。
  • UI 使用 SwiftUI；不再评估 UIKit 主架构、跨平台 UI 或其他客户端语言作为首版替代方案。
  • UIKit、Security、UserNotifications 等系统框架可作为 SwiftUI 客户端的底层适配器，但不得反向承担业务状态所有权。

说明书 MUST ​

  • 首版最低系统按 iOS 26.0 规划。
  • 未知协议版本和不安全降级必须拒绝。
  • 若未来支持更低系统，必须提供显式能力策略，不得静默换用较弱密码套件。
  • 生产密码协议不得由普通业务代码从零设计；必须基于公开规范、测试向量并通过独立密码学审计。
  • Swift 6 严格并发下，密码会话状态由独立 actor 串行管理。

建议决策 ​

建议首版采用 iOS 26.0 deployment target 与 Swift 6 language mode；Swift + SwiftUI 本身已经确定，不属于本 ADR 的待选项。所有平台密码能力通过 PlatformCryptoCapabilities 和 ProtocolEngine adapter 隔离。业务层只请求协议能力标识，不直接调用具体后量子 API，也不依据设备型号自行拼装套件。

能力协商的结果必须是以下之一：

  1. 双方支持经批准且版本匹配的协议，创建新会话；
  2. 能力不足或版本未知，明确阻断；
  3. 迁移到经单独批准的新协议版本。

不存在“先尝试后量子，失败后自动退回经典算法”的路径。

选项比较 ​

选项 A 首版仅支持 iOS 26+ ​

  • 优点：与说明书一致；平台与 UI 能力面更单一；减少并发、存储和密码能力兼容分支。
  • 缺点：设备覆盖较小；对尚未真机验证的平台 API 依赖更集中。
  • 风险：把 API 存在误当成协议安全；系统实现仍需测试向量与独立审计。

选项 B 支持更低 iOS 并引入兼容实现 ​

  • 优点：覆盖更多设备。
  • 缺点：需要额外密码实现、分发包体、许可和侧信道评估；迁移与互操作矩阵显著扩大。
  • 风险：能力探测错误、静默降级、不同实现产生不一致状态。

推荐 ​

推荐选项 A，但仍标记为待总控决策。推荐理由是首版范围有限，优先减少安全关键分支。该推荐不等于认可说明书中列举的具体后量子算法组合。

架构约束 ​

  • PlatformCryptoCapabilities 只报告经过实测且允许使用的能力，不报告营销名称。
  • ProtocolEngine 根据已冻结的协议版本整体选择实现，禁止业务层逐个选择 KEM、签名、AEAD 或 KDF。
  • 协议会话与密钥操作处于 Profile 作用域 actor 内；切换 Profile 时销毁对应 actor。
  • API availability、模拟器能力和真机能力分别记录；模拟器成功不能替代 Secure Enclave 或性能真机证据。
  • Fake engine 只用于 UI/流程测试，必须从发布构建中排除，并在运行时可识别。
  • 平台错误映射为稳定类别：能力缺失、用户取消、设备锁定、密钥失效、协议拒绝；不得把底层密钥标识写入日志。

需要验证的平台事项 ​

  1. 目标 Xcode 与 iOS 26 SDK 中相关 CryptoKit/Security API 的正式名称、availability、输入输出限制和错误语义。
  2. 后量子操作是否在目标设备硬件或系统实现中可用，以及最低设备、性能、内存、后台时间和能耗。
  3. Secure Enclave 能保护哪些密钥类型；对称数据库密钥采用何种封装路径；设备锁定、重启、口令变更和生物识别集合变化后的行为。
  4. Swift 6 严格并发下第三方密码/数据库依赖是否满足 Sendable 与 actor 隔离，而非用不安全标注绕过。
  5. App Store 构建、出口合规、隐私清单、依赖许可与 SBOM 要求。
  6. 跨语言固定测试向量、未知版本、降级攻击、乱序、重放与状态迁移测试。

验证门槛 ​

  • 使用最低支持版本的至少两类真机完成能力探测与性能基准；模拟器仅作补充。
  • 所有协议向量在 Swift 与服务端/参考实现间逐字节一致。
  • 不支持或异常设备明确阻断，不创建降级会话。
  • 生产构建静态检查确认不包含 Fake engine、测试密钥或开发协议开关。
  • 第三方许可评估与独立密码学审计完成前，不得发布“后量子安全”结论。

待总控决策 ​

  • 是否确认选项 A 为首版最低版本策略。
  • 是否将 Swift 6 language mode 与严格并发检查作为首版强制工具链基线；语言与 UI 框架本身已确定为 Swift + SwiftUI。
  • 哪个公开协议规范、版本、密码套件与实现进入独立审计；本 ADR 不作决定。
  • 是否引入第三方兼容实现及其开源/商业许可；本 ADR 不作决定。
  • 哪些设备构成发布真机矩阵，以及能力不足设备的产品提示。

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

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