aggrega sign
aggrega sign podpisuje jeden lub więcej już opublikowanych artefaktów katalogu i dołącza każdy podpis jako OCI referrer. Jest odpowiednikiem aggrega push --sign stosowanym po publikacji: służy do podpisania artefaktu opublikowanego bez podpisu albo do podpisania całej partii artefaktów w jednym wywołaniu. Nie dodaje drugiego podpisu do artefaktu, który ma już podpis weryfikowany przez politykę zaufania jego rejestru.
Działanie
aggrega sign ustala skrót (digest), który rejestr już przechowuje dla każdego <reference>, podpisuje ten skrót i dołącza pakiet podpisu jako referrer. Nigdy nie wypycha ponownie, nie zmienia tagów ani w żaden inny sposób nie modyfikuje opublikowanych bajtów — artefakt jest niezmienny, a podpis jest siostrzanym manifestem wskazującym z powrotem na niego. Dzięki temu artefakt można podpisać po fakcie, bez podbijania wersji.
Przed podpisaniem polecenie odczytuje podpisy, które referencja już posiada, i ocenia je względem polityki zaufania, którą ten obszar roboczy przechowuje dla rejestru referencji — tej samej, względem której weryfikuje aggrega pull. Jeśli któryś z nich przechodzi weryfikację, niezależnie od tego, kto go złożył, referencja jest już podpisana: polecenie wypisuje Already signed: wraz z referencją, jej skrótem, tożsamością podpisującego oraz, jeśli dziennik przejrzystości zarejestrował podpis, czasem jego złożenia — najwcześniejszego takiego podpisu, jeśli jest ich kilka — niczego nie dołącza i liczy referencję jako podpisaną. Czytelnik weryfikujący podpisy bezkluczowe datuje wersję według najwcześniejszego z nich, który przechodzi weryfikację, i wskazuje podpisującego ten podpis, jak opisuje aggrega registry update, więc kolejny podpis dodałby referrer i wpis w dzienniku przejrzystości, nie zmieniając niczego, co taki czytelnik odczytuje z wersji.
Rejestr, którego polityka nie przypina żadnego klucza publicznego ani zaufanej tożsamości, nie daje niczego, względem czego można ocenić podpis, więc referencja w nim jest podpisywana niezależnie od tego, co już posiada. Referencja zawierająca wyłącznie podpisy, których polityka nie dopuszcza, jest podpisywana, ponieważ żaden z nich nie liczy się dla czytelnika weryfikującego zgodnie z tą polityką.
Podpis jest pakietem Sigstore (zgodnym z cosign), w tym samym formacie, który dołącza aggrega push --sign i weryfikuje aggrega pull. Referrer nadaje pakietowi nazwę signature.json, więc ogólny klient OCI pobierający referrer według jego skrótu zapisuje pakiet do tego pliku.
Podpisywanie wsadowe
Aby podpisać kilka referencji w jednym wywołaniu, należy przekazać je wszystkie:
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.0Podpisywanie bezkluczowe ustala tożsamość raz dla całej partii — jedno interaktywne uwierzytelnienie albo, w GitHub Actions, otoczeniowy punkt końcowy OIDC runnera — i używa jej ponownie dla każdego artefaktu, wystawiając dla każdego artefaktu nowy, krótkotrwały certyfikat Fulcio. Token uzyskany interaktywnie lub przekazany jest używany ponownie dla każdego podpisu; otoczeniowy punkt końcowy generuje nowy token dla każdego podpisu. Referencje mogą wskazywać różne rejestry: każda jest podpisywana tą jedną tożsamością względem punktów końcowych Fulcio i Rekor skonfigurowanych dla jej własnego rejestru. Ścieżka z kluczem (--key) podpisuje partię bez żadnego uwierzytelniania.
Podpisywanie działa w trybie kontynuuj i raportuj: każda referencja, którą można podpisać, zostaje podpisana, referencja, której nie udało się rozwiązać, podpisać lub dołączyć, zostaje odnotowana, a partia przechodzi do następnej referencji zamiast zatrzymać się na pierwszym błędzie. Referencja, która ma już weryfikowalny podpis, jest zgłaszana jako już podpisana i liczy się jako podpisana. Referencja, której istniejących podpisów nie da się odczytać — rejestr nie kończy listowania albo podpisu nie można pobrać ani ocenić, a żaden nie przechodzi weryfikacji — zostaje odnotowana jako nieudana i nie jest podpisywana: pytanie bez odpowiedzi nigdy nie jest traktowane jako niepodpisany artefakt. Po zakończeniu partii, jeśli którakolwiek referencja się nie powiodła, na stderr wypisywane jest podsumowanie z listą nieudanych referencji, a polecenie kończy się kodem różnym od zera. Referencje, które się powiodły, pozostają podpisane niezależnie od niepowodzeń innych.
Podpisywanie kilku odwołań naraz
Domyślnie partia podpisuje odwołania jedno po drugim. --jobs N podpisuje do N odwołań naraz i nigdy więcej niż N. Każde jest nadal podpisywane dokładnie tak, jak byłoby podpisane samodzielnie: rozwiązywany jest jego opublikowany digest, pozostaje bez zmian, jeśli ma już podpis, który przechodzi weryfikację, a w przeciwnym razie otrzymuje własny podpis — w trybie bezkluczowym z własnym efemerycznym kluczem, własnym krótkotrwałym certyfikatem i własnym wpisem w dzienniku przejrzystości. Tożsamość jest nadal rozwiązywana raz, dla całej partii, zanim zostanie odczytane jakiekolwiek odwołanie. Wartość mniejsza niż 1 jest odrzucana i nic nie zostaje podpisane.
Niezależnie od tego, w jakiej kolejności odwołania się zakończą, wynik zachowuje kolejność, w jakiej je podano: wiersze każdego odwołania są wypisywane w całości, gdy tylko zakończy się każde odwołanie wskazane przed nim, więc wiersze dwóch odwołań nigdy się nie przeplatają, a podsumowanie nieudanych odwołań również wymienia je w tej kolejności. Jedna konsekwencja podpisywania każdego odwołania tak, jakby było samo: partia, która dwukrotnie wskazuje ten sam artefakt, otrzymuje dwa podpisy, gdy oba są podpisywane naraz, ponieważ żaden nie widzi podpisu drugiego w trakcie jego tworzenia, natomiast przy podpisywaniu jedno po drugim drugie znajduje podpis pierwszego i, jeśli polityka zaufania jego rejestru go weryfikuje, niczego nie dołącza.
Wartością domyślną jest 1, ponieważ podpisywanie bezkluczowe łączy się z publicznym urzędem certyfikacji i dziennikiem przejrzystości, chyba że konfiguracja wskazuje inne, a te usługi ograniczają liczbę przyjmowanych żądań.
Jedno poświadczenie na partię
Każda referencja w jednym wywołaniu jest podpisywana tym samym poświadczeniem: jednym posiadanym kluczem albo jedną tożsamością bezkluczową. O tym, którego poświadczenia wymaga referencja, decyduje konfiguracja jej rejestru — signing.key_path mający zastosowanie do tego rejestru wybiera wskazany klucz, a gdy żaden nie ma zastosowania, referencja jest podpisywana bezkluczowo. Gdy referencje wymagałyby różnych poświadczeń — konfiguracja wskazuje klucz dla jednego rejestru, a dla innego żadnego, albo dwa różne klucze — polecenie niczego nie podpisuje i wymienia rejestry po każdej ze stron. Dzieje się to, zanim zostanie zażądana jakakolwiek tożsamość i zanim zostanie odczytany jakikolwiek rejestr, więc nic nie zostaje dołączone i nikt nie jest proszony o dane dla przebiegu, który nie zostanie wykonany.
Zamiast tego należy uruchomić jedno wywołanie na każde poświadczenie: jedno z referencjami z rejestrów podpisywanych kluczem, drugie z pozostałymi. Klucz przekazany przez --key dotyczy każdej wymienionej referencji, niezależnie od konfiguracji poszczególnych rejestrów, więc wywołanie z --key nigdy nie jest z tego powodu odrzucane.
Partia jest odrzucana, zamiast zostać podpisana poświadczeniem, którego wymaga którakolwiek z jej referencji, ponieważ podpisu nie można odwołać u nikogo, kto już go pobrał. W odróżnieniu od opisanych wyżej niepowodzeń poszczególnych referencji jest to odmowa dotycząca całej partii, a nie jednej referencji: żadna referencja nie zostaje podpisana. Jeśli rejestr w partii wymaga podpisów, komunikat go wymienia, tak aby odmowa była odczytywana jako dotycząca łączenia referencji, a nie jako stwierdzenie, że nie można ich podpisać. Komunikat i to, co wskazuje każda jego część, opisano w References signed together need different signing credentials (Referencje podpisywane razem wymagają różnych poświadczeń podpisu).
Wygaśnięcie tokenu tożsamości w trakcie partii
Długa partia może trwać dłużej niż krótkotrwały token tożsamości. W GitHub Actions nie stanowi to problemu: otoczeniowy punkt końcowy generuje nowy token dla każdego podpisu, więc partia nigdy nie przeżywa swojej tożsamości. W przypadku tokenu uzyskanego interaktywnie lub przekazanego przez operatora (--identity-token, AGGREGA_IDENTITY_TOKEN lub SIGSTORE_ID_TOKEN) jeden token obsługuje całą partię; jeśli wygaśnie w jej trakcie, dotknięta referencja zostaje odnotowana w trybie kontynuuj i raportuj, a partia jest kontynuowana. Aby podpisać zgłoszone referencje, należy ponownie uruchomić polecenie — albo, w przypadku długiej partii skryptowej, uzyskać nowy token z góry.
W partiach skryptowych należy uzyskać token raz z góry i go wyeksportować, dzięki czemu każda referencja jest podpisywana bez przechodzenia przez przeglądarkę:
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.0Opis aggrega auth token znajduje się w ./aggrega-auth.md.
Gdy krok kończy się przejściowym błędem
Każda referencja jest podpisywana w trzech krokach: rozwiązywany jest jej opublikowany digest, digest jest podpisywany, a podpis jest dołączany. Dwa z tych kroków są ponawiane, gdy kończą się błędem, po którym kolejna próba może się powieść:
- Wywołanie podpisujące — przy każdym błędzie, po którym ponawiany jest zapis do rejestru, oraz gdy urząd certyfikacji trybu bezkluczowego zgłasza, że nie mógł przetworzyć tokenu tożsamości.
- Dołączenie, które zapisuje w rejestrze pakiet podpisu i manifest referrera — przy błędzie serwera, przekroczeniu limitu czasu lub zerwanym połączeniu; te błędy wymienia
aggrega push. Każda próba jest nowym przesłaniem tych samych bajtów, a nie ponowieniem żądania, które się nie powiodło, a powtórzone dołączenie pozostawia jeden podpis, nie dwa.
Każdy z nich jest próbowany najwyżej trzy razy, w odstępach pół sekundy, a następnie sekundy. Rozwiązanie digestu jest odczytem i nie jest ponawiane. Rejestr, który prosi o zwolnienie, to inny przypadek: każde żądanie do niego, łącznie z rozwiązaniem digestu i dołączeniem podpisu, czeka tak długo, jak rejestr prosi, jak opisuje Rejestr, który prosi o zwolnienie.
Bezkluczowe wywołanie podpisywania odpytuje do trzech usług — urząd certyfikacji o certyfikat, dziennik przejrzystości o wpis oraz, jeśli jest skonfigurowany, urząd znaczników czasu o znacznik czasu — a każde żądanie jest ponawiane osobno w ramach wywołania. Żądanie, na które jedna z nich odpowie 429 Too Many Requests lub błędem serwera (w przypadku dziennika przejrzystości dowolnym poza 501 Not Implemented), jest wysyłane do tej usługi ponownie, więc jest próbowane najwyżej trzy razy, w odstępach sekundy, a następnie dwóch sekund; powtarzane jest tylko to żądanie, więc ponowne żądanie wpisu w dzienniku przejrzystości nie żąda drugiego certyfikatu. Dziennik przejrzystości jest odpytywany ponownie także wtedy, gdy połączenie z nim się nie powiedzie, a na Retry-After wysłane przez niego wraz z 429 lub 503 czeka się tak długo, jak tego żąda. Odpowiedź o ograniczeniu liczby żądań lub błędzie serwera, która nadal wraca po tych próbach, kończy wywołanie podpisywania błędem, a całe wywołanie nie jest wtedy ponawiane.
Krok, który nadal kończy się błędem po ostatniej próbie, jest odnotowywany dla danej referencji w trybie continue-and-report wraz z błędem, a partia przechodzi dalej — nieudane dołączenie jest zgłaszane jako podpis, którego nie udało się dołączyć; każdy inny błąd jest odnotowywany od razu.
Tryby podpisywania
- Bezkluczowy (domyślny) — efemeryczny klucz powiązany z tożsamością OIDC przez krótkotrwały certyfikat Fulcio, zapisany w dzienniku przejrzystości Rekor. Fulcio i Rekor domyślnie wskazują publiczne instancje Sigstore (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). Zaufany znacznik czasu w trybie bezkluczowym pochodzi z włączenia wpisu do dziennika przejrzystości Rekor; osobny urząd znaczników czasu RFC3161 jest opcjonalny — aby go włączyć, należy podać--timestamp-urlz pełnym punktem końcowym. W terminalu interaktywnym podpisywanie bezkluczowe nie wymaga żadnych flag: CLI otwiera przeglądarkę, aby uzyskać krótkotrwały token tożsamości OIDC. W GitHub Actions również nie wymaga żadnych flag: CLI automatycznie generuje token OIDC przepływu pracy z punktu końcowego dostępnego w środowisku runnera. W innych zastosowaniach nieinteraktywnych / CI należy wyeksportowaćAGGREGA_IDENTITY_TOKEN(lubSIGSTORE_ID_TOKEN) albo przekazać--identity-token; bez podanego tokenu, bez punktu końcowego w środowisku i bez terminala polecenie zostaje odrzucone. - Kluczowy (
--key) — klucz ECDSA P-256 przechowywany offline (PEM zgodny z cosign). Nie nawiązuje się połączenia z żadnym dostawcą tożsamości, urzędem certyfikacji ani dziennikiem przejrzystości; z rejestrem nadal tak, aby rozwiązać każdy digest i dołączyć jego podpis.
Adresy URL trybu bezkluczowego i ścieżka klucza w trybie z kluczem mogą również pochodzić z bloku signing: pliku .aggrega-config.yaml (globalnie i dla poszczególnych rejestrów); flaga zastępuje konfigurację, a konfiguracja zastępuje publiczne wartości domyślne. W tym pliku każdy adres URL zapisuje się jako bezwzględny adres https — https://, host oraz opcjonalnie port i ścieżka, np. https://fulcio.sigstore.dev — a wartość w innej postaci, bez schematu lub zaczynająca się od http://, zostaje odrzucona podczas wczytywania pliku, z podaniem nazwy pliku i klucza. Token tożsamości OIDC nigdy nie jest polem konfiguracji, a klucz prywatny nigdy nie jest podawany bezpośrednio — tylko ścieżka do niego.
Sposób konstrukcji oraz działanie podpisywania i dołączania są wspólne z aggrega push, więc oba polecenia podpisują identycznie.
Zmienne środowiskowe
Dane wejściowe podpisywania można przekazać przez środowisko; zastępują one wtedy blok signing: pliku .aggrega-config.yaml, a flaga nadal ma pierwszeństwo:
AGGREGA_IDENTITY_TOKEN— bezkluczowy token tożsamości OIDC (odpowiednik--identity-tokenw zmiennych środowiskowych).SIGSTORE_ID_TOKENjest uwzględniany jako alias zapewniający interoperacyjność z ekosystemem sigstore, o priorytecie niższym niżAGGREGA_IDENTITY_TOKENi punkt końcowy dostępny w środowisku GitHub Actions. Token nigdy nie jest polem konfiguracji.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL— adresy URL usług podpisywania bezkluczowego.AGGREGA_SIGNING_KEY_PATH— ścieżka wskazująca plik PEM z kluczem do podpisywania kluczem (nigdy sam materiał klucza).
aggrega sign rozwiązuje konfigurację podpisywania i te zmienne dla hosta rejestru artefaktu w taki sam sposób jak aggrega push. Kolejność pierwszeństwa: flaga > środowisko > konfiguracja > wartość domyślna. Pełną listę zawiera environment-variables.md.
Adres URL przekazany przez jedną z tych zmiennych albo przez --fulcio-url, --rekor-url lub --timestamp-url jest przyjmowany w postaci, w jakiej został zapisany. Plik konfiguracyjny jest sprawdzany, zanim którakolwiek z tych wartości zostanie na niego nałożona, więc wymóg postaci https, któremu podlegają jego wartości, ich nie obejmuje, a błędnie sformułowany adres powoduje błąd dopiero wtedy, gdy podpisywanie łączy się z daną usługą.
Zobacz także
- ./aggrega-auth.md — jednorazowe uzyskanie tokenu tożsamości OIDC dla partii podpisów bezkluczowych.
- ./aggrega-push.md — publikowanie, opcjonalnie z podpisywaniem w momencie wypychania (podpisanie przed wypchnięciem).
- ./aggrega-pull.md — strona pobierająca, która weryfikuje podpisy względem zasad zaufania określonych dla każdego rejestru.
- ./aggrega-serve.md — demon obsługuje tę samą partię pod
aggrega/signArtifacts, ustalając tożsamość na podstawie żądania lub zmiennych środowiskowych i odmawiając zamiast wyświetlać monit; żądanie nie wskazuje tam żadnego klucza, więc podpisywanie kluczem odczytuje własny bloksigning:obszaru roboczego. - ./aggrega-mcp.md — ta sama funkcja w postaci narzędzia
sign-artifacts, które może wywołać asystent i które przyjmujekey_path. Przed zezwoleniem na nie należy zapoznać się z tym, co ta strona mówi o takim zezwoleniu.
Składnia
aggrega sign <reference>... [flags]Opis
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.Flagi
| Flaga | Domyślnie | Opis |
|---|---|---|
--fulcio-url | — | Adres URL urzędu certyfikacji Fulcio do podpisywania bezkluczowego. Jeśli zostanie pominięty, używana jest publiczna instancja Fulcio. |
--identity-token | — | Token tożsamości OIDC do podpisywania bezkluczowego. Opcjonalny w interaktywnym terminalu (token uzyskuje się w przeglądarce) oraz w GitHub Actions (token OIDC przepływu pracy jest generowany automatycznie); wymagany w pozostałych zastosowaniach nieinteraktywnych/CI, gdzie można go zamiast tego wyeksportować jako AGGREGA_IDENTITY_TOKEN lub SIGSTORE_ID_TOKEN. |
--jobs | 1 | Liczba odwołań podpisywanych naraz. Każde jest nadal podpisywane dokładnie tak, jak byłoby podpisane samodzielnie, a wynik zachowuje kolejność, w jakiej podano odwołania. Co najmniej 1. |
--key | — | Ścieżka do posiadanego klucza prywatnego ECDSA P-256 w formacie PEM do podpisywania kluczem w trybie offline. Jeśli zostanie pominięta, używane jest podpisywanie bezkluczowe. |
--rekor-url | — | Adres URL dziennika przejrzystości Rekor do podpisywania bezkluczowego. Jeśli zostanie pominięty, używana jest publiczna instancja Rekor. |
--timestamp-url | — | Opcjonalny adres URL urzędu znaczników czasu RFC3161 do podpisywania bezkluczowego. |