Sigstore bundle 怎样保存签名验证材料

如果把签名、证书和透明日志记录分散保存，几年后很难判断“这份签名当时用什么材料验证”。Sigstore bundle 的核心做法是把签名内容和验证材料放进同一个可传递文件，让验证端可以根据同一份材料复原验证上下文。

官方地址：https://docs.sigstore.dev/

本篇只讨论保存边界：签名本身放在哪里、证书或公钥提示怎样表达、透明日志和时间戳什么时候需要一起保存。当前官方 bundle 文档把它描述为“验证制品签名所需的全部材料”，规范文件用 mediaType 标识 bundle 版本。

升级范围：先把 bundle 看成一个验证输入

迁移时不要把 bundle 当成“签名文件的另一个后缀”。它至少包含两个职责不同的部分：

• content：签名内容，可以是普通的 message signature，也可以是 DSSE envelope；
• verificationMaterial：验证签名所需的材料，例如 Fulcio X.509 证书、公钥提示、透明日志条目和时间证明。

因此，只有签名值而没有匹配的 payload、证书或可信根，不能称为完整的 bundle。公钥提示也不是公钥本体：它表示验证端要按双方约定的外部机制取钥匙，不能误写成“bundle 已经内置公钥”。

变更表：当前 bundle 应保存哪些材料

按当前 v0.3 结构整理文件时，可以用下面的表做字段盘点：

透明日志条目在规范中不是所有场景的硬性必需字段，但面向公共消费的 bundle 强烈建议保留。使用短期 Fulcio 证书时，至少要有透明日志的 signed entry timestamp 或 RFC 3161 时间戳，帮助验证端证明签名发生在证书有效期内。

旧代码风险：只存 signature 会丢掉什么

旧流程常见的做法是把 signature、certificate、rekor entry 分别放在不同目录，再靠发布脚本约定文件名。这种方式有三个风险：

1. 制品和签名材料容易错配，验证端拿到的证书可能不是签名时使用的那一张；
2. 短期证书过期后，缺少日志时间或 RFC 3161 时间戳，无法判断签名发生时是否有效；
3. 离线环境不能临时访问 Rekor 或 TUF，分散材料不完整时验证会被迫退回在线流程。

迁移的关键不是把多个文件压缩成一个文件，而是让 bundle 内的签名内容、验证材料和制品摘要保持同一条关系。可信根仍然是验证端的信任配置，不能把任何随制品传来的证书自动当成可信根。

新写法：用 cosign 生成并复用 bundle

对普通 blob，cosign 可以在签名时直接写出 bundle，再把同一个文件交给验证命令：

# 生成签名与 bundle；--yes 表示在无交互环境确认签名流程
cosign sign-blob artifact.bin --bundle artifact.sigstore.json --yes

# 用 bundle、期望的身份和 OIDC issuer 验证同一个 blob
cosign verify-blob artifact.bin \
  --bundle artifact.sigstore.json \
  --certificate-identity "https://github.com/ORG/REPO/.github/workflows/release.yml@refs/heads/main" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

# 固定公钥场景改用 --key；公钥提示不能替代这个外部公钥文件
cosign verify-blob artifact.bin --bundle artifact.sigstore.json --key cosign.pub

上面的命令示例表达的是文件关系，不代表本文在本机执行了签名或验证。keyless 场景要把身份和 OIDC issuer 作为验证约束；公钥场景则显式提供公钥。两类流程都要保证 bundle 绑定的 payload 与待验证的 artifact.bin 是同一个制品。

回归检查：四个边界要逐项确认

1. 版本：保存顶层 mediaType，不要用文件名猜 bundle 版本；旧客户端需要确认是否接受 v0.3。
2. 内容类型：普通签名和 DSSE envelope 的验证路径不同，不能只判断文件扩展名。
3. 时间材料：短期证书不能只看今天是否过期，要检查日志时间或 RFC 3161 时间戳是否能证明签名时刻。
4. 离线根：离线验证除了 bundle，还要提前保存并维护可信根；只把 bundle 拷进隔离区并不等于拥有完整信任配置。

可以把发布物组织为“制品 + bundle + trusted root 配置”的最小集合。bundle 负责携带签名验证材料，trusted root 负责说明哪些服务证书、透明日志和时间戳根值得信任，两者不要混为一谈。

迁移清单

• 为每个制品固定一个 bundle 文件名，并把它与制品摘要放在同一发布记录中。
• 确认 bundle 的 mediaType、签名内容类型和验证材料都来自同一次签名。
• keyless 签名保存证书身份与 OIDC issuer 约束，公钥签名保存明确的公钥来源。
• 面向公共消费时保留透明日志条目；使用短期证书时额外确认签名时间证明。
• 为离线环境单独分发并维护 trusted root，不把随制品附带的材料直接提升为根信任。

常见问题

bundle 里有证书，是不是可以不配置 trusted root？

不是。证书属于被验证的材料，trusted root 用来验证服务材料是否可信，职责不同。

只有签名和公钥提示，能不能叫完整 bundle？

可以表示一种验证材料组合，但公钥本体仍需通过约定的外部机制取得；如果目标是公共 Sigstore 的 keyless 离线验证，还要按实际流程保存证书、透明日志或时间戳等材料。

参考资料：https://github.com/sigstore/docs/blob/main/content/en/about/bundle.md、https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto、https://github.com/sigstore/cosign/blob/main/doc/cosign_verify-blob.md