70 lines
4.8 KiB
Markdown
70 lines
4.8 KiB
Markdown
# 云KMS/HSM密钥轮换一致性证据
|
||
|
||
## 1. 目标与验收边界
|
||
|
||
`cmd/kms-rotation-conformance`用于把同一候选构建下的云密钥提供器、工作负载身份、版本切换、新旧凭据认证结果、业务连续性探针和提供器访问审计形成`kms-rotation-conformance-report-v1`。本地环境变量、Docker Secret或普通文件演练只能输出`LOCAL_SECRET/external_validation_required=true`；只有目标预生产或生产环境的云KMS、HSM、Secret Manager或等价受控提供器证据完整时，报告才为`REAL_KMS_HSM`。
|
||
|
||
报告不包含密钥值、令牌、数据库连接串或可还原的密钥摘要。它使用提供器版本引用、脱敏探针引用和审计引用证明“轮换的是哪一个受控版本、谁读取了它、业务如何验证、旧版本如何失效”。报告通过不等于业务发布批准，也不替代厂商侧权限审计和安全负责人签署。
|
||
|
||
## 2. 证据格式
|
||
|
||
输入文件使用`kms-rotation-capture-v1`并严格拒绝未知字段。顶层字段包括：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `evidence_source` | 本地演练填`LOCAL`，真实云KMS/HSM填`KMS_HSM` |
|
||
| `candidate_version/build_digest` | 必须与候选证据包一致 |
|
||
| `environment` | 本地为`LOCAL`；真实证据只能是`STAGING`或`PRODUCTION` |
|
||
| `provider_ref` | 不含租户凭据的云提供器或HSM稳定引用 |
|
||
| `workload_identity_ref` | API、Callbacks、Worker等实际工作负载身份引用 |
|
||
| `provider_audit_ref` | 提供器访问审计、版本变更审计或受控工单引用 |
|
||
| `attested_by_ref/attested_at` | 安全或平台复核人脱敏引用与复核时间 |
|
||
| `rotations` | 一次或多次密钥轮换观测 |
|
||
|
||
每条`rotations`必须保存密钥和消费者的非秘密引用、消费模式、不同的新旧版本引用、轮换时间，以及以下五类可复核结果：轮换前基线、新凭据成功、旧凭据拒绝、业务连续性、提供器访问审计。`secret_value_not_exported=true`声明采集过程没有导出密钥正文；该字段为false会使报告失败。
|
||
|
||
## 3. 两种消费模式
|
||
|
||
真实报告必须同时覆盖：
|
||
|
||
- `DYNAMIC_READ`：逐设备密钥等按请求从CSI原子挂载目录重新读取的凭据；新版本生效后下一次请求使用新值，过渡窗口结束后旧值被拒绝；
|
||
- `ROLLING_RESTART`：数据库、Redis、RTC、供应商、对象存储、方舟和进程级签名密钥等启动时读取的凭据；挂载版本更新后执行受控滚动重启，新Pod就绪再终止旧Pod，并确认旧版本失效。
|
||
|
||
只验证其中一种消费模式的云端报告仍为`FAIL`。本地报告允许只验证一种模式，以便开发环境检查工具链，但始终保留外部验收缺口。
|
||
|
||
## 4. 自动检查
|
||
|
||
报告包含11项检查：采集版本、证据来源、候选身份、采集候选绑定、提供器/身份/审计、两种轮换范围、版本转换、新凭据接受、旧凭据拒绝、业务连续性和全部探针/审计引用。任一失败使总结果为`FAIL`。
|
||
|
||
真实证据满足以下条件后才设置`external_validation_required=false`：来源为`KMS_HSM`、环境是预生产或生产、提供器和工作负载身份完整、至少两条轮换覆盖两种消费模式、新旧版本不同、新凭据成功、旧凭据拒绝、业务连续性通过、密钥正文未导出且所有审计引用存在。
|
||
|
||
## 5. 命令用法
|
||
|
||
```powershell
|
||
go run ./cmd/kms-rotation-conformance `
|
||
-capture E:\evidence\kms-rotation-capture.json `
|
||
-candidate-version 0.63.0-rc.1 `
|
||
-build-digest sha256:<64位摘要> `
|
||
-output E:\evidence\kms-rotation-report.json
|
||
```
|
||
|
||
输出路径必须为绝对路径。通过返回0，不一致时仍写出失败报告并返回1，文件、参数或JSON格式错误返回2。报告保存输入采集文件SHA-256，用于归档后检测替换。
|
||
|
||
## 6. 候选证据包门禁
|
||
|
||
`release-evidence-index-v2`中的`KMS_ROTATION`不可豁免。第一个文件必须是`PASS/REAL_KMS_HSM`报告并绑定同一候选；后续可以附SecretProviderClassPodStatus脱敏导出、云审计、滚动发布记录和安全签署材料。没有真实报告时，v3清单固定显示：
|
||
|
||
- `REAL_KMS_HSM_REPORT:0/1`；
|
||
- `DYNAMIC_READ:0/1`；
|
||
- `ROLLING_RESTART:0/1`。
|
||
|
||
本地报告、单一消费模式、跨候选版本、缺旧凭据拒绝、缺业务连续性或缺云审计时，`KMS_ROTATION`必须保持`PENDING`，不能使用`WAIVED`绕过。
|
||
|
||
## 7. 本地低强度演练
|
||
|
||
```powershell
|
||
pwsh -NoProfile -File .\scripts\verify-local-secret-rotation.ps1
|
||
```
|
||
|
||
脚本沿用现有本地设备HMAC轮换：原密钥请求成功，启动同镜像临时API并注入新密钥，新密钥请求成功、旧密钥返回401、就绪接口持续可用，随后恢复Compose API及原本地密钥。新增步骤把结果输出为`PASS/LOCAL_SECRET`报告，并确认它仍要求外部验证。脚本结束删除临时容器、采集和报告，不改变真实KMS门禁。
|