Master Key 与 Key Slot 生命周期

所有 Master Key、Key Slot 与 Recovery 操作都是离线控制面操作。先停止 Halro、取得数据目录独占锁并创建已校验备份。不得把明文 Key、密文、身份 Token 或原生错误正文放进命令参数、日志、工单或审计附件。KMS ARN 是当前 key rewrap --key-reference 的必需参数；只在受控终端使用，不把完整 ARN 复制进普通日志、工单或公开附件。

File 模式轮换

适用于：

storage:
  master_key:
    mode: file

轮换前确认 Master Key 位于 storage.data_dir 外，保存旧 Key，并创建新的 32 字节 0600 文件：

umask 077
openssl rand 32 > /secure-secrets/halro-master-next.key
test "$(wc -c < /secure-secrets/halro-master-next.key | tr -d ' ')" -eq 32

halro key rotate \
  --config /etc/halro/config.yaml \
  --new-key-file /secure-secrets/halro-master-next.key

成功输出只应包含可归档的指纹摘要、记录数和版本信息。不要提前修改 storage.master_key.file；命令成功后再按输出和配置核对当前 Key。

若主机或命令中断，保持 Halro 停止，保留旧 Key、新 Key、数据目录和日志，使用同一个 --new-key-file 重试。不要更换新 Key、手工组合数据库与 Key，也不要启动第二次轮换。

轮换完成后：

运行 halro doctor --config /etc/halro/config.yaml；
启动 Halro，使用新会话完成 Admin + MFA 登录和一条受控 Gateway 请求；
在 Usage 中确认对应结算记录；
创建并校验一份轮换后备份；
为所有轮换前备份保留其对应旧 Master Key，直到备份到期并完成处置。

Key Slot 的权限边界

当前 key_slots 实现使用 AWS KMS。Primary 与 Recovery 应使用独立的 customer-managed symmetric KMS Key，并至少在 Key、权限/身份、账号、区域或管理边界之一形成独立故障域。

Runtime 身份只持有日常 Primary 解密权限；
Recovery 身份不挂载到日常工作负载；
Lifecycle 身份只在审批后的离线变更期间使用；
不使用通配资源权限，也不把静态云 Access Key 放进环境变量；
Primary 失败时不会自动切到 Recovery，这是故障显性化与失败关闭边界。

变更前先做静态检查，再在目标 Runtime 身份下做完整检查：

halro config check --config /etc/halro/config.yaml
halro doctor --config /etc/halro/config.yaml --no-kms
halro doctor --config /etc/halro/config.yaml
halro key slot status --config /etc/halro/config.yaml

--no-kms 不能证明 Vault 可恢复；完整 doctor 会使用 Primary 做只读解锁并在云审计中留下调用证据。两者用途不同，不能用静态检查替代真实恢复身份验证。

正常 KEK rewrap

rewrap 只替换某个 Slot 的 KMS 包装，不是疑似泄露后的补救措施。先在配置 storage.master_key.allowed_kms_keys 中加入新 Key ARN，并把对应的 storage.master_key.primary_slot 或 storage.master_key.recovery_slot 改成命令将使用的新 Slot ID。另一条独立解锁路径必须保持不变且已经验证；随后先执行 config check，再运行 rewrap：

halro key rewrap \
  --config /etc/halro/config.yaml \
  --purpose primary \
  --slot-id slot_aws_primary_2026q4 \
  --key-reference arn:aws:kms:REGION:ACCOUNT:key/KEY_ID

halro key slot status --config /etc/halro/config.yaml

命令中的 --slot-id 必须与配置中同用途的目标 Slot 完全一致，否则 Halro 会失败关闭。Recovery 验证后需要 rewrap 新 Primary 时，也先按这一步更新 Primary 目标 Slot，不要直接套用旧配置。

只有新 Slot 已独立验证、恢复窗口和历史备份清单完成审批后，才退役旧 Slot。先从 slot status 取得当前 revisions，再精确确认：

halro key slot revoke \
  --config /etc/halro/config.yaml \
  --slot-id slot_aws_primary_2026q3 \
  --expected-descriptor-revision DESCRIPTOR_REVISION \
  --expected-slot-revision SLOT_REVISION \
  --confirm-slot-id slot_aws_primary_2026q3 \
  --reason retirement_window_completed

Slot revoke 成功并完成恢复证据归档后，才移除旧 allowlist 条目和撤销旧 Grant/Policy。当前实例已 rewrap 不会改变历史备份依赖的 descriptor 或 KMS Key。

Master Key/DEK rotate

KMS Key、Grant、Key Policy 或任何可执行解密的身份疑似泄露时，不能用 rewrap 作为修复；应先隔离相关身份并保全云审计，再执行 Master Key/DEK rotate。为一次操作选择稳定、非敏感的唯一 ID：

halro key rotate \
  --config /etc/halro/config.yaml \
  --operation-id incident-2026-09-05-001

命令中断后只能使用同一个 operation-id 恢复。发现另一个未完成 operation 时停止操作，不要创建第二次轮换或手工编辑数据文件。完成后重新执行 doctor、Primary/Recovery 演练、Admin/MFA 与 Gateway 验收，并创建新备份；每份历史备份仍需单独记录旧 descriptor、KMS Key 依赖与处置期限。

Recovery Slot

Primary 不可用时，先保持 Listener 停止并临时授予受审批的 Recovery 身份：

halro key recover \
  --config /etc/halro/config.yaml \
  --confirm-recovery-slot slot_aws_recovery

该命令验证 Recovery 路径，不会把它变成日常 Runtime fallback。验证后用短期 Lifecycle 身份 rewrap 出新的 Primary，撤销所有临时授权，再以日常 Runtime 身份执行完整 doctor 和冷启动。 Primary 仍不可用时必须保持失败关闭。

完成门禁

一次密钥变更只有在以下条件全部满足后才可关闭：

变更前、变更后备份均已校验，且至少一次隔离恢复演练成功；
doctor、Audit、Ledger、Usage、readiness、Admin/MFA 和受控请求通过；
临时 Recovery/Lifecycle 授权已经撤销；
历史备份逐份记录所需旧 Key/descriptor、保留截止时间与最终处置；
只归档非敏感命令结果、事件编号和云审计关联信息。