aggrega sign
aggrega sign は、公開済みのカタログアーティファクトを 1 つ以上署名し、各署名を OCI リファラーとして添付します。これは aggrega push --sign の公開後版にあたります。署名なしで公開されたアーティファクトに署名する場合や、多数のアーティファクトを 1 回の実行でまとめて署名する場合に使用します。レジストリのトラストポリシーで検証される署名をすでに持つアーティファクトには、2 つ目の署名を追加しません。
動作
aggrega sign は、各 <reference> についてレジストリがすでに保持しているダイジェストを解決し、そのダイジェストに署名して、署名バンドルをリファラーとして添付します。公開済みのバイトを再プッシュしたり、再タグ付けしたり、その他の方法で変更したりすることはありません。アーティファクトはイミュータブルであり、署名はそれを指し返す兄弟マニフェストです。そのため、アーティファクトはバージョンを上げることなく事後に署名できます。
署名の前に、コマンドはリファレンスがすでに持っている署名を読み取り、そのリファレンスのレジストリについてこのワークスペースが保持するトラストポリシー(aggrega pull が検証に用いるポリシー)に照らして判定します。いずれかが検証に成功すれば、署名者が誰であっても、そのリファレンスはすでに署名済みです。コマンドは Already signed: とともに、リファレンス、そのダイジェスト、署名のアイデンティティ、そして透明性ログが署名を記録している場合はその日時(複数ある場合はそのうち最も早い署名の日時)を出力し、何も添付せず、そのリファレンスを署名済みとして数えます。キーレス署名を検証する読み手は、aggrega registry update で説明されているとおり、検証に成功するキーレス署名のうち最も早いものでバージョンの日付を定め、その署名の署名者を示します。そのため、署名を追加してもリファラーと透明性ログのエントリが増えるだけで、そのような読み手がバージョンから得る情報は何も変わりません。
ポリシーが公開鍵も信頼済みアイデンティティも固定していないレジストリでは、署名を判定する基準がないため、そこにあるリファレンスは既存の署名にかかわらず署名されます。ポリシーが認めない署名しか持たないリファレンスは署名されます。そのポリシーのもとで検証する読み手にとって、それらの署名はどれも有効とみなされないためです。
署名は Sigstore(cosign 互換)のバンドルで、aggrega push --sign が添付し aggrega pull が検証するものと同じ形式です。リファラーはバンドルに signature.json という名前を付けるため、汎用の OCI クライアントがダイジェストでリファラーをプルすると、バンドルはそのファイルに書き出されます。
バッチ署名
複数の参照を渡すと、1 回の呼び出しでそれらに署名します。
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キーレス署名は、バッチ全体に対してアイデンティティを一度だけ解決し(1 回の対話的な認証、または GitHub Actions ではランナーのアンビエント OIDC エンドポイント)、それをすべてのアーティファクトで再利用して、アーティファクトごとに新しい短期の Fulcio 証明書を発行します。対話的に取得したトークンや指定されたトークンはすべての署名で再利用されます。アンビエントエンドポイントは署名ごとに新しいトークンを発行します。参照はそれぞれ異なるレジストリを対象にできます。各参照は、その 1 つのアイデンティティで、その参照自身のレジストリに設定された Fulcio と Rekor のエンドポイントに対して署名されます。鍵を使う経路(--key)は、認証を一切行わずにバッチに署名します。
署名は継続して報告する方式です。署名可能なすべての参照に署名し、解決、署名、添付のいずれかに失敗した参照は記録され、最初の失敗で停止せずに次の参照へ進みます。検証に成功する署名をすでに持つ参照は、署名済みとして報告され、署名済みとして数えられます。既存の署名を読み取れない参照(レジストリが一覧を完了しない、または検証に成功する署名がないまま署名の取得や判定ができない)は失敗として記録され、署名されません。答えの得られない問いが、未署名のアーティファクトとして解釈されることはありません。バッチの終了後、失敗した参照があれば、失敗した参照を一覧にした要約が stderr に出力され、コマンドは 0 以外で終了します。成功した参照は、他の参照の失敗にかかわらず署名されます。
複数の参照を同時に署名する
デフォルトでは、バッチは参照を 1 つずつ順に署名します。--jobs N は最大 N 個の参照を同時に署名し、N を超えることはありません。各参照は単独で署名する場合とまったく同じように署名されます。公開済みのダイジェストが解決され、検証される署名をすでに持つ場合はそのまま残され、そうでなければ独自の署名が付与されます。キーレスの場合は、独自の一時鍵、独自の短期証明書、独自の透明性ログエントリが使われます。アイデンティティは引き続き、どの参照も読み取る前にバッチ全体で 1 回だけ解決されます。1 未満の値は拒否され、何も署名されません。
参照がどの順序で完了しても、出力は参照が渡された順序を保ちます。各参照の行は、それより前に指定されたすべての参照が完了した時点でまとめて出力されるため、2 つの参照の行が混ざることはなく、失敗した参照の要約もその順序で列挙されます。各参照を単独であるかのように署名することの結果の 1 つとして、同じアーティファクトを 2 回指定したバッチは、両方を同時に署名すると署名が 2 つ付きます。署名を作成している間、どちらも相手の署名を見ないためです。一方、1 つずつ順に署名すると、2 回目は 1 回目の署名を見つけ、レジストリのトラストポリシーでそれが検証される場合は何も添付しません。
デフォルトが 1 なのは、設定で別のものを指定しない限り、キーレス署名は公共の認証局と透明性ログにアクセスし、それらのサービスは受け付けるリクエスト数を制限しているためです。
バッチごとに 1 つの資格情報
1 回の呼び出しに含まれるすべての参照は、同じ資格情報で署名されます。つまり、保持する 1 つの鍵、または 1 つのキーレスアイデンティティです。参照がどちらを必要とするかは、そのレジストリの設定によって決まります。そのレジストリに適用される signing.key_path があればそれが指す鍵が選ばれ、適用されるものがなければその参照はキーレスで署名されます。参照ごとに異なる資格情報が必要になる場合(設定があるレジストリには鍵を指定し、別のレジストリには指定していない場合や、2 つの異なる鍵を指定している場合)、コマンドは何にも署名せず、それぞれの側のレジストリを示します。これはアイデンティティを求める前、かつレジストリを読み取る前に行われるため、実行されない処理のために何かが添付されたり、誰かに入力が求められたりすることはありません。
代わりに、資格情報ごとに 1 回ずつ呼び出してください。鍵で署名するレジストリ上の参照を指定する呼び出しと、残りを指定する呼び出しです。--key で渡した鍵は、各レジストリに対する設定にかかわらず、指定したすべての参照に適用されるため、--key を指定した呼び出しがこの理由で拒否されることはありません。
バッチは、いずれかの参照が必要とする資格情報で署名されるのではなく拒否されます。署名は、それを取得した相手から取り消せないためです。前述の参照ごとの失敗とは異なり、これは 1 つの参照ではなくバッチ全体の拒否であり、どの参照も署名されません。バッチ内のレジストリが署名を必須としている場合、メッセージはそのレジストリを示します。これにより、この拒否は参照を組み合わせたことに関するものであり、参照に署名できないという意味ではないと読み取れます。メッセージと、その各部分が示す内容については、References signed together need different signing credentials(まとめて署名する参照に異なる署名資格情報が必要です)を参照してください。
バッチ途中でのアイデンティティトークンの期限切れ
長いバッチは、短期のアイデンティティトークンの有効期間を超えることがあります。GitHub Actions ではこれは問題になりません。アンビエントエンドポイントが署名ごとに新しいトークンを発行するため、バッチがアイデンティティの有効期間を超えることはありません。対話的に取得したトークン、またはオペレーターが指定したトークン(--identity-token、AGGREGA_IDENTITY_TOKEN、または SIGSTORE_ID_TOKEN)では、1 つのトークンがバッチ全体で使われます。バッチの途中で期限切れになると、影響を受けた参照は継続して報告する方式に従って記録され、バッチは続行します。報告された参照に署名するにはコマンドを再実行してください。または、スクリプトによる長いバッチでは、事前に新しいトークンを取得してください。
スクリプトによるバッチでは、事前にトークンを一度取得してエクスポートしておくと、ブラウザーとのやり取りなしに各参照に署名できます。
export AGGREGA_IDENTITY_TOKEN=$(aggrega auth token)aggrega sign hub.example.com/component/core/api-server:1.0.0aggrega sign hub.example.com/component/core/worker:1.0.0aggrega auth token については ./aggrega-auth.md を参照してください。
ステップが一時的に失敗した場合
各参照は 3 つのステップで署名されます。公開されたダイジェストが解決され、そのダイジェストが署名され、署名が添付されます。このうち 2 つのステップは、後の試行で成功しうる形で失敗した場合に再試行されます。
- 署名呼び出し — レジストリへの書き込みが再試行される対象となるあらゆる失敗の場合、およびキーレスの認証局が ID トークンを処理できなかったと報告した場合に再試行されます。
- 添付。署名バンドルとリファラー Manifest をレジストリに書き込みます — サーバーエラー、タイムアウト、または接続のリセットの場合に再試行されます。これらの失敗は
aggrega pushに一覧があります。各試行は、失敗したリクエストの再送ではなく同じバイト列の新たなアップロードであり、添付を繰り返しても残る署名は 2 つではなく 1 つです。
それぞれ最大 3 回、0.5 秒、次に 1 秒の間隔を空けて試行されます。ダイジェストの解決は読み取りであり、再試行されません。速度を落とすよう求めるレジストリは別のケースです。ダイジェストの解決やアタッチを含め、そのレジストリへのすべてのリクエストは、速度を落とすよう求めるレジストリで説明するとおり、求められた時間だけ待機します。
キーレス署名の呼び出しは最大 3 つのサービスに問い合わせます。証明書を得るための認証局、エントリを得るための透明性ログ、そして設定されている場合はタイムスタンプを得るためのタイムスタンプ局です。各リクエストは呼び出しの内部で個別に再試行されます。これらのいずれかが 429 Too Many Requests またはサーバーエラー(透明性ログの場合は 501 Not Implemented 以外のすべて)で応答したリクエストはそのサービスに再送されるため、最大 3 回、1 秒、次に 2 秒の間隔で試行されます。繰り返されるのはそのリクエストだけなので、透明性ログのエントリを再度要求しても 2 つ目の証明書は要求されません。透明性ログへの接続が失敗した場合も再度問い合わせが行われ、429 または 503 とともに送られる Retry-After は、それが求める時間だけ待機されます。これらの試行の後もレート制限またはサーバーエラーの応答が返り続ける場合、署名の呼び出しは失敗し、その後呼び出し全体が再試行されることはありません。
最後の試行の後もなお失敗しているステップは、continue-and-report のもとでそのエラーとともにその参照に対して記録され、バッチは次に進みます。添付の失敗は添付できなかった署名として報告され、それ以外の失敗は即座に記録されます。
署名モード
- キーレス(デフォルト) — 短期間有効な Fulcio 証明書によって OIDC ID に結び付けられた一時的な鍵で、Rekor 透明性ログに記録されます。Fulcio と Rekor のデフォルトは公共の Sigstore インスタンス(
https://fulcio.sigstore.dev、https://rekor.sigstore.dev)です。キーレス方式の信頼できるタイムスタンプは Rekor の透明性ログへの記録から得られます。別途 RFC3161 タイムスタンプ局を使うことは任意で、有効にするには--timestamp-urlに完全なエンドポイントを指定します。対話型ターミナルでは、キーレス署名にフラグは不要です。CLI がブラウザを開き、短期間有効な OIDC ID トークンを取得します。GitHub Actions でもフラグは不要です。CLI がランナーの環境内エンドポイントからワークフローの OIDC トークンを自動的に発行します。その他の非対話型 / CI で使う場合は、AGGREGA_IDENTITY_TOKEN(またはSIGSTORE_ID_TOKEN)をエクスポートするか、--identity-tokenを渡します。トークンが指定されず、環境内エンドポイントもターミナルもない場合、コマンドは拒否されます。 - キー付き(
--key)— オフラインで保持する ECDSA P-256 鍵(cosign 互換の PEM)です。ID プロバイダー、認証局、透明性ログには接続しません。ただし、各ダイジェストを解決して署名を添付するために、レジストリには引き続き接続します。
キーレス方式の URL と鍵ありの鍵パスは、.aggrega-config.yaml の signing: ブロック(グローバルおよびレジストリごと)から指定することもできます。フラグは設定より優先され、設定は公共のデフォルトより優先されます。このファイルでは、各 URL を絶対 https URL として記述します。つまり https://、ホスト、および任意でポートとパスからなる形式で、たとえば https://fulcio.sigstore.dev のようになります。それ以外の形式の値(スキームのないものや http:// で始まるもの)は、ファイルの読み込み時にファイル名とキーを示して拒否されます。OIDC ID トークンが設定フィールドになることはなく、秘密鍵がインラインで記述されることもありません。指定できるのはそのパスのみです。
構築処理および署名と添付の動作は aggrega push と共通であるため、どちらのコマンドも同じように署名します。
環境変数
署名の入力は環境変数から指定することもできます。環境変数は .aggrega-config.yaml の signing: ブロックより優先されますが、フラグはそれよりもさらに優先されます。
AGGREGA_IDENTITY_TOKEN— キーレス方式の OIDC ID トークンです(--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 ID トークンを一度だけ取得します。
- ./aggrega-push.md — 公開します。必要に応じてプッシュ時に署名することもできます(プッシュ前の署名)。
- ./aggrega-pull.md — 利用する側です。レジストリごとの信頼ポリシーに照らして署名を検証します。
- ./aggrega-serve.md — デーモンは同じ一括処理を
aggrega/signArtifactsで実行します。ID はリクエストまたは環境から解決し、入力を求めずに 拒否します。このリクエストは鍵を指定しないため、鍵ありの署名ではワークスペース自身の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 ID トークンです。対話型ターミナル(ブラウザーフローでトークンを取得します)と GitHub Actions(ワークフローの OIDC トークンが自動的に発行されます)では任意です。それ以外の非対話型/CI での使用では必須で、代わりに AGGREGA_IDENTITY_TOKEN または SIGSTORE_ID_TOKEN としてエクスポートすることもできます。 |
--jobs | 1 | 同時に署名する参照の数。各参照は単独で署名する場合とまったく同じように署名され、出力は参照が渡された順序を保ちます。1 以上。 |
--key | — | オフラインの鍵付き署名に使用する、保持している ECDSA P-256 秘密鍵 PEM のパスです。省略した場合は、キーレス署名が使用されます。 |
--rekor-url | — | キーレス署名に使用する Rekor 透明性ログの URL です。省略した場合は、公共の Rekor インスタンスが使用されます。 |
--timestamp-url | — | キーレス署名に使用する、任意の RFC3161 タイムスタンプ局の URL です。 |