Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

aggrega sign

aggrega sign signiert ein oder mehrere bereits veröffentlichte Katalogartefakte und hängt jede Signatur als OCI-Referrer an. Es ist das Gegenstück nach der Veröffentlichung zu aggrega push --sign: Verwenden Sie es, um ein unsigniert veröffentlichtes Artefakt zu signieren oder einen ganzen Stapel von Artefakten in einem Aufruf zu signieren. Es fügt einem Artefakt, das bereits eine Signatur trägt, die die Vertrauensrichtlinie seiner Registry verifiziert, keine zweite Signatur hinzu.

Funktionsweise

aggrega sign löst den Digest auf, den die Registry für jede <reference> bereits hält, signiert diesen Digest und hängt das Signatur-Bundle als Referrer an. Es führt nie einen erneuten Push durch, vergibt keine neuen Tags und verändert die veröffentlichten Bytes auch sonst nicht — das Artefakt ist unveränderlich, und die Signatur ist ein Geschwister-Manifest, das auf es zurückverweist. So kann ein Artefakt nachträglich ohne Versionserhöhung signiert werden.

Vor dem Signieren liest es die Signaturen, die die Referenz bereits trägt, und beurteilt sie anhand der Vertrauensrichtlinie, die dieser Workspace für die Registry der Referenz hält — der Richtlinie, gegen die aggrega pull verifiziert. Wo eine verifiziert wird, gleich wer sie signiert hat, ist die Referenz bereits signiert: Der Befehl gibt Already signed: mit der Referenz, ihrem Digest, der signierenden Identität und, wo das Transparenzlog die Signatur verzeichnet hat, dem Zeitpunkt aus — bei mehreren dem der frühesten solchen Signatur —, hängt nichts an und zählt die Referenz als signiert. Ein Leser, der Keyless-Signaturen verifiziert, datiert eine Version nach der frühesten davon, die verifiziert wird, und nennt den Unterzeichner dieser Signatur, wie aggrega registry update beschreibt, sodass eine weitere Signatur einen Referrer und einen Eintrag im Transparenzlog hinzufügen und nichts an dem ändern würde, was ein solcher Leser aus der Version entnimmt.

Eine Registry, deren Richtlinie keinen öffentlichen Schlüssel und keine vertrauenswürdige Identität festlegt, bietet nichts, woran eine Signatur zu beurteilen wäre, sodass eine Referenz dort signiert wird, was auch immer sie bereits trägt. Eine Referenz, die nur Signaturen trägt, die die Richtlinie nicht zulässt, wird signiert, da keine davon für einen Leser zählt, der unter dieser Richtlinie verifiziert.

Die Signatur ist ein Sigstore-Bundle (cosign-kompatibel), dasselbe Format, das aggrega push --sign anhängt und aggrega pull verifiziert. Der Referrer benennt das Bundle signature.json, sodass ein generischer OCI-Client, der den Referrer über seinen Digest abruft, das Bundle in diese Datei schreibt.

Stapelsignierung

Übergeben Sie mehrere Referenzen, um sie in einem Aufruf zu signieren:

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

Die Keyless-Signierung löst die Identität einmal für den ganzen Stapel auf — eine interaktive Authentifizierung oder auf GitHub Actions der ambiente OIDC-Endpunkt des Runners — und verwendet sie für jedes Artefakt wieder, wobei pro Artefakt ein neues kurzlebiges Fulcio-Zertifikat ausgestellt wird. Ein interaktiv beschafftes oder bereitgestelltes Token wird für jede Signatur wiederverwendet; der ambiente Endpunkt erzeugt pro Signatur ein neues Token. Referenzen können auf verschiedene Registrys zielen: Jede wird mit dieser einen Identität gegen die Fulcio- und Rekor-Endpunkte signiert, die für ihre eigene Registry konfiguriert sind. Der schlüsselbasierte Weg (--key) signiert den Stapel ganz ohne Authentifizierung.

Das Signieren folgt dem Prinzip Fortfahren und Melden: Jede signierbare Referenz wird signiert, eine Referenz, deren Auflösen, Signieren oder Anhängen fehlschlägt, wird verzeichnet, und der Stapel geht zur nächsten Referenz über, statt beim ersten Fehler abzubrechen. Eine Referenz, die bereits eine verifizierte Signatur trägt, wird als bereits signiert gemeldet und zählt als signiert. Eine Referenz, deren vorhandene Signaturen nicht gelesen werden können — die Registry schließt die Auflistung nicht ab, oder eine Signatur kann nicht abgerufen oder beurteilt werden, während keine verifiziert wird —, wird als fehlgeschlagen verzeichnet und nicht signiert: Eine unbeantwortete Frage wird nie als unsigniertes Artefakt gelesen. Wenn nach dem Stapel eine Referenz fehlgeschlagen ist, wird eine Zusammenfassung der fehlgeschlagenen Referenzen auf stderr ausgegeben, und der Befehl endet mit einem Exit-Code ungleich null. Erfolgreiche Referenzen sind unabhängig von den Fehlschlägen anderer signiert.

Mehrere Referenzen gleichzeitig signieren

Standardmäßig signiert der Stapel eine Referenz nach der anderen. --jobs N signiert bis zu N Referenzen gleichzeitig und nie mehr als N. Jede wird weiterhin genau so signiert, wie sie es allein würde: Ihr veröffentlichter Digest wird aufgelöst, sie wird unverändert gelassen, wenn sie bereits eine verifizierte Signatur trägt, und andernfalls erhält sie eine eigene Signatur — keyless, mit eigenem flüchtigem Schlüssel, eigenem kurzlebigem Zertifikat und eigenem Eintrag im Transparenzlog. Die Identität wird weiterhin einmal für den ganzen Stapel aufgelöst, bevor irgendeine Referenz gelesen wird. Ein Wert unter 1 wird abgelehnt, und nichts wird signiert.

In welcher Reihenfolge die Referenzen auch fertig werden, die Ausgabe behält die Reihenfolge bei, in der sie angegeben wurden: Die Zeilen jeder Referenz werden vollständig ausgegeben, sobald jede vor ihr genannte Referenz fertig ist, sodass sich die Zeilen zweier Referenzen nie vermischen, und auch die Zusammenfassung der fehlgeschlagenen Referenzen listet sie in dieser Reihenfolge. Eine Folge davon, jede Referenz wie allein zu signieren: Ein Stapel, der dasselbe Artefakt zweimal nennt, erhält zwei Signaturen, wenn beide gleichzeitig signiert werden, weil keine die Signatur der anderen sieht, während sie erstellt wird, wohingegen bei Signierung nacheinander die zweite die der ersten findet und, wo die Vertrauensrichtlinie ihrer Registry sie verifiziert, nichts anhängt.

Der Standardwert ist 1, weil die Keyless-Signierung die öffentliche Zertifizierungsstelle und das öffentliche Transparenzlog erreicht, sofern Ihre Konfiguration keine anderen nennt, und diese Dienste begrenzen, wie viele Anfragen sie annehmen.

Eine Anmeldeinformation pro Stapel

Jede Referenz in einem Aufruf wird mit derselben Anmeldeinformation signiert: einem einzigen gehaltenen Schlüssel oder einer einzigen Keyless-Identität. Welche eine Referenz benötigt, entscheidet die Konfiguration für ihre Registry — ein signing.key_path, der für diese Registry gilt, wählt den Schlüssel, den er nennt, und wo keiner gilt, wird die Referenz keyless signiert. Wenn die Referenzen unterschiedliche Anmeldeinformationen bräuchten — die Konfiguration nennt einen Schlüssel für eine Registry und keinen für eine andere, oder zwei verschiedene Schlüssel —, signiert der Befehl nichts und nennt die Registrys auf jeder Seite. Er tut dies, bevor eine Identität angefordert und bevor eine Registry gelesen wird, sodass nichts angehängt und niemand für einen Lauf zur Eingabe aufgefordert wird, der nicht stattfindet.

Führen Sie stattdessen einen Aufruf pro Anmeldeinformation aus: einen, der die Referenzen auf den mit einem Schlüssel signierten Registrys nennt, einen anderen, der den Rest nennt. Ein mit --key übergebener Schlüssel gilt für jede genannte Referenz, unabhängig davon, was die Konfiguration für jede Registry sagt, sodass ein Aufruf mit --key deswegen nie abgelehnt wird.

Der Stapel wird abgelehnt, statt mit der Anmeldeinformation signiert zu werden, die eine seiner Referenzen gerade benötigt, weil eine Signatur von niemandem zurückgerufen werden kann, der sie abgerufen hat. Anders als die oben beschriebenen Fehlschläge pro Referenz ist dies die Ablehnung des Stapels und nicht die einer Referenz: Keine Referenz wird signiert. Wo eine Registry im Stapel Signaturen verlangt, nennt die Meldung sie, sodass sich die Ablehnung als eine über das Kombinieren der Referenzen liest und nicht als Aussage, dass sie nicht signiert werden können. Die Meldung und das, was jeder ihrer Teile nennt, steht in References signed together need different signing credentials (Gemeinsam signierte Referenzen benötigen unterschiedliche Signier-Anmeldeinformationen).

Ablauf des Identitätstokens mitten im Stapel

Ein langer Stapel kann ein kurzlebiges Identitätstoken überdauern. Auf GitHub Actions ist das kein Problem: Der ambiente Endpunkt erzeugt für jede Signatur ein neues Token, sodass ein Stapel seine Identität nie überdauert. Bei einem interaktiv beschafften oder vom Betreiber bereitgestellten Token (--identity-token, AGGREGA_IDENTITY_TOKEN oder SIGSTORE_ID_TOKEN) dient ein Token dem ganzen Stapel; läuft es mitten im Stapel ab, wird die betroffene Referenz nach dem Prinzip Fortfahren und Melden verzeichnet, und der Stapel läuft weiter. Führen Sie den Befehl erneut aus, um die gemeldeten Referenzen zu signieren — oder beschaffen Sie für einen langen geskripteten Stapel vorab ein neues Token.

Beschaffen Sie für geskriptete Stapel das Token einmal vorab und exportieren Sie es, sodass jede Referenz ohne Umweg über den Browser signiert wird:

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

Siehe ./aggrega-auth.md zu aggrega auth token.

Wenn ein Schritt vorübergehend fehlschlägt

Jede Referenz wird in drei Schritten signiert: Ihr veröffentlichter Digest wird aufgelöst, der Digest wird signiert, und die Signatur wird angehängt. Zwei davon werden wiederholt, wenn sie auf eine Weise fehlschlagen, bei der ein späterer Versuch gelingen kann:

  • Der Signieraufruf — bei jedem Fehler, bei dem ein Registry-Schreibvorgang wiederholt wird, und wenn die Keyless-Zertifizierungsstelle meldet, dass sie das Identitätstoken nicht verarbeiten konnte.
  • Das Anhängen, das das Signatur-Bundle und das Referrer-Manifest in die Registry schreibt — bei einem Serverfehler, einer Zeitüberschreitung oder einer zurückgesetzten Verbindung; aggrega push listet diese Fehler auf. Jeder Versuch ist ein neuer Upload derselben Bytes und kein erneutes Senden der fehlgeschlagenen Anfrage, und ein wiederholtes Anhängen hinterlässt eine Signatur, nicht zwei.

Jeder wird höchstens dreimal versucht, im Abstand von einer halben Sekunde und dann einer Sekunde. Das Auflösen des Digests ist ein Lesevorgang und wird nicht wiederholt. Eine Registry, die um Verlangsamung bittet, ist ein anderer Fall: Jede Anfrage an sie, einschließlich der Auflösung des Digests und des Anhängens, wartet so lange, wie sie verlangt, wie Eine Registry, die um Verlangsamung bittet beschreibt.

Ein Keyless-Signieraufruf fragt bis zu drei Dienste an — die Zertifizierungsstelle nach einem Zertifikat, das Transparenzlog nach einem Eintrag und, wo eine konfiguriert ist, die Zeitstempelstelle nach einem Zeitstempel —, und jede Anfrage wird innerhalb des Aufrufs für sich wiederholt. Eine Anfrage, die einer von ihnen mit 429 Too Many Requests oder einem Serverfehler beantwortet (beim Transparenzlog jedem außer 501 Not Implemented), wird erneut an diesen Dienst gesendet, sodass sie höchstens dreimal versucht wird, im Abstand von einer Sekunde und dann zwei Sekunden; nur diese Anfrage wird wiederholt, sodass ein erneut angeforderter Eintrag im Transparenzlog kein zweites Zertifikat anfordert. Das Transparenzlog wird auch erneut angefragt, wenn die Verbindung zu ihm fehlschlägt, und ein Retry-After, das es mit einem 429 oder einem 503 sendet, wird so lange abgewartet, wie es verlangt. Eine Antwort wegen Ratenbegrenzung oder Serverfehler, die nach diesen Versuchen weiterhin zurückkommt, lässt den Signieraufruf fehlschlagen, der dann nicht als Ganzes wiederholt wird.

Ein Schritt, der nach seinem letzten Versuch weiterhin fehlschlägt, wird für diese Referenz nach dem Prinzip Fortfahren und Melden mit seinem Fehler verzeichnet, und der Stapel geht weiter — ein fehlgeschlagenes Anhängen wird als die Signatur gemeldet, die nicht angehängt werden konnte; jeder andere Fehler wird sofort verzeichnet.

Signiermodi

  • Keyless (Standard) — ein flüchtiger Schlüssel, der durch ein kurzlebiges Fulcio-Zertifikat an eine OIDC-Identität gebunden ist und im Transparenzlog Rekor verzeichnet wird. Fulcio und Rekor verwenden standardmäßig die öffentlichen Sigstore-Instanzen (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). Der vertrauenswürdige Keyless-Zeitstempel stammt aus der Aufnahme in das Transparenzlog von Rekor; eine separate RFC3161-Zeitstempelstelle ist optional — geben Sie --timestamp-url mit einem vollständigen Endpunkt an, um eine zu aktivieren. An einem interaktiven Terminal benötigt die Keyless-Signierung keine Flags: Die CLI öffnet einen Browser, um ein kurzlebiges OIDC-Identitätstoken zu beschaffen. Auf GitHub Actions benötigt sie ebenfalls keine: Die CLI erzeugt das OIDC-Token des Workflows automatisch über den ambienten Endpunkt des Runners. Für andere nicht interaktive / CI-Nutzung exportieren Sie AGGREGA_IDENTITY_TOKEN (oder SIGSTORE_ID_TOKEN) oder übergeben --identity-token; ohne bereitgestelltes Token, ohne ambienten Endpunkt und ohne Terminal wird der Befehl abgelehnt.
  • Keyed (--key) — ein offline gehaltener ECDSA-P-256-Schlüssel (cosign-kompatibles PEM). Es wird weder ein Identitätsanbieter noch eine Zertifizierungsstelle noch ein Transparenzlog kontaktiert; die Registry wird weiterhin kontaktiert, um jeden Digest aufzulösen und seine Signatur anzuhängen.

Die Keyless-URLs und der Schlüsselpfad können auch aus dem Block signing: von .aggrega-config.yaml stammen (global und pro Registry); ein Flag überschreibt die Konfiguration, und die Konfiguration überschreibt den öffentlichen Standard. In dieser Datei wird jede URL als absolute https-URL geschrieben — https://, ein Host und optional ein Port und ein Pfad, etwa https://fulcio.sigstore.dev —, und ein Wert in jeder anderen Form, einer ohne Schema oder einer, der mit http:// beginnt, wird beim Laden der Datei unter Nennung der Datei und des Schlüssels abgelehnt. Das OIDC-Identitätstoken ist nie ein Konfigurationsfeld, und der private Schlüssel steht nie inline — nur ein Pfad dorthin.

Die Konstruktion und das Verhalten beim Signieren und Anhängen werden mit aggrega push geteilt, sodass beide Verben identisch signieren.

Umgebungsvariablen

Die Signiereingaben können über die Umgebung bereitgestellt werden und überschreiben dann den Block signing: von .aggrega-config.yaml, während ein Flag weiterhin Vorrang hat:

  • AGGREGA_IDENTITY_TOKEN — das OIDC-Identitätstoken für schlüsselloses Signieren (das Umgebungs-Gegenstück zu --identity-token). SIGSTORE_ID_TOKEN wird als Interop-Alias des Sigstore-Ökosystems berücksichtigt, mit niedrigerem Rang als AGGREGA_IDENTITY_TOKEN und dem Umgebungs-Endpunkt von GitHub Actions. Das Token ist nie ein Konfigurationsfeld.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — die URLs der schlüssellosen Dienste.
  • AGGREGA_SIGNING_KEY_PATH — ein Pfadverweis auf ein PEM mit dem Schlüssel für Keyed-Signieren (nie Schlüsselmaterial).

aggrega sign löst die Signierkonfiguration und diese Variablen für den Registry-Host des Artefakts auf, genauso wie aggrega push. Die Rangfolge ist Flag > Umgebung > Konfiguration > Standard. Siehe environment-variables.md für die vollständige Liste.

Eine URL, die über eine dieser Variablen oder über --fulcio-url, --rekor-url oder --timestamp-url bereitgestellt wird, wird so übernommen, wie sie geschrieben ist. Die Konfigurationsdatei wird geprüft, bevor eines davon darüber angewendet wird, sodass die https-Form, an die ihre Werte gebunden sind, diese nicht erreicht, und eine fehlerhafte schlägt erst fehl, wenn das Signieren diesen Dienst kontaktiert.

Siehe auch

  • ./aggrega-auth.md — ein OIDC-Identitätstoken einmal für einen Stapel von Keyless-Signaturen beschaffen.
  • ./aggrega-push.md — veröffentlichen, optional mit Signierung beim Push (Signieren vor dem Push).
  • ./aggrega-pull.md — die konsumierende Seite, die Signaturen gegen die Vertrauensrichtlinie pro Registry verifiziert.
  • ./aggrega-serve.md — der Daemon bietet denselben Stapel unter aggrega/signArtifacts, löst seine Identität aus der Anfrage oder der Umgebung auf und lehnt ab, statt nachzufragen; eine Anfrage dort nennt keinen Schlüssel, sodass die schlüsselbasierte Signierung den eigenen signing:-Block des Workspace liest.
  • ./aggrega-mcp.md — dieselbe Fähigkeit als Werkzeug sign-artifacts, das ein Assistent aufrufen kann und das key_path akzeptiert. Lesen Sie, was diese Seite über das Zulassen sagt, bevor Sie es zulassen.

Übersicht

aggrega sign <reference>... [flags]

Beschreibung

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.

Flags

FlagStandardBeschreibung
--fulcio-url—URL der Fulcio-Zertifizierungsstelle für schlüssellose Signierung. Wenn weggelassen, wird die öffentliche Fulcio-Instanz verwendet.
--identity-token—OIDC-Identitätstoken für schlüssellose Signierung. Optional an einem interaktiven Terminal (ein Browser-Ablauf beschafft eines) und in GitHub Actions (das OIDC-Token des Workflows wird automatisch ausgestellt); erforderlich für andere nicht interaktive Verwendung/CI, wo es stattdessen als AGGREGA_IDENTITY_TOKEN oder SIGSTORE_ID_TOKEN exportiert werden kann.
--jobs1Anzahl der gleichzeitig signierten Referenzen. Jede wird weiterhin genau so signiert, wie sie es allein würde, und die Ausgabe behält die Reihenfolge bei, in der die Referenzen angegeben wurden. Mindestens 1.
--key—Pfad zu einer vorliegenden privaten ECDSA-P-256-Schlüssel-PEM für die Offline-Signierung mit Schlüssel. Wenn weggelassen, wird schlüssellose Signierung verwendet.
--rekor-url—URL des Rekor-Transparenzlogs für schlüssellose Signierung. Wenn weggelassen, wird die öffentliche Rekor-Instanz verwendet.
--timestamp-url—Optionale URL einer RFC3161-Zeitstempelstelle für schlüssellose Signierung.