Files
ShadowsocksX-NG/docs/adr/0035-encrypt-persistent-server-library.md
T

6.6 KiB
Raw Blame History

持久服务器库整体加密与主密钥恢复边界

Status: Accepted(2026-10-18)。

持久服务器库采用 CryptoKit AES-256-GCM 整体加密。密码、完整插件参数、订阅 URL 与配置目录、订阅关联、收藏共同进入密文;服务器库专用 Keychain 项只保存随机主密钥,不再逐项保存这些凭据。监听认证、连通性检测 URL 等范围外凭据不随本决定迁移。sslocal-active.json 与派生认证文件的加密另案处理。

主密钥采用经典登录钥匙串,并以严格 ACL 限制获准应用访问。该选择优先考虑开源分发中的维护者签名变更和用户自行编译;不通过放宽到任意应用访问来换取兼容。更换签名后的前台重新授权与迁移路径仍须设计,并在真实签名构建中验证,不能承诺静默读取旧密钥。

启动和后台读取不得主动触发授权弹窗;遇到需要交互的状态时显示可重试的错误,只有用户主动解锁时请求系统授权。当前进程成功读取过密钥后继续使用内存资料。签名变更后的重新授权沿用该显式入口,实际系统授权结果以真机验证为准。

首版不提供完整服务器库的独立密码加密备份。用户接受主密钥丢失后通过重新导入或订阅恢复资料;未另存的手动资料无法保证恢复。ADR-0018 的 SIP-008 明文配置组导出保持其原有用途,不等同于完整服务器库的加密备份。

内存与加载失败

应用成功解密后,主密钥与服务器库明文在当前应用进程内保留至退出;首版不增加手动锁定功能。此后锁定钥匙串不撤销当前进程已经读取的资料,当前应用继续工作。应用重新启动后重新读取主密钥。

整体解密使服务器密码随服务器库进入内存,因此调整 ADR-0030 的按需读取边界:不再承诺只有打开编辑界面才装载密码,也不再承诺插件参数明文只在详情会话中持有。详情界面仍不显示密码,编辑草稿仍与详情展示分离。非秘密展示投影、诊断与日志不得因整体解密而包含秘密。

加载失败时保留原文件,阻止服务器库写入,并提供重试入口;已有后台代理服务继续运行。不得将解密失败、密钥不可用、格式不支持或文件损坏自动视为空库。加载失败后,只有用户明确确认放弃原配置时,才进入新建流程。

用户可以在加载失败后明确确认创建空库,并覆盖旧文件。该操作必须独立于重试,确认文案必须说明覆盖将放弃旧服务器库;取消操作不得修改旧文件。此授权是产品行为决定,不是本次设计讨论中立即删除本机数据的授权。重置时创建新主密钥,成功保存新空库后清除活动目标并撤下原服务器出口,保留代理服务开关意图,沿用现有空库收敛行为。新空库保存失败时保留旧文件与原运行状态。

加载失败状态不得作为空库传入启动时的活动目标重展开流程。当前活动目标独立持久化;以空库重展开会清除目标并部署无服务器出口的运行配置,违背失败时保留已有代理运行的决定。加载失败状态必须与真正空库明确区分。

迁移与清理

首次成功读取全部旧资料后自动迁移;任何所需旧凭据读取失败都停止迁移并保留原数据。迁移将全部资料汇总到内存,加密后提交新库,重新读取验证成功后才清理迁入的旧凭据。不新增持久明文备份,范围外凭据保持不变。

新密文使用独立文件名 catalog.enc。存在新密文时优先读取新密文,即使其读取失败也不得自动退回旧 catalog.json。迁移验证后删除旧 catalog.json。旧版程序普通库写入使用旧路径,独立路径隔开了对新密文的直接覆盖;该结论来自源码分析,尚未运行旧版兼容验证。

首版不承诺旧版程序直接打开新库,也不自动合并旧版后续新增的资料。独立库路径不隔离新旧版共享的活动目标、设置与运行契约,因此不承诺新旧版交替启动的运行兼容。

应用尚未发版,本次不为极端迁移故障增加恢复框架。保留正常自动迁移路径,以及提交失败不覆盖旧数据、密钥持久化成功后才提交密文的基本保护。新库验证成功后尝试清理旧文件与迁入凭据;清理失败时报告清理失败并继续使用新库,不撤回成功迁移,不增加持久清理队列、后台自动重试或跨次启动的清理事务日志。残留旧资料不会因报告错误而自动消失。

主密钥生命周期

首版不提供手动或定期轮换入口。正常保存沿用现有主密钥,每次加密生成新 nonce;用户明确重置服务器库时创建新主密钥。密钥创建与首份文件提交的失败保护属于实现契约,不得先删除旧密钥再尝试写入新文件。

实施与验收

实现保持单应用进程、串行保存与单份主密钥模型,不引入多进程迁移协调、自动轮换或历史密文恢复系统。固定版本化文件封装,认证文件头;服务器库保存过程只写密文临时文件,不向日志或诊断报告增加秘密。主密钥不写入普通文件、日志或诊断报告;运行契约沿用本文开头规定的范围。磁盘权限沿用目录 0700、文件 0600。

验收集中于本次实际改变的路径:

  • 文件与加密:完整资料往返不丢字段;多次保存生成不同密文;错误密钥、篡改与不支持版本返回错误;文件不含样本资料明文。
  • 迁移与失败:正常迁移整合密码、插件参数及订阅 URL;缺凭据时保留旧数据;提交失败不覆盖旧文件;成功后执行一次清理并报告失败。
  • 产品行为:加载失败不写空库、不重展开原活动目标;授权仅由用户主动触发;取消重置保留旧数据,确认且保存成功后清除目标;现有导入、编辑、订阅与激活兼容。
  • 真机:验证实际构建下的主密钥保存和读取、退出重启、钥匙串锁定与前台授权;运行进程验证与纯文件测试分别记录。没有实际执行的签名身份变更或跨机恢复测试标为未验证,不扩展为首版完整签名组合测试矩阵。

用户通过 implement 指令确认实施本设计。上述验收条件是实施检查清单;实际执行结果见对应提交与交付记录。

研究依据见 服务器配置文件整体加密方案研究。该报告是候选方案与调研记录,本 ADR 仅采纳上述明确列出的决定。