Files
crawler-plugin/docs/ops/credential-rotation-design-2026-10-02.md
T
huangzd1997 3fd58ec197 feat(安全): 店铺凭据解密支持历史密钥,为轮换留出双密钥窗口
换 shop-credential-key 会让 435 行历史密文全部解不开,而调用方拿到解不开的串
是当明文口令往外发(紫鸟账号、1688 店铺、第三方 api_key 都这样用)。
现在新增 aiimage.security.shop-credential-key-previous(逗号分隔),解密按
当前→历史的顺序回试,加密只用当前密钥;全部不中时 WARN 写明"这串密文会被
当成明文口令发出去",不再静默回退。与当前密钥相同的历史项自动丢弃。
previous 留空时行为与改动前逐字节一致(6 例单测盯着这一条)。
轮换设计与取证见 docs/ops/credential-rotation-design-2026-10-02.md(只含长度与
sha8 指纹,无明文值);轮换本身与存量重加密脚本仍未做。
2026-10-02 11:01:18 +08:00

126 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 店铺凭据密钥轮换设计(2026-10-02)
范围:`aiimage.security.shop-credential-key` 这一把密钥的轮换,以及轮换时三张库里凭据表怎么处理。
本文只给设计、取证结果和待办,**没有执行过任何轮换或重启**。
## 一、为什么现在不能直接换密钥
`ShopCredentialCryptoService.decrypt()` 解不出来时回退返回原文(`ShopCredentialCryptoService.java:76-97`)。
调用方拿到这串原文就当明文口令往外发——紫鸟账号、1688 店铺、第三方 api_key 都是这样被使用的。
所以「改了密钥、没重加密存量」这段时间里的表现不是报错,而是**拿着密文当口令去登录**,
失败点离原因很远,最难查。
本次改动(只做防护,未动线上):
- `ShopCredentialCryptoService` 支持 `shop-credential-key-previous`(逗号分隔的旧密钥),解密时当前密钥失败后按顺序回试旧密钥,加密只用当前密钥。
- 回退不再静默:打 WARN,写明「当前密钥 + N 个历史密钥都试过」,并直接说出后果(这串密文会被当成明文口令发出去)。
## 二、生效值到底配在哪一层(今天的实测)
| 键 | 位置 | 读数 |
| --- | --- | --- |
| `shop-credential-key` | 容器 `/app/application-server.yml`(宿主 `/app/java/`) | `configured=yes len=64 sha8=190cc85c occurrences=1`,**两台一致** |
| `jwt-secret` | 同上 | `len=64 sha8=2d40fe8a`,**两台一致** |
| `AIIMAGE_SHOP_CREDENTIAL_KEY` | 宿主 `/.env`、java 进程 environ | **两处都没有** |
| `AIIMAGE_JWT_SECRET` | 同上 | **两处都没有** |
| `AIIMAGE_DB_PASSWORD` | 宿主 `/.env`(= java 进程 environ) | `len=16 sha8=83809acd`,两台一致 |
**结论:这两把密钥的生效值只有 yml 一个来源,没有环境变量覆盖它。** 之前按「改 `/.env` 追加 export」的
配方去轮换这两把是无效的——那条配方只对 `/.env` 里真实存在的那些键有效。改密钥就改
`/app/java/application-server.yml`,两台各一份,改完 `sha8` 应当同步变化。
复现命令(只读,值不出生产):
```
MSYS2_ARG_CONV_EXCL='*' python scripts/_prod_config.py all --container java-server \
--file /app/application-server.yml --key shop-credential-key
```
## 三、存量行的形态:没有明文(本次实测)
`scripts/_probe_credential_decrypt_audit.sh` 在主机A 上用**当前密钥真解了一遍**三张表的七个凭据列,
只输出计数。判据与 Java 一致:AES/ECB/PKCS5Padding,密钥 = SHA-256(原文密钥) 前 16 字节;
并且必须过 base64 往返、16 字节对齐、填充合法、**解出来是合法 UTF-8** 四道关
——只看长度和对齐是不够的,换错密钥也能解出「看着像样」的字节。
| 表.列 | 行数 | 空 | 解得出 | b64 非串 | 长度不对 | 填充不对 | 非 UTF-8 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `biz_shop_manage.password` | 86 | 0 | 86 | 0 | 0 | 0 | 0 |
| `biz_user_api_secret.secret_value` | 314 | 0 | 314 | 0 | 0 | 0 | 0 |
| `biz_image_video_secret.copy_api_key` | 7 | 0 | 7 | 0 | 0 | 0 | 0 |
| `biz_image_video_secret.t8_key` | 7 | 0 | 7 | 0 | 0 | 0 | 0 |
| `biz_image_video_secret.t8_video_key` | 7 | 2 | 5 | 0 | 0 | 0 | 0 |
| `biz_image_video_secret.voice_api_key` | 7 | 0 | 7 | 0 | 0 | 0 | 0 |
| `biz_image_video_secret.voice_group_id` | 7 | 0 | 7 | 0 | 0 | 0 | 0 |
三点用处:
1. **没有明文行**,435 行里 433 行是当前密钥解得出的密文,另 2 行是空值。所以重加密可以走纯 Java
一条路,不需要「遇到解不出的行就跳过」的分支——那个分支的存在本身就等于把密文当明文写回去。
2. 轮换前跑一次、轮换后跑一次,**`解得出` 的计数应当一模一样**,这是这批改动的验收标准。
3. 写入路径本来就全过加密(`ShopManageService.java:100,124`、`UserApiSecretService.java:843`,
两处 `setSecretValue`/`setPassword` 都包着 `encrypt(...)`),没有发现明文字段入口。
## 四、轮换顺序(每一步都能单独发版)
1. **先发版**:带双密钥回试的版本。此时 `previous` 为空,行为与旧版逐字节相同
(`behaves_exactly_as_before_when_previous_keys_is_empty` 钉住这条)。
2. **改配置**:两台 `/app/java/application-server.yml` 同时改——`shop-credential-key` 写新值、
`shop-credential-key-previous` 写旧值。**这一步起新数据用新密钥加密,旧数据仍解得出。**
回滚 = 把两行改回原值重启,比重加密便宜得多。
3. **重加密存量**:跑一次迁移(下面第 5 节),把这 433 行用当前密钥重新加密。
4. **验证**:再跑 `scripts/_probe_credential_decrypt_audit.sh`,`解得出` 仍是 433、其余四类仍为 0。
5. **收尾**:清掉 `shop-credential-key-previous`,下次发版生效。留着不影响正确性,只是每次解密多一轮试。
顺序不能反:先改配置再发版的话,旧 jar 不认 `previous` 这个键,存量行立刻进回退分支。
## 五、重加密迁移的关键约束
- **只改密文,不改业务时间戳。** 这批表上有 `updated_at` 会被心跳/看板读,走实体更新会顺带刷新它。
- **不要走业务 Service 的写入路径**(会带缓存刷新、索引重算、`ziniaoShopIndexRefreshTrigger` 之类的副作用)。
用一条独立的取行→解密→用当前密钥加密→按主键回写的脚本,跑在 Java 侧。
- 分表分批、每批独立事务;失败要能重跑(重加密天然幂等,重复跑只是再解一次)。
- 迁移脚本**本次没写**,等你定了窗口再动。
## 六、不该走这条路的几把密钥
| 密钥 | 为什么另算 |
| --- | --- |
| `auth.jwt-secret`(sha8 `2d40fe8a`) | 换它 = 现有登录态全废,所有人被踢;必须单独定维护窗口,和重加密无关 |
| `AIIMAGE_DB_PASSWORD`(sha8 `83809acd`) | 库口令,改它要同时动 `/.env` 与 MySQL 账号,属另一套流程 |
| 极客图 / jikip / LLM 代理 key | 生效值在 yml 或 `biz_user_api_secret`,前者按普通配置轮换、后者随第五节的迁移一起走 |
| MinIO(B 机设备日志、A 机业务桶) | 走各自的 `.env`/服务重启,与店铺凭据无关 |
## 七、验证做到哪一步
- 新增 `ShopCredentialCryptoServiceTest` 6 条,`mvn -o -Dtest=ShopCredentialCryptoServiceTest test`
→ `Tests run: 6, Failures: 0, Errors: 0` + `BUILD SUCCESS`。
- 变异检验:把 `candidates.addAll(previousKeySpecs)` 删掉后重跑 → `Tests run: 6, Failures: 2`
(`rotates_key_but_still_decrypts_legacy_ciphertext`、`tries_several_previous_keys_in_order` 变红),
说明这两条真的在钉双密钥回试,不是恒绿断言。
(Python 侧的等价做法见 `scripts/tests/`:`umask 077` 挪到 `base64 -d >` 之后、或绕过 `upload_and_run_command` 直接拼命令,各有 1 条用例变红,改完的文件按 md5 原样还原。)
- 这批测试走的是标准生命周期(`mvn -o -Dtest=ShopCredentialCryptoServiceTest test`)。
上午有一段时间 `test-compile` 被并发会话新加的未跟踪测试挡住,当时只能用「javac 单编我的测试类 +
`surefire:test` 单跑」绕过;09:5x 复跑时那条阻塞已经自己清了,没有动过别人的文件。
- Python 侧:`scripts/tests` 共 78 例(`PYTHONUTF8=1 python -m pytest scripts/tests -q` 全绿)。
掩码层那 8 个护栏点也各打坏过一次(出口不掩码、三层各自失效、`verdict` 把读不到当一致、裸标记不记录、MSYS 路径不拦、`atexit` 没注册),**8/8 都有用例变红**;其中「`atexit.register(_report)` 删掉」原本是漏网之鱼——直接调 `_report` 的用例看不见「没注册」这个状态,补了一条开子进程实跑的用例才咬住。
## 八、还欠什么
1. **轮换本身没执行**,新密钥由你定、yml 由你改(生产写操作按约定只交付命令,不代跑)。
2. **重加密迁移脚本没写**——第五节的约束已经定好,等窗口。
3. `ShopManageService.java:260` 往 VO 写的是 `masked`,读侧掩码是有的;**日志侧**这几把密钥有没有
别的出口,本次没审。
4. 外观/货源的 LLM key 分组那部分结论来自之前的实测记录(一把 key 平均挂 9.5 个账号),
本次没复核,引它做决策前先重跑一遍当时的脚本。
5. **两台 `/tmp` 里躺着 48 个 644 权限的历史探针副本**(主机A 36 个、主机B 12 个,其中 20 个含
`password|secret|token|api_key` 形式的行)——那是 `_ssh_bash.py` 加 `rm -f` 收尾之前几次会话留下的。
上传命令现在带 `umask 077`,新副本落成 600,但**旧的这 48 个还在**,删除算生产改动,命令给你:
```
python scripts/_ssh_bash.py a scripts/清理用临时脚本 # 或直接
MSYS2_ARG_CONV_EXCL='*' python scripts/_ssh_probe.py all 'rm -f /tmp/_run__*.sh; ls /tmp/_run__*.sh 2>/dev/null | wc -l'
```
后面那条回读应当是 `0`。