Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

aggrega sign

aggrega sign assina um ou mais artefatos de catálogo já publicados e anexa cada assinatura como um referrer OCI. É a contrapartida pós-publicação de aggrega push --sign: use-o para assinar um artefato que foi publicado sem assinatura, ou para assinar um lote inteiro de artefatos em uma única invocação. Ele não adiciona uma segunda assinatura a um artefato que já carrega uma que a política de confiança do seu registry verifica.

O que ele faz

aggrega sign resolve o digest que o registry já tem para cada <reference>, assina esse digest e anexa o bundle da assinatura como referrer. Ele nunca faz push de novo, nunca reaplica tags nem altera de qualquer outra forma os bytes publicados — o artefato é imutável, e a assinatura é um manifesto irmão que aponta de volta para ele. Assim, um artefato pode ser assinado depois do fato sem aumento de versão.

Antes de assinar, ele lê as assinaturas que a referência já carrega e as avalia em relação à política de confiança que este workspace mantém para o registry da referência — a política com base na qual aggrega pull verifica. Quando uma delas é verificada, seja quem for que a assinou, a referência já está assinada: o comando imprime Already signed: com a referência, seu digest, a identidade signatária e, quando o log de transparência registrou a assinatura, quando — a mais antiga dessas assinaturas, quando há várias —, não anexa nada e conta a referência como assinada. Um leitor que verifica assinaturas keyless data uma versão pela mais antiga delas que é verificada e nomeia o signatário dessa assinatura, como descreve aggrega registry update, então outra assinatura acrescentaria um referrer e uma entrada no log de transparência sem mudar nada do que tal leitor obtém da versão.

Um registry cuja política não fixa nenhuma chave pública e nenhuma identidade confiável não oferece nada com que avaliar uma assinatura, então uma referência ali é assinada seja o que for que ela já carregue. Uma referência que carrega apenas assinaturas que a política não admite é assinada, já que nenhuma delas conta para um leitor que verifica sob essa política.

A assinatura é um bundle do Sigstore (compatível com cosign), o mesmo formato que aggrega push --sign anexa e aggrega pull verifica. O referrer nomeia o bundle como signature.json, então um cliente OCI genérico que baixa o referrer pelo seu digest grava o bundle nesse arquivo.

Assinatura em lote

Passe várias referências para assiná-las em uma única invocação:

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

A assinatura keyless resolve a identidade uma única vez para o lote inteiro — uma autenticação interativa ou, no GitHub Actions, o endpoint OIDC ambiente do runner — e a reutiliza para cada artefato, emitindo um novo certificado Fulcio de curta duração por artefato. Um token adquirido de forma interativa ou fornecido é reutilizado para cada assinatura; o endpoint ambiente emite um novo token por assinatura. As referências podem ter como destino registries diferentes: cada uma é assinada com essa única identidade junto aos endpoints Fulcio e Rekor configurados para seu próprio registry. O caminho com chave (--key) assina o lote sem nenhuma autenticação.

A assinatura segue o modo continuar e relatar: toda referência assinável é assinada, uma referência que não consegue ser resolvida, assinada ou anexada é registrada, e o lote passa para a próxima referência em vez de parar na primeira falha. Uma referência que já carrega uma assinatura que é verificada é relatada como já assinada e conta como assinada. Uma referência cujas assinaturas existentes não podem ser lidas — o registry não completa a listagem, ou uma assinatura não pode ser baixada nem avaliada enquanto nenhuma é verificada — é registrada como falha e não é assinada: uma pergunta sem resposta nunca é lida como um artefato não assinado. Após o lote, se alguma referência falhou, um resumo que lista as referências com falha é impresso em stderr e o comando termina com código diferente de zero. As referências que tiveram sucesso ficam assinadas independentemente das falhas das outras.

Assinar várias referências ao mesmo tempo

Por padrão, o lote assina uma referência após a outra. --jobs N assina até N referências ao mesmo tempo, e nunca mais que N. Cada uma continua sendo assinada exatamente como seria sozinha: seu digest publicado é resolvido, ela é deixada como está quando já carrega uma assinatura que é verificada e, caso contrário, recebe uma assinatura própria — keyless, com sua própria chave efêmera, seu próprio certificado de curta duração e sua própria entrada no log de transparência. A identidade continua sendo resolvida uma única vez, para o lote inteiro, antes que qualquer referência seja lida. Um valor menor que 1 é recusado, e nada é assinado.

Seja qual for a ordem em que as referências terminem, a saída mantém a ordem em que elas foram fornecidas: as linhas de cada referência são impressas por inteiro, depois que cada referência nomeada antes dela tiver terminado, de modo que as linhas de duas referências nunca se intercalam, e o resumo das referências com falha também as lista nessa ordem. Uma consequência de assinar cada referência como se estivesse sozinha: um lote que nomeia o mesmo artefato duas vezes recebe duas assinaturas quando as duas são assinadas ao mesmo tempo, porque nenhuma vê a assinatura da outra enquanto ela está sendo feita, ao passo que, uma após a outra, a segunda encontra a da primeira e, quando a política de confiança do seu registry a verifica, não anexa nada.

O padrão é 1 porque a assinatura keyless acessa a autoridade certificadora e o log de transparência públicos, a menos que sua configuração nomeie outros, e esses serviços limitam quantas requisições aceitam.

Uma credencial por lote

Toda referência em uma única invocação é assinada com a mesma credencial: uma única chave mantida ou uma única identidade keyless. Qual delas uma referência precisa é decidido pela configuração do seu registry — um signing.key_path que se aplica a esse registry seleciona a chave que nomeia, e onde nenhum se aplica a referência é assinada keyless. Quando as referências precisariam de credenciais diferentes — a configuração nomeia uma chave para um registry e nenhuma para outro, ou duas chaves diferentes —, o comando não assina nada e nomeia os registries de cada lado. Ele faz isso antes que qualquer identidade seja solicitada e antes que qualquer registry seja lido, de modo que nada é anexado e ninguém recebe um prompt para uma execução que não vai seguir adiante.

Em vez disso, execute uma invocação por credencial: uma que nomeie as referências nos registries assinados com uma chave, outra que nomeie o restante. Uma chave passada com --key se aplica a toda referência nomeada, seja o que for que a configuração diga para cada registry, então uma invocação com --key nunca é recusada por esse motivo.

O lote é recusado em vez de assinado com a credencial de que uma de suas referências precisa, porque uma assinatura não pode ser recolhida de quem já a baixou. Diferentemente das falhas por referência descritas acima, esta é a recusa do lote, e não de uma referência: nenhuma referência é assinada. Quando um registry do lote exige assinaturas, a mensagem o nomeia, de modo que a recusa se lê como sendo sobre a combinação das referências, e não como uma afirmação de que elas não podem ser assinadas. A mensagem, e o que cada parte dela nomeia, está em References signed together need different signing credentials (Referências assinadas juntas precisam de credenciais de assinatura diferentes).

Expiração do token de identidade no meio do lote

Um lote longo pode durar mais que um token de identidade de curta duração. No GitHub Actions isso não é problema: o endpoint ambiente emite um novo token para cada assinatura, então um lote nunca dura mais que sua identidade. Para um token adquirido de forma interativa ou fornecido pelo operador (--identity-token, AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN), um único token serve ao lote inteiro; se ele expirar no meio do lote, a referência afetada é registrada no modo continuar e relatar e o lote prossegue. Execute o comando de novo para assinar as referências relatadas — ou, para um lote longo em script, adquira um novo token de antemão.

Para lotes em script, adquira o token uma vez de antemão e exporte-o, assinando cada referência sem passar pelo navegador:

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

Veja ./aggrega-auth.md para aggrega auth token.

Quando uma etapa falha de forma transitória

Cada referência é assinada em três etapas: seu digest publicado é resolvido, o digest é assinado e a assinatura é anexada. Duas delas são tentadas novamente quando falham de uma forma em que uma tentativa posterior pode ter sucesso:

  • A chamada de assinatura — em qualquer falha para a qual uma gravação no registry é tentada novamente, e quando a autoridade certificadora keyless informa que não conseguiu processar o token de identidade.
  • O anexo, que grava no registry o bundle da assinatura e o manifesto do referrer — em um erro do servidor, um timeout ou uma conexão redefinida; aggrega push lista essas falhas. Cada tentativa é um novo upload dos mesmos bytes, e não um reenvio da requisição que falhou, e um anexo repetido deixa uma assinatura, não duas.

Cada uma é tentada no máximo três vezes, com meio segundo e depois um segundo de intervalo. A resolução do digest é uma leitura e não é tentada novamente. Um registry que pede para desacelerar é um caso diferente: toda requisição a ele, incluindo a resolução do digest e o anexo da assinatura, aguarda o tempo que ele pedir, como descreve Um registry que pede para desacelerar.

Uma chamada de assinatura keyless consulta até três serviços — a autoridade certificadora para um certificado, o log de transparência para uma entrada e, quando há uma configurada, a autoridade de carimbo de tempo para um carimbo de tempo — e cada requisição é tentada novamente por conta própria dentro da chamada. Uma requisição que um deles responde com 429 Too Many Requests ou com um erro do servidor (para o log de transparência, qualquer um exceto 501 Not Implemented) é enviada de novo a esse serviço, de modo que é tentada no máximo três vezes, com um segundo e depois dois segundos de intervalo; só essa requisição é repetida, então uma entrada do log de transparência pedida de novo não pede um segundo certificado. O log de transparência também é consultado de novo quando a conexão com ele falha, e um Retry-After que ele envia com um 429 ou um 503 é aguardado pelo tempo que ele pedir. Uma resposta de limitação de taxa ou de erro do servidor que continua chegando após essas tentativas faz a chamada de assinatura falhar, e ela então não é tentada novamente como um todo.

Uma etapa que continua falhando após sua última tentativa é registrada para essa referência no modo continuar e relatar, com seu erro, e o lote segue adiante — um anexo com falha é relatado como a assinatura que não pôde ser anexada; qualquer outra falha é registrada de imediato.

Modos de assinatura

  • Keyless (padrão) — uma chave efêmera vinculada a uma identidade OIDC por um certificado Fulcio de curta duração, registrada no log de transparência Rekor. Fulcio e Rekor usam por padrão as instâncias públicas do Sigstore (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). O carimbo de tempo confiável keyless vem da inclusão no log de transparência do Rekor; uma autoridade de carimbo de tempo RFC3161 separada é opcional — forneça --timestamp-url com um endpoint completo para habilitar uma. Em um terminal interativo, a assinatura keyless não precisa de flags: a CLI abre um navegador para adquirir um token de identidade OIDC de curta duração. No GitHub Actions também não precisa de nenhuma: a CLI emite automaticamente o token OIDC do workflow a partir do endpoint ambiente do runner. Para outros usos não interativos / CI, exporte AGGREGA_IDENTITY_TOKEN (ou SIGSTORE_ID_TOKEN), ou passe --identity-token; sem token fornecido, sem endpoint ambiente e sem terminal, o comando é recusado.
  • Keyed (--key) — uma chave ECDSA P-256 mantida offline (PEM compatível com cosign). Nenhum provedor de identidade, autoridade certificadora ou log de transparência é contatado; o registry ainda é, para resolver cada digest e anexar sua assinatura.

As URLs keyless e o caminho da chave também podem vir do bloco signing: de .aggrega-config.yaml (global e por registry); uma flag sobrescreve a configuração, e a configuração sobrescreve o padrão público. Nesse arquivo, cada URL é escrita como uma URL https absoluta — https://, um host e, opcionalmente, uma porta e um caminho, como https://fulcio.sigstore.dev — e um valor em qualquer outra forma, sem esquema ou começando com http://, é recusado quando o arquivo é carregado, nomeando o arquivo e a chave. O token de identidade OIDC nunca é um campo de configuração, e a chave privada nunca fica inline — apenas um caminho para ela.

A construção e o comportamento de assinar e anexar são compartilhados com aggrega push, então os dois verbos assinam de forma idêntica.

Variáveis de ambiente

As entradas de assinatura podem ser fornecidas pelo ambiente, sobrescrevendo o bloco signing: de .aggrega-config.yaml, enquanto uma flag continua tendo prioridade:

  • AGGREGA_IDENTITY_TOKEN — o token de identidade OIDC keyless (o equivalente em variável de ambiente de --identity-token). SIGSTORE_ID_TOKEN é aceito como alias de interoperabilidade do ecossistema sigstore, com prioridade abaixo de AGGREGA_IDENTITY_TOKEN e do endpoint de ambiente do GitHub Actions. O token nunca é um campo de configuração.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — as URLs dos serviços keyless.
  • AGGREGA_SIGNING_KEY_PATH — um caminho que aponta para um PEM de chave keyed (nunca o material da chave).

aggrega sign resolve a configuração de assinatura e essas variáveis para o host do registry do artefato, da mesma forma que aggrega push. A precedência é flag > ambiente > configuração > padrão. Veja environment-variables.md para a lista completa.

Uma URL fornecida por uma dessas variáveis, ou por --fulcio-url, --rekor-url ou --timestamp-url, é usada como está escrita. O arquivo de configuração é verificado antes que qualquer uma delas seja aplicada por cima dele, então a forma https a que seus valores estão sujeitos não as alcança, e uma malformada só falha quando a assinatura contata esse serviço.

Veja também

  • ./aggrega-auth.md — adquira um token de identidade OIDC uma única vez para um lote de assinaturas keyless.
  • ./aggrega-push.md — publique, opcionalmente assinando no momento do push (assinar antes do push).
  • ./aggrega-pull.md — o lado consumidor, que verifica assinaturas em relação à política de confiança por registry.
  • ./aggrega-serve.md — o daemon oferece o mesmo lote em aggrega/signArtifacts, resolvendo sua identidade a partir da requisição ou do ambiente e recusando em vez de solicitar interação; uma requisição ali não nomeia nenhuma chave, então a assinatura com chave lê o bloco signing: do próprio workspace.
  • ./aggrega-mcp.md — a mesma capacidade como a ferramenta sign-artifacts, que um assistente pode chamar e que aceita key_path. Leia o que essa página diz sobre permiti-la antes de fazê-lo.

Sinopse

aggrega sign <reference>... [flags]

Descrição

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

FlagPadrãoDescrição
--fulcio-url—URL da autoridade certificadora Fulcio para assinatura sem chave. Quando omitida, a instância pública do Fulcio é usada.
--identity-token—Token de identidade OIDC para assinatura sem chave. Opcional em um terminal interativo (um fluxo no navegador obtém um) e no GitHub Actions (o token OIDC do workflow é emitido automaticamente); obrigatório para outros usos não interativos/CI, em que pode ser exportado como AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN.
--jobs1Número de referências assinadas ao mesmo tempo. Cada uma continua sendo assinada exatamente como seria sozinha, e a saída mantém a ordem em que as referências foram fornecidas. No mínimo 1.
--key—Caminho para um PEM de chave privada ECDSA P-256 em seu poder, para assinatura offline com chave. Quando omitido, a assinatura sem chave é usada.
--rekor-url—URL do log de transparência Rekor para assinatura sem chave. Quando omitida, a instância pública do Rekor é usada.
--timestamp-url—URL opcional da autoridade de carimbo de tempo RFC3161 para assinatura sem chave.