Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

aggrega sign

aggrega sign firma uno o varios artefactos del catálogo ya publicados y adjunta cada firma como referrer OCI. Es la contrapartida posterior a la publicación de aggrega push --sign: úsalo para firmar un artefacto que se publicó sin firmar, o para firmar todo un lote de artefactos en una sola invocación. No añade una segunda firma a un artefacto que ya lleva una que verifica la política de confianza de su registro.

Qué hace

aggrega sign resuelve el digest que el registro ya tiene para cada <reference>, firma ese digest y adjunta el bundle de la firma como referrer. Nunca vuelve a hacer push, nunca vuelve a etiquetar ni modifica de ningún otro modo los bytes publicados — el artefacto es inmutable, y la firma es un manifiesto hermano que apunta a él. Así, un artefacto puede firmarse a posteriori sin aumentar la versión.

Antes de firmar, lee las firmas que la referencia ya lleva y las juzga según la política de confianza que este espacio de trabajo tiene para el registro de la referencia — la política con la que verifica aggrega pull. Cuando una se verifica, la haya firmado quien la haya firmado, la referencia ya está firmada: el comando imprime Already signed: con la referencia, su digest, la identidad firmante y, cuando el log de transparencia registró la firma, cuándo — la más antigua de esas firmas cuando hay varias —, no adjunta nada y cuenta la referencia como firmada. Un lector que verifica firmas keyless fecha una versión por la más antigua de ellas que se verifica y nombra al firmante de esa firma, como describe aggrega registry update, así que otra firma añadiría un referrer y una entrada en el log de transparencia sin cambiar nada de lo que ese lector obtiene de la versión.

Un registro cuya política no fija ninguna clave pública ni ninguna identidad de confianza no ofrece nada con lo que juzgar una firma, por lo que allí una referencia se firma lleve lo que lleve. Una referencia que solo lleva firmas que la política no admite se firma, ya que ninguna de ellas cuenta para un lector que verifica según esa política.

La firma es un bundle de Sigstore (compatible con cosign), el mismo formato que adjunta aggrega push --sign y que verifica aggrega pull. El referrer llama al bundle signature.json, de modo que un cliente OCI genérico que descarga el referrer por su digest escribe el bundle en ese archivo.

Firma por lotes

Pasa varias referencias para firmarlas en una sola invocación:

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 resuelve la identidad una sola vez para todo el lote — una autenticación interactiva o, en GitHub Actions, el endpoint OIDC ambiental del runner — y la reutiliza para cada artefacto, emitiendo un certificado Fulcio nuevo de corta duración por artefacto. Un token adquirido de forma interactiva o suministrado se reutiliza para cada firma; el endpoint ambiental emite un token nuevo por firma. Las referencias pueden apuntar a registros distintos: cada una se firma con esa única identidad contra los endpoints de Fulcio y Rekor configurados para su propio registro. La vía con clave (--key) firma el lote sin ninguna autenticación.

La firma sigue el modo continuar e informar: se firma cada referencia firmable, se registra cada referencia que no se puede resolver, firmar o adjuntar, y el lote pasa a la siguiente referencia en lugar de detenerse en el primer fallo. Una referencia que ya lleva una firma que se verifica se notifica como ya firmada y cuenta como firmada. Una referencia cuyas firmas existentes no se pueden leer — el registro no completa el listado, o una firma no se puede descargar ni juzgar mientras ninguna se verifica — se registra como fallida y no se firma: una pregunta sin respuesta nunca se interpreta como un artefacto sin firmar. Tras el lote, si alguna referencia falló, se imprime en stderr un resumen con las referencias fallidas y el comando sale con un código distinto de cero. Las referencias que tuvieron éxito quedan firmadas independientemente de los fallos de las demás.

Firmar varias referencias a la vez

De forma predeterminada, el lote firma una referencia tras otra. --jobs N firma hasta N referencias a la vez, y nunca más de N. Cada una se sigue firmando exactamente como se firmaría sola: se resuelve su digest publicado, se deja como está cuando ya lleva una firma que se verifica y, en caso contrario, recibe una firma propia — keyless, su propia clave efímera, su propio certificado de corta duración y su propia entrada en el log de transparencia. La identidad se sigue resolviendo una sola vez, para todo el lote, antes de leer ninguna referencia. Un valor inferior a 1 se rechaza, y no se firma nada.

Sea cual sea el orden en que terminen las referencias, la salida conserva el orden en que se dieron: las líneas de cada referencia se imprimen completas una vez que ha terminado cada referencia nombrada antes que ella, de modo que las líneas de dos referencias nunca se entremezclan, y el resumen de referencias fallidas también las enumera en ese orden. Una consecuencia de firmar cada referencia como si estuviera sola: un lote que nombra dos veces el mismo artefacto recibe dos firmas cuando ambas se firman a la vez, porque ninguna ve la firma de la otra mientras se crea, mientras que, una tras otra, la segunda encuentra la de la primera y, cuando la política de confianza de su registro la verifica, no adjunta nada.

El valor predeterminado es 1 porque la firma keyless accede a la autoridad de certificación y al log de transparencia públicos, salvo que tu configuración nombre otros, y esos servicios limitan cuántas solicitudes aceptan.

Una credencial por lote

Cada referencia de una misma invocación se firma con la misma credencial: una única clave en posesión o una única identidad keyless. Cuál necesita una referencia lo decide la configuración de su registro — un signing.key_path que se aplica a ese registro selecciona la clave que nombra, y donde no se aplica ninguno la referencia se firma keyless. Cuando las referencias necesitarían credenciales distintas — la configuración nombra una clave para un registro y ninguna para otro, o dos claves distintas —, el comando no firma nada y nombra los registros de cada lado. Lo hace antes de pedir ninguna identidad y antes de leer ningún registro, de modo que no se adjunta nada y no se pide nada a nadie para una ejecución que no va a seguir adelante.

En su lugar, ejecuta una invocación por credencial: una que nombre las referencias de los registros firmados con una clave y otra que nombre el resto. Una clave pasada con --key se aplica a cada referencia nombrada, diga lo que diga la configuración para cada registro, por lo que una invocación con --key nunca se rechaza por este motivo.

El lote se rechaza en lugar de firmarse con la credencial que necesite alguna de sus referencias, porque una firma no se puede retirar de quien ya la haya descargado. A diferencia de los fallos por referencia descritos antes, este es el rechazo del lote y no de una referencia: no se firma ninguna referencia. Cuando un registro del lote exige firmas, el mensaje lo nombra, de modo que el rechazo se lee como relativo a la combinación de las referencias y no como una afirmación de que no se pueden firmar. El mensaje, y lo que nombra cada parte de él, están en References signed together need different signing credentials (Las referencias firmadas juntas necesitan credenciales de firma distintas).

Caducidad del token de identidad a mitad del lote

Un lote largo puede durar más que un token de identidad de corta duración. En GitHub Actions esto no es un problema: el endpoint ambiental emite un token nuevo para cada firma, así que un lote nunca dura más que su identidad. Para un token adquirido de forma interactiva o suministrado por el operador (--identity-token, AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN), un único token sirve para todo el lote; si caduca a mitad del lote, la referencia afectada se registra según el modo continuar e informar y el lote continúa. Vuelve a ejecutar el comando para firmar las referencias notificadas — o, para un lote largo con script, adquiere un token nuevo de antemano.

Para lotes con script, adquiere el token una vez de antemano y expórtalo, de modo que cada referencia se firme sin pasar por el 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

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

Cuando un paso falla de forma transitoria

Cada referencia se firma en tres pasos: se resuelve su digest publicado, se firma el digest y se adjunta la firma. Dos de ellos se reintentan cuando fallan de un modo en que un intento posterior puede tener éxito:

  • La llamada de firma — ante cualquier fallo por el que se reintenta una escritura en el registro, y cuando la autoridad de certificación keyless informa de que no pudo procesar el token de identidad.
  • El adjunto, que escribe en el registro el bundle de la firma y el manifiesto del referrer — ante un error del servidor, un tiempo de espera agotado o una conexión restablecida; aggrega push enumera esos fallos. Cada intento es una nueva subida de los mismos bytes y no un reenvío de la solicitud que falló, y un adjunto repetido deja una sola firma, no dos.

Cada uno se intenta como máximo tres veces, con medio segundo y luego un segundo de separación. Resolver el digest es una lectura y no se reintenta. Un registro que pide ir más despacio es un caso distinto: cada solicitud que se le hace, incluidos la resolución del digest y el adjuntado de la firma, espera lo que pida, como describe Un registro que pide ir más despacio.

Una llamada de firma keyless consulta hasta tres servicios — la autoridad de certificación para un certificado, el log de transparencia para una entrada y, cuando hay una configurada, la autoridad de sellado de tiempo para una marca de tiempo — y cada solicitud se reintenta por separado dentro de la llamada. Una solicitud que uno de ellos responde con 429 Too Many Requests o con un error del servidor (para el log de transparencia, cualquiera salvo 501 Not Implemented) se vuelve a enviar a ese servicio, de modo que se intenta como máximo tres veces, con un segundo y luego dos segundos de separación; solo se repite esa solicitud, así que una entrada del log de transparencia que se pide de nuevo no pide un segundo certificado. El log de transparencia también se vuelve a consultar cuando falla la conexión con él, y un Retry-After que envíe con un 429 o un 503 se espera durante todo el tiempo que indique. Una respuesta de limitación de frecuencia o de error del servidor que sigue llegando tras esos intentos hace fallar la llamada de firma, que entonces no se reintenta en su conjunto.

Un paso que sigue fallando tras su último intento se registra para esa referencia según el modo continuar e informar, con su error, y el lote sigue adelante — un adjunto fallido se notifica como la firma que no se pudo adjuntar; cualquier otro fallo se registra de inmediato.

Modos de firma

  • Keyless (predeterminado) — una clave efímera vinculada a una identidad OIDC mediante un certificado Fulcio de corta duración, registrada en el log de transparencia Rekor. Fulcio y Rekor usan de forma predeterminada las instancias públicas de Sigstore (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). La marca de tiempo de confianza keyless procede de la inclusión en el log de transparencia de Rekor; una autoridad de sellado de tiempo RFC3161 independiente es opcional — proporciona --timestamp-url con un endpoint completo para habilitar una. En un terminal interactivo, la firma keyless no necesita flags: la CLI abre un navegador para adquirir un token de identidad OIDC de corta duración. En GitHub Actions tampoco necesita ninguno: la CLI emite automáticamente el token OIDC del flujo de trabajo desde el endpoint ambiental del runner. Para otros usos no interactivos / CI, exporta AGGREGA_IDENTITY_TOKEN (o SIGSTORE_ID_TOKEN), o pasa --identity-token; sin token suministrado, sin endpoint ambiental y sin terminal, el comando se rechaza.
  • Keyed (--key): una clave ECDSA P-256 guardada sin conexión (PEM compatible con cosign). No se contacta con ningún proveedor de identidad, autoridad de certificación ni log de transparencia; con el registro sí, para resolver cada digest y adjuntar su firma.

Las URL keyless y la ruta de la clave también pueden venir del bloque signing: de .aggrega-config.yaml (global y por registro); un flag sobrescribe la configuración, y la configuración sobrescribe el valor público predeterminado. En ese archivo, cada URL se escribe como una URL https absoluta — https://, un host y, opcionalmente, un puerto y una ruta, como https://fulcio.sigstore.dev — y un valor con cualquier otra forma, sin esquema o que empiece por http://, se rechaza al cargar el archivo, con el nombre del archivo y de la clave. El token de identidad OIDC nunca es un campo de configuración, y la clave privada nunca va en línea — solo una ruta a ella.

La construcción y el comportamiento de firma y adjunto se comparten con aggrega push, de modo que ambos verbos firman de forma idéntica.

Variables de entorno

Las entradas de firma pueden suministrarse a través del entorno, sobrescribiendo el bloque signing: de .aggrega-config.yaml, mientras que un flag sigue teniendo prioridad:

  • AGGREGA_IDENTITY_TOKEN: el token de identidad OIDC keyless (el equivalente en el entorno de --identity-token). SIGSTORE_ID_TOKEN se acepta como alias de interoperabilidad del ecosistema sigstore, con menor prioridad que AGGREGA_IDENTITY_TOKEN y el endpoint ambiental de GitHub Actions. El token nunca es un campo de configuración.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL: las URL de los servicios keyless.
  • AGGREGA_SIGNING_KEY_PATH: una ruta que apunta a un PEM de clave keyed (nunca el material de la clave).

aggrega sign resuelve la configuración de firma y estas variables para el host del registro del artefacto, del mismo modo que aggrega push. La precedencia es flag > entorno > configuración > valor predeterminado. Consulta environment-variables.md para ver la lista completa.

Una URL suministrada mediante una de estas variables, o mediante --fulcio-url, --rekor-url o --timestamp-url, se toma tal como está escrita. El archivo de configuración se comprueba antes de aplicar cualquiera de ellas por encima, de modo que la forma https a la que se ciñen sus valores no les alcanza, y una mal formada solo falla cuando la firma contacta con ese servicio.

Véase también

  • ./aggrega-auth.md — adquiere un token de identidad OIDC una sola vez para un lote de firmas keyless.
  • ./aggrega-push.md — publica, firmando opcionalmente en el momento del push (firma antes del push).
  • ./aggrega-pull.md — el lado consumidor, que verifica las firmas según la política de confianza por registro.
  • ./aggrega-serve.md — el daemon ofrece el mismo lote en aggrega/signArtifacts, resolviendo su identidad a partir de la solicitud o del entorno y rechazando en lugar de preguntar; una solicitud allí no nombra ninguna clave, así que la firma con clave lee el bloque signing: propio del espacio de trabajo.
  • ./aggrega-mcp.md — la misma capacidad como la herramienta sign-artifacts, que un asistente puede llamar y que acepta key_path. Lee lo que esa página dice sobre permitirla antes de hacerlo.

Sinopsis

aggrega sign <reference>... [flags]

Descripción

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

FlagPredeterminadoDescripción
--fulcio-url—URL de la autoridad de certificación Fulcio para la firma sin clave. Si se omite, se usa la instancia pública de Fulcio.
--identity-token—Token de identidad OIDC para la firma sin clave. Opcional en un terminal interactivo (un flujo en el navegador obtiene uno) y en GitHub Actions (el token OIDC del workflow se emite automáticamente); obligatorio para otros usos no interactivos/CI, donde en su lugar se puede exportar como AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN.
--jobs1Número de referencias firmadas a la vez. Cada una se sigue firmando exactamente como se firmaría sola, y la salida conserva el orden en que se dieron las referencias. Como mínimo 1.
--key—Ruta a un PEM de clave privada ECDSA P-256 en tu poder para la firma con clave sin conexión. Si se omite, se usa la firma sin clave.
--rekor-url—URL del registro de transparencia Rekor para la firma sin clave. Si se omite, se usa la instancia pública de Rekor.
--timestamp-url—URL opcional de la autoridad de sellado de tiempo RFC3161 para la firma sin clave.