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

aggrega sign

aggrega sign assina um ou mais artefactos de catálogo já publicados e anexa cada assinatura como um referrer OCI. É a contraparte pós-publicação de aggrega push --sign: use-o para assinar um artefacto que foi publicado sem assinatura, ou para assinar um lote inteiro de artefactos numa única invocação. Não acrescenta uma segunda assinatura a um artefacto que já tem uma que a política de confiança do seu registo verifica.

O que faz

aggrega sign resolve o digest que o registo já contém para cada <reference>, assina esse digest e anexa o pacote da assinatura como um referrer. Nunca volta a enviar, a etiquetar nem altera de outra forma os bytes publicados — o artefacto é imutável, e a assinatura é um manifesto irmão que aponta para ele. Assim, um artefacto pode ser assinado posteriormente sem qualquer incremento de versão.

Antes de assinar, lê as assinaturas que a referência já tem e avalia-as em relação à política de confiança que este espaço de trabalho mantém para o registo da referência — a política em relação à 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, o seu digest, a identidade de assinatura e, quando o registo de transparência registou a assinatura, a data — a da mais antiga dessas assinaturas, quando há várias —, não anexa nada e conta a referência como assinada. Um leitor que verifica assinaturas sem chave data uma versão pela mais antiga delas que é verificada e nomeia o signatário dessa assinatura, como descreve aggrega registry update, pelo que outra assinatura acrescentaria um referrer e uma entrada no registo de transparência e não mudaria nada do que esse leitor retira da versão.

Um registo cuja política não fixa nenhuma chave pública nem nenhuma identidade de confiança não dá nada em relação ao qual avaliar uma assinatura, pelo que uma referência aí é assinada seja o que for que já tenha. Uma referência que tem apenas assinaturas que a política não admite é assinada, uma vez que nenhuma delas conta para um leitor que verifica sob essa política.

A assinatura é um pacote Sigstore (compatível com cosign), o mesmo formato que aggrega push --sign anexa e aggrega pull verifica. O referrer dá ao pacote o nome signature.json, pelo que um cliente OCI genérico que obtenha o referrer pelo seu digest escreve o pacote nesse ficheiro.

Assinatura em lote

Passe várias referências para as assinar numa ú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 sem chave resolve a identidade uma vez para todo o lote — uma autenticação interativa, ou, no GitHub Actions, o endpoint OIDC ambiente do runner — e reutiliza-a em todos os artefactos, emitindo um certificado Fulcio novo e de curta duração por artefacto. Um token obtido interativamente ou fornecido é reutilizado em todas as assinaturas; o endpoint ambiente emite um token novo por assinatura. As referências podem visar registos diferentes: cada uma é assinada com essa única identidade nos endpoints Fulcio e Rekor configurados para o seu próprio registo. O caminho com chave (--key) assina o lote sem qualquer autenticação.

A assinatura funciona em modo continuar e reportar: todas as referências assináveis são assinadas, uma referência que não consegue ser resolvida, assinada ou anexada é registada, e o lote avança para a referência seguinte em vez de parar na primeira falha. Uma referência que já tem uma assinatura que é verificada é reportada como já assinada e conta como assinada. Uma referência cujas assinaturas existentes não podem ser lidas — o registo não conclui a listagem, ou uma assinatura não pode ser obtida ou avaliada enquanto nenhuma é verificada — é registada como falhada e não é assinada: uma pergunta sem resposta nunca é lida como um artefacto não assinado. Após o lote, se alguma referência falhou, é impresso no stderr um resumo com as referências falhadas e o comando termina com um código diferente de zero. As referências que tiveram êxito ficam assinadas independentemente das falhas das outras.

Assinar várias referências ao mesmo tempo

Por predefinição, o lote assina uma referência após a outra. --jobs N assina até N referências ao mesmo tempo, e nunca mais de N. Cada uma continua a ser assinada exatamente como seria sozinha: o seu digest publicado é resolvido, é deixada como está quando já tem uma assinatura que é verificada e, caso contrário, recebe uma assinatura própria — keyless, com a sua própria chave efémera, o seu próprio certificado de curta duração e a sua própria entrada no registo de transparência. A identidade continua a ser resolvida uma única vez, para todo o lote, antes de qualquer referência ser lida. Um valor inferior a 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 foram indicadas: as linhas de cada referência são impressas por inteiro, assim que todas as referências nomeadas antes dela tiverem terminado, pelo que as linhas de duas referências nunca se intercalam, e o resumo das referências falhadas também as enumera por essa ordem. Uma consequência de assinar cada referência como se estivesse sozinha: um lote que nomeia o mesmo artefacto duas vezes recebe duas assinaturas quando ambas são assinadas ao mesmo tempo, porque nenhuma vê a assinatura da outra enquanto está a ser criada, 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.

A predefinição é 1 porque a assinatura keyless acede à autoridade de certificação e ao registo de transparência públicos, a menos que a configuração indique outros, e esses serviços limitam quantos pedidos aceitam.

Uma credencial por lote

Todas as referências de uma invocação são assinadas com a mesma credencial: uma única chave detida, ou uma única identidade sem chave. A credencial de que uma referência precisa é decidida pela configuração do seu registo — uma signing.key_path que se aplica a esse registo seleciona a chave que nomeia, e, onde nenhuma se aplica, a referência é assinada sem chave. Quando as referências precisariam de credenciais diferentes — a configuração nomeia uma chave para um registo e nenhuma para outro, ou duas chaves diferentes —, o comando não assina nada e nomeia os registos de cada lado. Fá-lo antes de qualquer identidade ser pedida e antes de qualquer registo ser lido, pelo que nada é anexado e nada é solicitado a ninguém para uma execução que não vai avançar.

Em vez disso, execute uma invocação por credencial: uma que nomeia as referências nos registos assinados com uma chave, outra que nomeia as restantes. Uma chave passada com --key aplica-se a todas as referências nomeadas, diga a configuração o que disser para cada registo, pelo que uma invocação com --key nunca é recusada por este motivo.

O lote é recusado em vez de ser assinado com a credencial de que uma das suas referências precisa, porque uma assinatura não pode ser retirada a quem já a obteve. Ao contrário das falhas por referência descritas acima, esta é uma recusa do lote e não de uma referência: nenhuma referência é assinada. Quando um registo do lote exige assinaturas, a mensagem nomeia-o, para que a recusa se leia como sendo sobre a combinação das referências e não como uma afirmação de que não podem ser assinadas. A mensagem, e o que cada parte dela nomeia, encontra-se em References signed together need different signing credentials (As referências assinadas em conjunto precisam de credenciais de assinatura diferentes).

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

Um lote longo pode durar mais do que um token de identidade de curta duração. No GitHub Actions isto não é um problema: o endpoint ambiente emite um token novo para cada assinatura, pelo que um lote nunca dura mais do que a sua identidade. Para um token obtido interativamente ou fornecido pelo operador (--identity-token, AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN), um único token serve todo o lote; se expirar a meio do lote, a referência afetada é registada segundo o modo continuar e reportar e o lote avança. Volte a executar o comando para assinar as referências reportadas — ou, para um lote longo em script, obtenha um token novo antecipadamente.

Para lotes em script, obtenha o token uma vez antecipadamente e exporte-o, assinando cada referência sem uma ida e volta 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

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

Quando um passo falha de forma transitória

Cada referência é assinada em três passos: o seu digest publicado é resolvido, o digest é assinado e a assinatura é anexada. Dois deles são repetidos quando falham de uma forma em que uma tentativa posterior pode ter êxito:

  • A chamada de assinatura — em qualquer falha para a qual uma escrita no registo é repetida, e quando a autoridade de certificação sem chave reporta que não conseguiu processar o token de identidade.
  • O anexo, que escreve o pacote da assinatura e o manifesto do referrer no registo — num erro do servidor, num tempo limite esgotado ou numa ligação reposta; aggrega push enumera essas falhas. Cada tentativa é um novo carregamento dos mesmos bytes e não um reenvio do pedido que falhou, e um anexo repetido deixa uma assinatura, não duas.

Cada um é tentado 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 é repetida. Um registo que pede para abrandar é um caso diferente: cada pedido que lhe é feito, incluindo a resolução do digest e a anexação da assinatura, espera o tempo que ele pedir, como descreve Um registo que pede para abrandar.

Uma chamada de assinatura keyless consulta até três serviços — a autoridade de certificação para um certificado, o registo de transparência para uma entrada e, quando há uma configurada, a autoridade de carimbo temporal para um carimbo temporal — e cada pedido é repetido por si só dentro da chamada. Um pedido a que um deles responda com 429 Too Many Requests ou com um erro do servidor (no caso do registo de transparência, qualquer um exceto 501 Not Implemented) é enviado novamente a esse serviço, pelo que é tentado no máximo três vezes, com um segundo e depois dois segundos de intervalo; só esse pedido é repetido, pelo que uma entrada do registo de transparência pedida novamente não pede um segundo certificado. O registo de transparência também é consultado novamente quando a ligação a ele falha, e um Retry-After que envie com um 429 ou um 503 é aguardado durante todo o tempo que pedir. Uma resposta de limitação de taxa ou de erro do servidor que continue a chegar após essas tentativas faz falhar a chamada de assinatura, que não é então repetida no seu todo.

Um passo que continua a falhar após a sua última tentativa é registado para essa referência segundo o modo continuar e reportar, com o seu erro, e o lote avança — um anexo falhado é reportado como a assinatura que não pôde ser anexada; qualquer outra falha é registada de imediato.

Modos de assinatura

  • Sem chave (predefinição) — uma chave efémera associada a uma identidade OIDC por um certificado Fulcio de curta duração, registada no registo de transparência Rekor. O Fulcio e o Rekor usam por predefinição as instâncias Sigstore públicas (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). O carimbo temporal de confiança sem chave provém da inclusão no registo de transparência do Rekor; uma autoridade de carimbo temporal RFC3161 separada é opcional — forneça --timestamp-url com um endpoint completo para ativar uma. Num terminal interativo, a assinatura sem chave não precisa de flags: a CLI abre um navegador para obter 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 outras utilizações não interativas / de 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.
  • Com chave (--key) — uma chave ECDSA P-256 detida offline (PEM compatível com cosign). Não é contactado nenhum fornecedor de identidade, autoridade de certificação ou registo de transparência; o registry continua a ser contactado, para resolver cada digest e anexar a respetiva assinatura.

Os URL sem chave e o caminho da chave com chave também podem vir do bloco signing: de .aggrega-config.yaml (global e por registo); uma flag substitui a configuração, e a configuração substitui a predefinição pública. Nesse ficheiro, cada URL é escrito como um URL https absoluto — https://, um anfitrião e, opcionalmente, uma porta e um caminho, como https://fulcio.sigstore.dev — e um valor com qualquer outra forma, sem esquema ou a começar por http://, é recusado quando o ficheiro é carregado, nomeando o ficheiro e a chave. O token de identidade OIDC nunca é um campo de configuração, e a chave privada nunca é escrita inline — apenas um caminho para ela.

A construção e o comportamento de assinar e anexar são partilhados com aggrega push, pelo que ambos os verbos assinam de forma idêntica.

Variáveis de ambiente

Os dados de assinatura podem ser fornecidos através do ambiente, substituindo o bloco signing: de .aggrega-config.yaml, embora uma flag continue a prevalecer:

  • AGGREGA_IDENTITY_TOKEN — o token de identidade OIDC keyless (a contrapartida em ambiente de --identity-token). SIGSTORE_ID_TOKEN é respeitado como alias de interoperabilidade do ecossistema sigstore, com prioridade abaixo de AGGREGA_IDENTITY_TOKEN e do endpoint ambiente do GitHub Actions. O token nunca é um campo de configuração.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — os URLs dos serviços keyless.
  • AGGREGA_SIGNING_KEY_PATH — um ponteiro de caminho para um PEM de chave para assinatura com chave (nunca material de chave).

aggrega sign resolve a configuração de assinatura e estas variáveis para o anfitrião do registo do artefacto, da mesma forma que aggrega push. A precedência é flag > ambiente > configuração > predefinição. Consulte environment-variables.md para a lista completa.

Um URL fornecido através de uma destas variáveis, ou através de --fulcio-url, --rekor-url ou --timestamp-url, é aceite tal como está escrito. O ficheiro de configuração é verificado antes de qualquer um deles ser aplicado por cima, pelo que a forma https a que os seus valores estão sujeitos não os abrange, e um malformado só falha quando a assinatura contacta esse serviço.

Ver também

  • ./aggrega-auth.md — obter um token de identidade OIDC uma vez para um lote de assinaturas sem chave.
  • ./aggrega-push.md — publicar, assinando opcionalmente no momento do push (assinar antes do push).
  • ./aggrega-pull.md — o lado consumidor, que verifica as assinaturas em relação à política de confiança por registo.
  • ./aggrega-serve.md — o daemon executa o mesmo lote em aggrega/signArtifacts, resolvendo a sua identidade a partir do pedido ou do ambiente e recusando em vez de solicitar; um pedido aí não nomeia nenhuma chave, pelo que a assinatura com chave lê o próprio bloco signing: do espaço de trabalho.
  • ./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 o fazer.

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

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