AskaEth
bc1b09b776
P2-1（安全）：`signing-status.yml` 原先把生产签名种子注入到 `pull_request` 与任意 ref 的 `workflow_dispatch` 运行里，而 CI 跑的是那个 ref 自己的代码 ⇒ 任何能推分支的人都能把种子搬走 （这把种子能给全量已装客户端签可信清单）。改成： - 去掉 `pull_request` 触发； - 注入行加 ref 门：`github.ref == 'refs/heads/main' && secrets.… || ''`； - 非 main 用 `ULL_SIGNING_KEY_WITHHELD` 说明原因，于是 ② 读「未判定（未注入）」而不是「没配」。 runbook §2 步② 加硬顺序：先合这笔、再录 Secret。 P2-2：`--key` 读不了（不存在 / 是目录 / 非 UTF-8）曾在 main 的 try 之外抛 traceback + rc=1， 与「未就绪」同码；现在统一 rc=2 + 一行说明，并补用例 `key_unreadable`。 P2-3：4 处文案指针修正（`signing-ready.yml` → `signing-status.yml`；§3 → §2 步③；§1–§3 → §2 步①–③；§4 → §2 步⑤ / §5）。新增两条机检：`section_refs`（输出的 `§N` 必须是 runbook 真实 章节号）与 `signing_ready_wiring_selftest.py`（文档里的 `packaging/…`/`crates/…`/`.github/…` 路径必须真存在），后者另带三处变异重放：去掉 ref 门 / 加回 pull_request / 改坏文档路径 ⇒ 必须红。 顺带修掉 r1 复审指出的两处小问题：`--release-assets` 里只有 `manifest.json.sig` 时的子串假读数 （先剥 `.sig` 再判清单）、③ 那个从不参与判定的 bool 保持原样（无行为影响）。 selftest 拆成两份（400 行红线）：判据本体 + 接线/文案。guards.yml 仍 399 行零改动。
191 lines
15 KiB
Markdown
191 lines
15 KiB
Markdown
# 签名就绪度操作手册（M255）
|
||
|
||
本文件是**人类照做**的手册：从「信任表是空的」走到「发出去的 Release 用客户端判据能验过」。
|
||
背景/威胁模型/轮换纪律在 [`signing.md`](signing.md)；本文件只讲**步骤、命令、坑**。
|
||
|
||
> ⚠ 本文件**不含**任何真实私钥、种子或公钥。所有示例都是 `<尖括号占位符>`。
|
||
> `--generate-key` 的输出是**敏感物**：只在你要贴进 Secret 的那一次运行里存在，别存文件、别贴 issue。
|
||
|
||
## 0. 现状读一遍（2026-11 的 M254 审计结论）
|
||
|
||
`crates/core/src/update/trust.rs` 的 `PRODUCTION` 表在 `PINNED-KEYS` 标记之间是**空的**。空表 =
|
||
`KeyringEmpty` 一律拒装 ⇒ **今天任何正式二进制都验不过任何清单**（fail-closed 成立，但用户端表现为
|
||
「更新永远失败」）。已存在的部分（都能用）：
|
||
|
||
| 环节 | 在哪 | 今天的状态 |
|
||
|---|---|---|
|
||
| 生成钥 | `sign_manifest.py --generate-key` | 有；打印 Secret JSON + `PinnedKey` 那一行 |
|
||
| 钥 ↔ 信任表对账 | `sign_manifest.py --check-pinned-keyring` | 有；**今天必然红**（表空 ⇒ 「信任表是空的」） |
|
||
| 签名 | `sign_manifest.py --sign dist/manifest.json` → `.sig` | 有；**今天必然红**（`ULL_MANIFEST_SIGNING_KEY` 没有，前面先红） |
|
||
| 回验 | `sign_manifest.py --verify-pinned dist/manifest.json` | 有；**今天必然红**（表空 ⇒ 「无从回验」） |
|
||
| 发布接线 | `release-publish.yml` 的「签更新清单」步 | 有；上面四条任一非零 ⇒ 不出 Release（**这是对的**） |
|
||
| 资产上传 | `release-publish.yml` 的 `assets=(… manifest.json manifest.json.sig …)` | 有 |
|
||
| **操作步骤与可见性** | 本文件 + `packaging/check_signing_ready.py` + `signing-status.yml` | **本次补上的就是这两样** |
|
||
|
||
一句话：**工具链不缺，缺的是有人把钥钉进表里。** 那件事只有人类能做（塔不会自己生成生产私钥）。
|
||
|
||
## 1. 先看读数（不用碰任何钥）
|
||
|
||
```bash
|
||
python3 packaging/check_signing_ready.py # 三行读数 + 退出码
|
||
python3 packaging/check_signing_ready.py --dist dist # 顺手看一眼本地留档
|
||
```
|
||
|
||
三行分别是 ① `PRODUCTION` 表空不空 ② 环境里有没有签名钥（并顺手对账「这把钥在不在表里」）
|
||
③ 最近一次发布的 `.sig`/清单痕迹（取不到就写「未知」——本地没留档 ≠ 上次没签）。
|
||
|
||
退出码：`0` 就绪 / `1` 未就绪 / `2` 用法错（参数写错、`trust.rs` 读不到、标记丢了）。
|
||
**未就绪时会打印一行修复命令**，直接照抄即可。CI 里同一条读数在 `Signing status（播报）` workflow 的
|
||
job summary 里（见 §6 —— 它是播报，不是门禁）。
|
||
|
||
## 2. 人类要亲手做的 5 步（下单清单）
|
||
|
||
下面每一行都只有命令与占位符，**没有任何密钥值**。做完一步就把该步的验证跑一遍。
|
||
|
||
> 🔴 **顺序硬要求（M255 r1 P2-1）：先合并「播报 workflow 的 ref 门」那笔改动，再录 Secret。**
|
||
> 播报 workflow（`.github/workflows/signing-status.yml`）会把 `ULL_MANIFEST_SIGNING_KEY` 注入到
|
||
> 就绪度那一步的环境里；那个注入**只在 `refs/heads/main` 上发生**，而且该 workflow **没有**
|
||
> `pull_request` 触发。这两条是安全边界：仓库内分支的 PR 与任意分支的 `workflow_dispatch` 都拿得到
|
||
> 仓库 Secret，而 CI 会在**那个 PR 自己的代码**上执行 checker —— 种子一旦进过那种运行，等于交给
|
||
> 任何能推分支的人（这把种子能给**全量已安装客户端**签可信清单，即用户端 RCE）。
|
||
> 所以：**ref 门那笔没合进去之前不要录 Secret**；录之前先确认线上版本里有
|
||
> `github.ref == 'refs/heads/main'` 这个条件式（§6 也写了这条）。
|
||
|
||
```bash
|
||
# ① 生成钥（⚠ 输出是敏感物；不要跑在 CI 里，不要重定向到仓库里的文件）
|
||
python3 packaging/sign_manifest.py --generate-key --key-id <key-id，例 ull-release-2026a>
|
||
|
||
# ② 把打印出来的那一行 JSON（{"key_id": …, "seed_hex": …}）贴进仓库 Secret（⚠ 先读上面的顺序硬要求）：
|
||
# Settings → Secrets and variables → Actions → New repository secret
|
||
# 名字必须**逐字**是：ULL_MANIFEST_SIGNING_KEY
|
||
# （等价 CLI：gh secret set ULL_MANIFEST_SIGNING_KEY，然后按提示粘贴，别用 -b 把值留在 shell 历史里）
|
||
|
||
# ③ 把打印出来的那一行 PinnedKey { … } 贴进 trust.rs 的 PINNED-KEYS 标记之间（标记本身别动）
|
||
grep -n 'PINNED-KEYS' crates/core/src/update/trust.rs
|
||
# 贴完提交这次改动 —— 公钥进 git 是对的：它是信任锚，本来就该公开可审计
|
||
|
||
# ④ 对账（需要一个有钥的环境：本机就先 export，别写进任何文件）
|
||
python3 packaging/sign_manifest.py --check-pinned-keyring # 期望：ok: 签名钥 <key-id> 已被钉住
|
||
|
||
# ⑤ 发一次带 .sig 的 Release，然后用**客户端的判据**回验（这一步不需要私钥）
|
||
python3 packaging/sign_manifest.py --verify-pinned dist/manifest.json # 期望：ok: 用钉住的公钥能验过
|
||
```
|
||
|
||
`--verify-pinned` 才是证据：`--sign` 说「签好了」不算 —— 客户端拿的是 `trust.rs` 里那把公钥。
|
||
发布后建议再用**下载下来的资产**验一次（§5），因为「CI 上能验过」不等于「上传的那份就是被签的那份」。
|
||
|
||
### 每一步的判据（怎么知道这步真的成了）
|
||
|
||
| 步 | 成功长什么样 | 失败长什么样 |
|
||
|---|---|---|
|
||
| ① | 打印 ① 私钥 JSON、② 一行 `PinnedKey`、③ 公钥十六进制；脚本自带「自己签自己验」自检 | `error: 自己签自己验不过` ⇒ 不要用这把钥，环境有问题 |
|
||
| ② | `gh secret list` 里能看到 `ULL_MANIFEST_SIGNING_KEY` | 列表里没有 / 名字拼错（大小写、下划线） |
|
||
| ③ | `check_signing_ready.py` 的 ① 从「未就绪」翻成「就绪」 | ① 仍说 0 条 ⇒ 贴到了标记**外面**（读数里会点名「另有 N 条在标记之外（key_id：…）」） |
|
||
| ④ | `ok: 签名钥 … 已被钉住` | `签名钥（…）不在信任表里` ⇒ ②③ 不是同一把钥 |
|
||
| ⑤ | `ok: manifest.json.sig 用钉住的公钥 … 能验过（客户端会接受）` | `拿 trust.rs 里钉住的公钥回验不过 —— 这份 Release 的用户会全部拒装。别发版` |
|
||
|
||
## 3. 一次发布里签名是怎么被执行的（不用额外操作）
|
||
|
||
`release-publish.yml` 的「签更新清单」步按顺序跑四条，任一非零 ⇒ 本步红 ⇒ 不出 Release：
|
||
|
||
```bash
|
||
sign_manifest.py --self-test # RFC 8032 向量：脚本自己没坏
|
||
sign_manifest.py --check-pinned-keyring # Secret 里的钥必须已在 trust.rs 钉住
|
||
sign_manifest.py --sign dist/manifest.json # 产出 dist/manifest.json.sig
|
||
sign_manifest.py --verify-pinned dist/manifest.json # 用钉住的公钥回验产出
|
||
```
|
||
|
||
这一步已经把「未配置 Secret」「钥没钉」「钥不匹配」都变成**发版前的红**，所以「发了但没签名」这条
|
||
不会发生 —— 它只会在发布 job 上红，不会静默发出去。
|
||
|
||
## 4. 已知坑（按踩到的概率排序）
|
||
|
||
1. **Secret 名字拼错**（`ULL_MANIFEST_...` vs `ULL_MANIFEST_KEY`）：可复用工作流只拿得到自己**声明过**的
|
||
secret，名字不对就是空串 ⇒ 签名步红，而错误文案会反过来指控「Secret 没配」。`release-publish.yml`
|
||
已经声明了这一个（`required: false`，缺省走 fail-closed），照抄名字即可。
|
||
2. **只配 Secret 没钉表**：`--check-pinned-keyring` 报「信任表是空的（fail-closed）」，并**直接打印**
|
||
该贴的那一行 `PinnedKey`（只含公钥，安全）。照贴即可。
|
||
3. **只钉表没配 Secret**：`--check-pinned-keyring` 报「没有签名密钥」。这不影响已有用户（表非空 ⇒
|
||
他们能验签），但发不了新版。
|
||
4. **Secret 与 trust.rs 是两把不同的钥**：最常见于「换过钥但只更新了一边」。判据是**公钥字节**，
|
||
`key_id` 只是标签；`--check-pinned-keyring` 会把两边的公钥都打出来对账。
|
||
5. **把条目贴到标记外面**（`];` 之后、或贴着别的 `const`）：等于没钉。`check_signing_ready.py` 会**点名**
|
||
标记之外的 `key_id`；注意本仓 `TEST_ONLY` 那条**本来就在标记之外**（那是它的正确位置），所以读数是
|
||
「另有 N 条在标记之外（key_id：…）」而不是「贴错了」—— 对着 `key_id` 自己认。
|
||
6. **`set -x` / `echo $ULL_MANIFEST_SIGNING_KEY`**：一次就够把私钥泄进日志。工作流里那一步显式 `set +x`
|
||
且只回显**公钥**；本机调试同理，别开 trace。
|
||
7. **`--generate-key` 的输出落进文件/issue/聊天**：当成泄露处理，走 `signing.md` §5 轮换（旧钥签新钥）。
|
||
8. **以为「非 main 分支的读数」就是仓库状态**：播报 workflow **只在 `refs/heads/main` 上注入** Secret
|
||
（也没有 `pull_request` 触发 —— 见 §2 的顺序硬要求与 §6）。非 main ref 的运行里 ② 显示
|
||
「**未判定** —— 非 main ref（按设计不注入 Secret）」，这是**策略**，不是「没配」。以 `main` 上的读数为准。
|
||
9. **`.sig` 没上传到 Release**（手改过 `assets=(…)` 那一行）：客户端取 `<产物根>/manifest.json.sig`
|
||
会 404 ⇒ 所有人验签失败。上传后请在资产列表里**亲眼看到** `manifest.json` 与 `manifest.json.sig`
|
||
两个名字（§5 的 `gh release view` 那条命令就是干这个的）。
|
||
10. **删掉旧钥条目太早**：用户机器上装着旧二进制，它只认旧钥；删条目的那个版本必须**只**由新钥签，
|
||
并且至少一个发布周期的双签名之后（`signing.md` §5）。
|
||
11. **「昨天验过」不等于「今天验得过」**：`PRODUCTION` 是**编译期**常量，改 `trust.rs` 只影响**下一次构建**。
|
||
已在用户盘上的旧二进制永远用旧表 —— 这是设计，不是 bug。
|
||
12. **给播报 workflow 加回 `pull_request` 触发、或去掉注入行的 ref 门**：等于把生产签名种子交给任意推
|
||
分支的人的代码（自更新链 = 用户端 RCE）。这两处各有接线用例钉着（去掉任一处都会红），
|
||
别为了「PR 上也能看读数」去动它 —— 看读数请对 `main` 跑，或读 §1 在本地跑。
|
||
|
||
## 5. 发布后回验（发布侧，不需要私钥）
|
||
|
||
```bash
|
||
# 资产里必须两个名字都在（漏一个等于全员验签失败）
|
||
gh release view <tag> --json assets --jq '.assets[].name' | grep -E 'manifest\.json(\.sig)?$'
|
||
|
||
# 拿下载回来的真实资产复现客户端判据：manifest.json 与 .sig 必须成对、且是同一份字节
|
||
mkdir -p /tmp/verify && gh release download <tag> --pattern 'manifest.json*' --dir /tmp/verify
|
||
python3 packaging/sign_manifest.py --verify-pinned /tmp/verify/manifest.json
|
||
```
|
||
|
||
退出码 0 = 「客户端会接受这份清单」。非零时**不要**手动 `edit` Release 绕过 —— 先看脚本 stderr
|
||
（它会说清楚是表空、无 `.sig`、还是签名对不上）。
|
||
|
||
## 6. CI 里那条读数：`Signing status（播报）`
|
||
|
||
`.github/workflows/signing-status.yml` 在 `push: branches: [main]` 与**手动 dispatch** 上跑，把 §1 的三行
|
||
搬进 job summary。**它不是门禁**：
|
||
|
||
* 它**不应被设为 required check**（分支保护里不要勾它），也不阻断任何其它 job；
|
||
* 它就绪度那一步**恒 `exit 0`**：未就绪用 `::warning::` 播报，不用 error 级注解（那会让人以为构建挂了）；
|
||
* **生产签名种子只在 `refs/heads/main` 上注入**（`github.ref == 'refs/heads/main' && secrets.… || ''`），
|
||
而且**没有 `pull_request` 触发**。理由是安全：仓库内分支的 PR / 任意分支的 dispatch 都拿得到仓库 Secret，
|
||
而 CI 跑的是那个 ref 自己的代码 —— 种子进过那种运行就等于交给任何能推分支的人。
|
||
非 main ref 的运行里 ② 显示「**未判定** —— 非 main ref（按设计不注入）」，**不写「没配」**；
|
||
* 它**刻意不声明 `workflow_call:`**，所以别的 workflow 没法 `uses:` 它；接线自检还会扫全部 workflow，
|
||
任何 `uses: …/signing-status.yml` 出现即红（防的是「顺手接进 dev 线把播报变成门禁」）；
|
||
* 它**绿**只说明脚本跑完了；结论只看 summary 里的三行字。
|
||
* 同一 workflow 里另有两步跑自测（`packaging/tests/signing_ready_selftest.py` +
|
||
`packaging/tests/signing_ready_wiring_selftest.py`）：那两步**会红**，红 = **尺子坏了**（三行读数/退出码/
|
||
变异重放/接线与 ref 门之一没过），与「签名未就绪」是两件不同的事，措辞在 summary 里分开写。
|
||
|
||
为什么不做成门禁：今天已经有四次「守卫假绿」的账（见 `packaging/README.md` §12 里那几条先例）。
|
||
把一条**按定义今天必然失败**的检查做成 required，只会有两种结局 —— 要么所有人学会忽略红叉，
|
||
要么有人把它改成永远绿。真正的红留在 `release-publish.yml` 的签名步：那里今天红是**对的**，
|
||
因为签不出来的产物本来就不能发。
|
||
|
||
## 7. 本手册**没**覆盖 / 没验的部分（明账）
|
||
|
||
* **Authenticode / SmartScreen**：项目自有签名解决的是「这条自更新链是不是我们发的」，用户双击 exe 看到
|
||
的「未知发布者」与此无关（`signing.md` §0）。
|
||
* **托管签名**（如 SignPath）：只是后续可替换路径，本手册与判据都不依赖它。
|
||
* **本文档里的命令没有被真跑过一遍**：`--generate-key` 会产出生产私钥，塔不生成、也不跑它；
|
||
②③ 两步要动 GitHub Secret 与 Rust 常量，同理。所以本手册是「按现有脚本的接口写的步骤」，
|
||
首次执行时**以脚本的实际输出为准**，跑完请回来修正本文档。
|
||
* **「用户机器上真的更新成功」**没有在本条里验：需要一次真 Release + 一台装着旧版本的机器。
|
||
* **ref 门只在本地验证过**（抽 `run:` 块用 Git Bash 跑 + 接线用例的文本变异），没有在真 Actions 上看过
|
||
`secrets` 的求值结果 —— 第一次真跑请确认非 main ref 的 ② 显示「未判定」。
|
||
|
||
## 8. 相关文件
|
||
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `packaging/check_signing_ready.py` | 三行就绪度 + `0/1/2` 退出码（只读、零第三方依赖） |
|
||
| `packaging/tests/signing_ready_selftest.py` | 判据自测：三行/退出码/两向变异重放/`--key` 用法错/指针章节 |
|
||
| `packaging/tests/signing_ready_wiring_selftest.py` | 接线自测：不是门禁 / 不被 `uses:` / **ref 门** / 文档路径存在性 + 三处变异 |
|
||
| `.github/workflows/signing-status.yml` | 把三行搬进 job summary 的**播报** workflow（不是门禁；种子只在 main 注入） |
|
||
| `packaging/docs/signing.md` | 为什么签名、威胁模型、轮换纪律、四条发布侧命令的红法对照表 |
|
||
| `packaging/sign_manifest.py` | 生成钥 / 签名 / 对账 / 回验的唯一实现（`--self-test` 跑 RFC 8032 向量） |
|