跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

aggrega sign

aggrega sign 对一个或多个已发布的目录制品进行签名,并将每个签名作为 OCI referrer 附加。它是 aggrega push --sign 在发布之后的对应命令:用它为一个未签名发布的制品签名,或在一次调用中为一整批制品签名。如果某个制品已带有一个能通过其注册表信任策略验证的签名,它不会再为该制品添加第二个签名。

功能说明

aggrega sign 为每个 <reference> 解析注册表中已有的摘要,对该摘要签名,并将签名包作为 referrer 附加。它从不重新推送、重新打标签或以其他方式修改已发布的字节——制品是不可变的,签名是一个指回该制品的同级 manifest。因此,制品可以在发布之后签名,而无需升级版本。

签名之前,它会读取该引用已带有的签名,并依据此工作区为该引用所在注册表持有的信任策略(即 aggrega pull 进行验证所依据的策略)对其进行判定。只要有一个签名通过验证,无论签名者是谁,该引用即视为已签名:命令会打印 Already signed:,附上该引用、其摘要、签名身份,以及在透明日志记录了该签名时的签名时间(存在多个时取最早的此类签名),不附加任何内容,并将该引用计为已签名。验证无密钥签名的读取方会按通过验证的最早签名确定版本日期,并给出该签名的签名者,如 aggrega registry update 所述,因此再添加一个签名只会增加一个 referrer 和一条透明日志条目,而不会改变此类读取方从该版本获取的任何信息。

如果某个注册表的策略既未固定公钥,也未指定受信任身份,则没有可用于判定签名的依据,因此该注册表中的引用无论已带有什么签名都会被签名。仅带有策略不接受的签名的引用也会被签名,因为对于依据该策略进行验证的读取方而言,这些签名都不算数。

签名是一个 Sigstore(与 cosign 兼容)签名包,与 aggrega push --sign 附加、aggrega pull 验证的格式相同。referrer 将该签名包命名为 signature.json,因此通用 OCI 客户端按摘要拉取该 referrer 时,会将签名包写入该文件。

批量签名

传入多个引用,即可在一次调用中对它们签名:

aggrega sign \
hub.example.com/component/core/api-server:1.0.0 \
hub.example.com/component/core/worker:1.0.0 \
hub.example.com/feature/core/telemetry:2.1.0

无密钥签名为整个批次只解析一次身份——一次交互式认证,或在 GitHub Actions 上使用 runner 的环境 OIDC 端点——并在每个制品之间复用该身份,为每个制品签发一个新的短期 Fulcio 证书。交互式获取或外部提供的令牌会在每次签名中复用;环境端点则为每次签名签发一个新令牌。各引用可以指向不同的 registry:每个引用都使用这同一个身份,针对为其所在 registry 配置的 Fulcio 和 Rekor 端点进行签名。密钥路径(--key)对批次签名时完全不需要认证。

签名采用继续并报告方式:每个可签名的引用都会被签名;解析、签名或附加失败的引用会被记录下来,批次继续处理下一个引用,而不会在第一次失败时中止。已带有可验证签名的引用会被报告为已签名,并计为已签名。现有签名无法读取的引用——registry 未完成列举,或某个签名无法获取或判定且没有任何签名通过验证——会被记录为失败且不会被签名:未得到回答的问题绝不会被当作未签名的制品。批次结束后,如有任何引用失败,会向 stderr 打印列出失败引用的汇总,命令以非零状态退出。成功的引用无论其他引用是否失败都已完成签名。

一次签名多个引用

默认情况下,批处理逐个签名引用。--jobs N 最多同时签名 N 个引用,绝不超过 N 个。每个引用仍会完全像单独签名时那样被签名:解析其已发布的摘要;若它已带有可验证的签名,则保持原样;否则为它生成独立的签名——在无密钥方式下,使用它自己的临时密钥、自己的短期证书和自己的透明日志条目。身份仍只为整个批次解析一次,且在读取任何引用之前完成。小于 1 的值会被拒绝,且不签名任何内容。

无论各引用以何种顺序完成,输出都保持引用给出的顺序:每个引用的各行会在其之前指明的每个引用都完成后整体打印,因此两个引用的行绝不会交错,失败引用的汇总也按该顺序列出。将每个引用都当作单独签名来处理会带来一个后果:两次指明同一制品的批次,在同时签名两者时会得到两个签名,因为两者在生成签名时都看不到对方的签名;而逐个签名时,第二次会找到第一次的签名,并在其注册表的信任策略可验证该签名时不附加任何内容。

默认值为 1,因为除非你的配置指定了其他服务,否则无密钥签名会访问公益性的证书颁发机构和透明日志,而这些服务会限制其接受的请求数量。

每个批次一个凭据

一次调用中的每个引用都使用同一个凭据签名:单个持有的密钥,或单个无密钥身份。某个引用需要哪一种,由其所在 registry 的配置决定——适用于该 registry 的 signing.key_path 选择其指定的密钥,没有适用的配置时,该引用以无密钥方式签名。当各引用需要不同的凭据时——配置为一个 registry 指定了密钥而另一个没有,或指定了两个不同的密钥——命令不签名任何内容,并列出两侧各自的 registry。它在请求任何身份之前、读取任何 registry 之前就这样做,因此对于不会继续执行的运行,既不会附加任何内容,也不会提示任何人。

请改为每个凭据运行一次调用:一次列出使用密钥签名的 registry 上的引用,另一次列出其余引用。通过 --key 传入的密钥适用于所列出的每个引用,无论配置对各 registry 如何规定,因此带 --key 的调用绝不会因此被拒绝。

批次会被拒绝,而不是使用其中某个引用所需的凭据签名,因为签名一旦被他人获取就无法撤回。与上文所述的逐引用失败不同,这是整个批次的拒绝,而非某一个引用的拒绝:不会有任何引用被签名。当批次中某个 registry 要求签名时,消息会指出它,从而使该拒绝被理解为针对引用组合的拒绝,而非表明这些引用无法签名。该消息及其各部分所指内容,见 References signed together need different signing credentials(一起签名的引用需要不同的签名凭据)。

批次中途身份令牌过期

较长的批次可能超出短期身份令牌的有效期。在 GitHub Actions 上这不成问题:环境端点为每次签名签发一个新令牌,因此批次永远不会超出其身份的有效期。对于交互式获取或由操作者提供的令牌(--identity-token、AGGREGA_IDENTITY_TOKEN 或 SIGSTORE_ID_TOKEN),一个令牌服务于整个批次;如果它在批次中途过期,受影响的引用会按继续并报告方式被记录,批次继续执行。重新运行命令即可对报告的引用签名——或者,对于较长的脚本化批次,预先获取一个新令牌。

对于脚本化批次,预先获取一次令牌并将其导出,即可在无需浏览器往返的情况下对每个引用签名:

export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)
aggrega sign hub.example.com/component/core/api-server:1.0.0
aggrega sign hub.example.com/component/core/worker:1.0.0

关于 aggrega auth token,参见 ./aggrega-auth.md。

当某个步骤出现暂时性失败时

每个引用的签名分三个步骤:解析其已发布的摘要,对摘要签名,然后附加签名。其中两个步骤在以后续尝试可能成功的方式失败时会被重试:

  • 签名调用——遇到任何会使 registry 写入被重试的失败时重试,以及当 keyless 证书颁发机构报告无法处理身份令牌时重试。
  • 附加,即将签名包和 referrer manifest 写入 registry——遇到服务器错误、超时或连接被重置时重试;aggrega push 列出了这些失败。每次尝试都是对相同字节的一次新上传,而不是重新发送失败的请求,重复附加只会留下一个签名,而不是两个。

每个步骤最多尝试三次,间隔依次为半秒和一秒。解析摘要是读取操作,不会重试。要求放慢速度的注册表是另一种情况:发往它的每个请求,包括摘要解析和附加操作,都会按它要求的时间等待,如要求放慢速度的注册表所述。

一次无密钥签名调用最多会请求三个服务——向证书颁发机构请求证书、向透明日志请求条目,以及在已配置时向时间戳颁发机构请求时间戳——并且每个请求都在调用内部单独重试。其中某个服务以 429 Too Many Requests 或服务器错误(对于透明日志,指除 501 Not Implemented 之外的任何服务器错误)作答的请求会再次发送给该服务,因此最多尝试三次,间隔依次为一秒和两秒;只重复该请求,因此再次请求透明日志条目时不会再请求第二张证书。与透明日志的连接失败时也会再次请求,它随 429 或 503 发送的 Retry-After 会按其要求的时长等待。经过这些尝试后仍返回限流或服务器错误的应答会使签名调用失败,之后不会再整体重试该调用。

某个步骤在最后一次尝试后仍然失败时,会按照 continue-and-report 方式连同其错误记录到该引用下,批处理继续进行——附加失败会报告为无法附加的签名;任何其他失败会立即记录。

签名模式

  • 无密钥(默认)—— 使用一个临时密钥,由短期有效的 Fulcio 证书绑定到某个 OIDC 身份,并记录在 Rekor 透明日志中。Fulcio 和 Rekor 默认使用公益性的 Sigstore 实例(https://fulcio.sigstore.dev、https://rekor.sigstore.dev)。无密钥签名的可信时间戳来自 Rekor 透明日志的收录记录;单独的 RFC3161 时间戳机构是可选的 —— 提供带完整端点的 --timestamp-url 即可启用。在交互式终端中,无密钥签名无需任何标志:CLI 会打开浏览器获取短期有效的 OIDC 身份令牌。在 GitHub Actions 上同样无需标志:CLI 会从运行器环境提供的端点自动生成工作流 OIDC 令牌。对于其他非交互式 / CI 场景,请导出 AGGREGA_IDENTITY_TOKEN(或 SIGSTORE_ID_TOKEN),或传入 --identity-token;若未提供令牌、没有环境端点且没有终端,该命令将被拒绝。
  • 有密钥(--key)——离线保存的 ECDSA P-256 密钥(兼容 cosign 的 PEM)。不会连接任何身份提供方、证书颁发机构或透明日志;但仍会连接注册表,以解析每个摘要并附加其签名。

无密钥模式的 URL 和有密钥模式的密钥路径也可以来自 .aggrega-config.yaml 的 signing: 块(全局和按注册表配置);标志覆盖配置,配置覆盖公益默认值。在该文件中,每个 URL 都写成绝对 https URL —— 即 https://、主机名,以及可选的端口和路径,例如 https://fulcio.sigstore.dev —— 其他形式的值,如没有协议或以 http:// 开头的值,会在文件加载时被拒绝,并指出该文件和该键。OIDC 身份令牌永远不是配置字段,私钥也永远不会内联 —— 只提供指向它的路径。

构造方式以及签名并附加的行为与 aggrega push 共用,因此两个命令的签名方式完全相同。

环境变量

签名输入可以通过环境变量提供,它会覆盖 .aggrega-config.yaml 中的 signing: 块,但标志的优先级仍然更高:

  • AGGREGA_IDENTITY_TOKEN —— 无密钥 OIDC 身份令牌(--identity-token 对应的环境变量)。SIGSTORE_ID_TOKEN 作为 sigstore 生态互操作别名同样被接受,其优先级低于 AGGREGA_IDENTITY_TOKEN 和 GitHub Actions 环境提供的端点。该令牌永远不是配置字段。
  • AGGREGA_SIGNING_FULCIO_URL、AGGREGA_SIGNING_REKOR_URL、AGGREGA_SIGNING_TIMESTAMP_URL —— 无密钥服务的 URL。
  • AGGREGA_SIGNING_KEY_PATH —— 指向有密钥签名所用 PEM 文件的路径(绝不是密钥内容本身)。

aggrega sign 会针对制品的镜像仓库主机解析签名配置和这些变量,方式与 aggrega push 相同。优先级为:标志 > 环境变量 > 配置 > 默认值。完整列表请参阅 environment-variables.md。

通过上述某个变量,或通过 --fulcio-url、--rekor-url 或 --timestamp-url 提供的 URL 会按原样采用。配置文件会在这两者叠加应用到它之上之前接受检查,因此其值所须遵守的 https 格式不适用于它们;格式错误的 URL 只有在签名过程联系该服务时才会失败。

另请参阅

  • ./aggrega-auth.md —— 为一批无密钥签名一次性获取 OIDC 身份令牌。
  • ./aggrega-push.md —— 发布,可选择在推送时签名(先签名后推送)。
  • ./aggrega-pull.md —— 消费端,依据各 registry 的信任策略验证签名。
  • ./aggrega-serve.md —— 守护进程通过 aggrega/signArtifacts 提供同样的批量签名,从请求或环境中解析身份,并直接拒绝 而不是提示;该处的请求不指定密钥,因此有密钥签名读取工作区自身的 signing: 块。
  • ./aggrega-mcp.md —— 以 sign-artifacts 工具提供同样的能力,助手 可以调用该工具,且它接受 key_path。在允许使用之前,请先阅读该页面 关于允许它的说明。

概要

aggrega sign <reference>... [flags]

说明

Sign amends already-published artifacts by attaching a signature to each as an OCI referrer. It does not re-push, re-tag, or otherwise mutate the published bytes — the artifacts are immutable; each signature is a sibling manifest pointing back at its artifact. With --key signatures are produced offline from a held ECDSA P-256 key; without --key the keyless flow is used, which requires a live identity provider, Fulcio, and Rekor. Multiple references are signed in one invocation: the keyless identity is acquired once and reused across every artifact, and a fresh short-lived certificate is issued per artifact. Every reference in one invocation is signed with one credential: where the configuration names a held key (signing.key_path) for one reference's registry and none for another's, or two different keys, nothing is signed and the command says to run one invocation per credential; --key applies its key to every reference. A reference that already carries a signature its registry's trust policy verifies is reported as already signed, naming who signed it and when, and nothing is attached to it; a registry whose policy pins no public key or trusted identity gives nothing to judge a signature against, so a reference there is signed. Every other signable reference is signed; failures are collected and reported at the end, and the command exits non-zero if any reference failed — including one whose existing signatures could not be read, which is not signed. With --jobs N up to N references are signed at once; each is still signed exactly as it would be alone — when keyless, with its own certificate and its own transparency-log entry — and the output lists the references in the order they were given. The default, 1, signs one reference after another, because keyless signing reaches the public certificate authority and transparency log by default, and those limit how many requests they accept.

标志

标志默认值描述
--fulcio-url—用于无密钥签名的 Fulcio 证书颁发机构 URL。省略时使用公共 Fulcio 实例。
--identity-token—用于无密钥签名的 OIDC 身份令牌。在交互式终端中(通过浏览器流程获取令牌)和在 GitHub Actions 上(自动签发工作流 OIDC 令牌)为可选;在其他非交互式/CI 场景中必须提供,也可以改为导出为 AGGREGA_IDENTITY_TOKEN 或 SIGSTORE_ID_TOKEN。
--jobs1同时签名的引用数量。每个引用仍会完全像单独签名时那样被签名,输出保持引用给出的顺序。至少为 1。
--key—用于离线密钥签名的已持有 ECDSA P-256 私钥 PEM 文件路径。省略时使用无密钥签名。
--rekor-url—用于无密钥签名的 Rekor 透明日志 URL。省略时使用公共 Rekor 实例。
--timestamp-url—用于无密钥签名的可选 RFC3161 时间戳颁发机构 URL。