Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

aggrega sign

aggrega sign firma uno o più artefatti di catalogo già pubblicati e allega ciascuna firma come referrer OCI. È la controparte post-pubblicazione di aggrega push --sign: usalo per firmare un artefatto pubblicato senza firma, o per firmare un intero lotto di artefatti in un’unica invocazione. Non aggiunge una seconda firma a un artefatto che ne porta già una verificata dalla policy di fiducia del suo registry.

Cosa fa

aggrega sign risolve il digest che il registry già possiede per ogni <reference>, firma quel digest e allega il bundle della firma come referrer. Non esegue mai un nuovo push, non riassegna tag e non modifica in alcun altro modo i byte pubblicati — l’artefatto è immutabile, e la firma è un manifest fratello che punta a esso. Così un artefatto può essere firmato a posteriori senza alcun incremento di versione.

Prima di firmare, legge le firme che il riferimento porta già e le giudica rispetto alla policy di fiducia che questo workspace possiede per il registry del riferimento — la policy rispetto a cui verifica aggrega pull. Se una di esse viene verificata, chiunque l’abbia firmata, il riferimento è già firmato: il comando stampa Already signed: con il riferimento, il suo digest, l’identità firmataria e, quando il log di trasparenza ha registrato la firma, quando — la prima di tali firme, se ce ne sono diverse —, non allega nulla e conta il riferimento come firmato. Un lettore che verifica firme keyless data una versione in base alla prima di esse che viene verificata e nomina il firmatario di quella firma, come descrive aggrega registry update, quindi un’altra firma aggiungerebbe un referrer e una voce nel log di trasparenza senza cambiare nulla di ciò che un tale lettore ricava dalla versione.

Un registry la cui policy non fissa alcuna chiave pubblica e alcuna identità attendibile non offre nulla rispetto a cui giudicare una firma, quindi lì un riferimento viene firmato qualunque cosa porti già. Un riferimento che porta solo firme che la policy non ammette viene firmato, poiché nessuna di esse conta per un lettore che verifica secondo quella policy.

La firma è un bundle Sigstore (compatibile con cosign), lo stesso formato che aggrega push --sign allega e aggrega pull verifica. Il referrer chiama il bundle signature.json, quindi un client OCI generico che scarica il referrer tramite il suo digest scrive il bundle in quel file.

Firma in lotto

Passa più riferimenti per firmarli in un’unica invocazione:

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

La firma keyless risolve l’identità una sola volta per l’intero lotto — un’autenticazione interattiva, oppure su GitHub Actions l’endpoint OIDC ambientale del runner — e la riutilizza per ogni artefatto, emettendo un nuovo certificato Fulcio di breve durata per ciascun artefatto. Un token acquisito interattivamente o fornito viene riutilizzato per ogni firma; l’endpoint ambientale conia un nuovo token per ogni firma. I riferimenti possono puntare a registry diversi: ciascuno viene firmato con quell’unica identità rispetto agli endpoint Fulcio e Rekor configurati per il proprio registry. Il percorso con chiave (--key) firma il lotto senza alcuna autenticazione.

La firma segue il modello continua e segnala: ogni riferimento firmabile viene firmato, un riferimento che non riesce a essere risolto, firmato o allegato viene registrato, e il lotto passa al riferimento successivo anziché arrestarsi al primo errore. Un riferimento che porta già una firma che viene verificata è segnalato come già firmato e conta come firmato. Un riferimento le cui firme esistenti non possono essere lette — il registry non completa l’elenco, oppure una firma non può essere scaricata o giudicata mentre nessuna viene verificata — è registrato come fallito e non viene firmato: una domanda senza risposta non viene mai letta come un artefatto non firmato. Dopo il lotto, se un riferimento è fallito, un riepilogo che elenca i riferimenti falliti viene stampato su stderr e il comando termina con un codice diverso da zero. I riferimenti riusciti sono firmati indipendentemente dagli errori degli altri.

Firmare più riferimenti contemporaneamente

Per impostazione predefinita il lotto firma un riferimento dopo l’altro. --jobs N firma fino a N riferimenti contemporaneamente, e mai più di N. Ciascuno viene comunque firmato esattamente come lo sarebbe da solo: il suo digest pubblicato viene risolto, viene lasciato com’è se porta già una firma che viene verificata, e altrimenti riceve una firma propria — keyless, con la propria chiave effimera, il proprio certificato di breve durata e la propria voce nel log di trasparenza. L’identità viene comunque risolta una sola volta, per l’intero lotto, prima che venga letto qualsiasi riferimento. Un valore inferiore a 1 viene rifiutato, e non viene firmato nulla.

In qualunque ordine finiscano i riferimenti, l’output mantiene l’ordine in cui sono stati forniti: le righe di ogni riferimento vengono stampate per intero, una volta che ogni riferimento nominato prima di esso è terminato, così le righe di due riferimenti non si intrecciano mai, e anche il riepilogo dei riferimenti falliti li elenca in quell’ordine. Una conseguenza del firmare ogni riferimento come se fosse da solo: un lotto che nomina due volte lo stesso artefatto riceve due firme quando entrambi vengono firmati contemporaneamente, perché nessuno dei due vede la firma dell’altro mentre viene creata, mentre uno dopo l’altro il secondo trova quella del primo e, se la policy di fiducia del suo registry la verifica, non allega nulla.

Il valore predefinito è 1 perché la firma keyless raggiunge l’autorità di certificazione e il log di trasparenza pubblici, a meno che la tua configurazione non ne nomini altri, e questi servizi limitano quante richieste accettano.

Una credenziale per lotto

Ogni riferimento in un’unica invocazione viene firmato con la stessa credenziale: una singola chiave posseduta, o una singola identità keyless. Quale serva a un riferimento lo decide la configurazione del suo registry — un signing.key_path che si applica a quel registry seleziona la chiave che nomina, e dove non se ne applica nessuno il riferimento viene firmato keyless. Quando i riferimenti richiederebbero credenziali diverse — la configurazione nomina una chiave per un registry e nessuna per un altro, oppure due chiavi diverse — il comando non firma nulla e nomina i registry di ciascuna parte. Lo fa prima che venga richiesta qualsiasi identità e prima che venga letto qualsiasi registry, quindi non viene allegato nulla e a nessuno viene chiesto nulla per un’esecuzione che non procederà.

Esegui invece un’invocazione per credenziale: una che nomina i riferimenti sui registry firmati con una chiave, un’altra che nomina il resto. Una chiave passata con --key si applica a ogni riferimento nominato, qualunque cosa dica la configurazione per ciascun registry, quindi un’invocazione con --key non viene mai rifiutata per questo motivo.

Il lotto viene rifiutato anziché firmato con la credenziale di cui ha bisogno uno qualsiasi dei suoi riferimenti, perché una firma non può essere richiamata da chiunque l’abbia scaricata. A differenza degli errori per singolo riferimento descritti sopra, questo è il rifiuto del lotto anziché di un riferimento: nessun riferimento viene firmato. Quando un registry del lotto richiede le firme, il messaggio lo nomina, così il rifiuto si legge come relativo alla combinazione dei riferimenti anziché come un’affermazione che non possono essere firmati. Il messaggio, e ciò che nomina ciascuna sua parte, si trova in References signed together need different signing credentials (I riferimenti firmati insieme richiedono credenziali di firma diverse).

Scadenza del token di identità a metà lotto

Un lotto lungo può durare più di un token di identità di breve durata. Su GitHub Actions non è un problema: l’endpoint ambientale conia un nuovo token per ogni firma, quindi un lotto non sopravvive mai alla propria identità. Per un token acquisito interattivamente o fornito dall’operatore (--identity-token, AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN), un solo token serve l’intero lotto; se scade a metà lotto, il riferimento interessato viene registrato secondo il modello continua e segnala e il lotto prosegue. Esegui di nuovo il comando per firmare i riferimenti segnalati — oppure, per un lungo lotto da script, acquisisci in anticipo un nuovo token.

Per i lotti da script, acquisisci il token una sola volta in anticipo ed esportalo, firmando ogni riferimento senza un passaggio dal browser:

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

Vedi ./aggrega-auth.md per aggrega auth token.

Quando un passaggio fallisce in modo transitorio

Ogni riferimento viene firmato in tre passaggi: il suo digest pubblicato viene risolto, il digest viene firmato e la firma viene allegata. Due di essi vengono ritentati quando falliscono in un modo per cui un tentativo successivo può riuscire:

  • La chiamata di firma — su qualsiasi errore per cui viene ritentata una scrittura nel registry, e quando l’autorità di certificazione keyless segnala di non essere riuscita a elaborare il token di identità.
  • L’allegato, che scrive nel registry il bundle della firma e il manifest del referrer — su un errore del server, un timeout o una connessione reimpostata; aggrega push elenca questi errori. Ogni tentativo è un nuovo caricamento degli stessi byte anziché un nuovo invio della richiesta fallita, e un allegato ripetuto lascia una sola firma, non due.

Ciascuno viene tentato al massimo tre volte, a mezzo secondo e poi a un secondo di distanza. La risoluzione del digest è una lettura e non viene ritentata. Un registry che chiede di rallentare è un caso diverso: ogni richiesta rivolta a esso, comprese la risoluzione del digest e l’aggiunta della firma, attende quanto esso chiede, come descrive Un registry che chiede di rallentare.

Una chiamata di firma keyless interroga fino a tre servizi — l’autorità di certificazione per un certificato, il log di trasparenza per una voce e, se ne è configurata una, l’autorità di marcatura temporale per un timestamp — e ogni richiesta viene ritentata per conto proprio all’interno della chiamata. Una richiesta a cui uno di essi risponde con 429 Too Many Requests o con un errore del server (per il log di trasparenza, qualsiasi tranne 501 Not Implemented) viene inviata di nuovo a quel servizio, quindi viene tentata al massimo tre volte, a un secondo e poi a due secondi di distanza; viene ripetuta solo quella richiesta, quindi una voce del log di trasparenza richiesta di nuovo non richiede un secondo certificato. Il log di trasparenza viene interrogato di nuovo anche quando la connessione a esso fallisce, e un Retry-After che invia con un 429 o un 503 viene atteso per tutto il tempo che chiede. Una risposta di limitazione della frequenza o di errore del server che continua ad arrivare dopo quei tentativi fa fallire la chiamata di firma, che poi non viene ritentata nel suo insieme.

Un passaggio che continua a fallire dopo l’ultimo tentativo viene registrato per quel riferimento secondo il modello continua e segnala, con il suo errore, e il lotto va avanti — un allegato fallito viene segnalato come la firma che non è stato possibile allegare; qualsiasi altro errore viene registrato subito.

Modalità di firma

  • Keyless (predefinita) — una chiave effimera legata a un’identità OIDC da un certificato Fulcio di breve durata, registrata nel log di trasparenza Rekor. Fulcio e Rekor usano per impostazione predefinita le istanze Sigstore pubbliche (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). Il timestamp attendibile keyless deriva dall’inclusione nel log di trasparenza di Rekor; un’autorità di marcatura temporale RFC3161 separata è facoltativa — fornisci --timestamp-url con un endpoint completo per abilitarne una. In un terminale interattivo la firma keyless non richiede flag: la CLI apre un browser per acquisire un token di identità OIDC di breve durata. Su GitHub Actions non ne richiede nemmeno lì: la CLI conia automaticamente il token OIDC del workflow dall’endpoint ambientale del runner. Per altri usi non interattivi / CI, esporta AGGREGA_IDENTITY_TOKEN (o SIGSTORE_ID_TOKEN), oppure passa --identity-token; senza alcun token fornito, alcun endpoint ambientale e alcun terminale il comando viene rifiutato.
  • Keyed (--key) — una chiave ECDSA P-256 conservata offline (PEM compatibile con cosign). Non viene contattato alcun provider di identità, autorità di certificazione o log di trasparenza; il registry sì, per risolvere ogni digest e allegarne la firma.

Gli URL keyless e il percorso della chiave possono anche provenire dal blocco signing: di .aggrega-config.yaml (globale e per registry); un flag sovrascrive la configurazione, e la configurazione sovrascrive il valore pubblico predefinito. In quel file ogni URL è scritto come URL https assoluto — https://, un host e facoltativamente una porta e un percorso, come https://fulcio.sigstore.dev — e un valore di qualsiasi altra forma, senza schema o che inizia con http://, viene rifiutato al caricamento del file, con il nome del file e della chiave. Il token di identità OIDC non è mai un campo di configurazione, e la chiave privata non è mai inline — solo un percorso che vi punta.

La costruzione e il comportamento di firma e allegato sono condivisi con aggrega push, quindi entrambi i verbi firmano in modo identico.

Variabili d’ambiente

Gli input di firma possono essere forniti tramite l’ambiente, sovrascrivendo il blocco signing: di .aggrega-config.yaml, mentre un flag continua ad avere la precedenza:

  • AGGREGA_IDENTITY_TOKEN — il token di identità OIDC keyless (la controparte d’ambiente di --identity-token). SIGSTORE_ID_TOKEN è accettato come alias di interoperabilità con l’ecosistema sigstore, con priorità inferiore a AGGREGA_IDENTITY_TOKEN e all’endpoint ambientale di GitHub Actions. Il token non è mai un campo di configurazione.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — gli URL dei servizi keyless.
  • AGGREGA_SIGNING_KEY_PATH — un puntatore al percorso di un PEM con chiave keyed (mai il materiale della chiave).

aggrega sign risolve la configurazione di firma e queste variabili per l’host del registry dell’artefatto, nello stesso modo di aggrega push. La precedenza è flag > ambiente > configurazione > predefinito. Vedi environment-variables.md per l’elenco completo.

Un URL fornito tramite una di queste variabili, o tramite --fulcio-url, --rekor-url o --timestamp-url, viene preso così com’è scritto. Il file di configurazione viene controllato prima che l’uno o l’altro venga applicato sopra di esso, quindi la forma https a cui sono vincolati i suoi valori non li raggiunge, e uno malformato fallisce solo quando la firma contatta quel servizio.

Vedi anche

  • ./aggrega-auth.md — acquisisci un token di identità OIDC una sola volta per un lotto di firme keyless.
  • ./aggrega-push.md — pubblica, facoltativamente firmando al momento del push (firma prima del push).
  • ./aggrega-pull.md — il lato del consumo, che verifica le firme rispetto alla policy di fiducia per registry.
  • ./aggrega-serve.md — il daemon offre lo stesso lotto in aggrega/signArtifacts, risolvendo la propria identità dalla richiesta o dall’ambiente e rifiutando anziché chiedere; una richiesta lì non nomina alcuna chiave, quindi la firma con chiave legge il blocco signing: del workspace stesso.
  • ./aggrega-mcp.md — la stessa funzionalità come strumento sign-artifacts, che un assistente può chiamare e che accetta key_path. Leggi ciò che quella pagina dice sul consentirlo prima di farlo.

Sinossi

aggrega sign <reference>... [flags]

Descrizione

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.

Flag

FlagPredefinitoDescrizione
--fulcio-url—URL dell’autorità di certificazione Fulcio per la firma keyless. Se omesso, viene usata l’istanza pubblica di Fulcio.
--identity-token—Token di identità OIDC per la firma keyless. Facoltativo in un terminale interattivo (un flusso nel browser ne acquisisce uno) e su GitHub Actions (il token OIDC del workflow viene generato automaticamente); obbligatorio per altri usi non interattivi/CI, dove può invece essere esportato come AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN.
--jobs1Numero di riferimenti firmati contemporaneamente. Ciascuno viene comunque firmato esattamente come lo sarebbe da solo, e l’output mantiene l’ordine in cui i riferimenti sono stati forniti. Almeno 1.
--key—Percorso di un PEM di chiave privata ECDSA P-256 posseduta, per la firma con chiave offline. Se omesso, viene usata la firma keyless.
--rekor-url—URL del transparency log Rekor per la firma keyless. Se omesso, viene usata l’istanza pubblica di Rekor.
--timestamp-url—URL facoltativo della timestamp authority RFC3161 per la firma keyless.