XHIM 数据库加密与密钥生命周期

构建门禁

普通开发构建仍可使用系统 SQLite；正式加密制品必须显式提供经审核的 SQLCipher CMake Target，并同时开启：

-DXHIM_ENABLE_SQLCIPHER=ON
-DXHIM_REQUIRE_DATABASE_ENCRYPTION=ON
-DXHIM_SQLCIPHER_TARGET=SQLCipher::SQLCipher
-DXHIM_ENABLE_LOCAL_PREVIEW=OFF

开启加密却只链接普通 SQLite 会在 CMake 配置阶段失败。要求加密但 Product Adapter 未提供 32–64 字节数据库密钥，也会在 Client 创建阶段失败，不允许 静默降级到明文。

密钥来源

• iOS/macOS：Keychain 中保存随机数据库密钥，访问级别与产品后台/锁屏策略一致；
• Android：用 Android Keystore 不可导出 AES Key 包装随机数据库密钥，包装密文 存入应用私有目录；
• Windows：用 DPAPI/企业密钥保护随机数据库密钥，并绑定当前用户或设备范围；
• HarmonyOS：用 HUKS Key 包装随机数据库密钥，密文保存在应用沙箱。

密钥不能从用户密码直接截断、写入普通配置、备份到日志或随数据库文件保存。 备份/迁移策略必须同时覆盖受保护密钥，并明确“数据库存在但密钥丢失”属于不可 恢复事故。

打开与轮换

Store 在 sqlite3_open_v2 后把 sqlite3_key 作为首个数据库操作，然后读取 sqlite_master 验证密钥；失败统一映射为 encryption_key_rejected。 rotate_encryption_key() 仅允许可写句柄，并把 sqlite3_rekey 的成功返回 作为唯一提交点；成功后不再增加一个可能把“数据库已换 Key”误报成失败的查询 窗口。新密钥缓冲区在返回前被显式覆盖。平台安全存储只应在 rekey 成功后原子 提交新密钥；rekey 失败则保留旧密钥。

正式验收必须覆盖新库、旧明文库受控迁移、错误密钥、密钥丢失、rekey 中断、 备份恢复、离线只读和多进程争用。2026-07-25 已在 Apple toolchain 用 CommonCrypto 编译 SQLCipher 4.12.0 的 iPhone arm64 和 Simulator arm64/x86_64，并确认加密 API 进入已签名的 Preview XCFramework；二进制 Swift Package 和模拟器 App 链接运行也已通过。

这仍不等于“正式加密真机已验收”：Preview 模式故意不从 Keychain 注入数据库 Key，因此其本地数据库不作为密文证据。Production 只有在 Apple Product Adapter 返回 Keychain 随机 Key、关闭 Local Preview，并完成错误 Key、轮换、 备份恢复与真机文件抽检后才能关闭该门禁。