aggrega sign
aggrega sign signe un ou plusieurs artefacts de catalogue déjà publiés et attache chaque signature comme referrer OCI. C’est le pendant post-publication de aggrega push --sign : utilisez-le pour signer un artefact publié sans signature, ou pour signer tout un lot d’artefacts en une seule invocation. Il n’ajoute pas de seconde signature à un artefact qui en porte déjà une que la politique de confiance de son registre vérifie.
Fonctionnement
aggrega sign résout le digest que le registre détient déjà pour chaque <reference>, signe ce digest et attache le bundle de signature comme referrer. Il ne refait jamais de push, ne réétiquette jamais et ne modifie d’aucune autre façon les octets publiés — l’artefact est immuable, et la signature est un manifeste frère qui pointe vers lui. Un artefact peut donc être signé après coup sans changement de version.
Avant de signer, il lit les signatures que la référence porte déjà et les évalue par rapport à la politique de confiance que cet espace de travail détient pour le registre de la référence — la politique par rapport à laquelle aggrega pull vérifie. Lorsqu’une signature est vérifiée, quel qu’en soit le signataire, la référence est déjà signée : la commande imprime Already signed: avec la référence, son digest, l’identité signataire et, lorsque le journal de transparence a enregistré la signature, sa date — celle de la plus ancienne de ces signatures lorsqu’il y en a plusieurs —, n’attache rien et compte la référence comme signée. Un lecteur qui vérifie les signatures keyless date une version d’après la plus ancienne d’entre elles qui est vérifiée et nomme le signataire de cette signature, comme le décrit aggrega registry update, de sorte qu’une autre signature ajouterait un referrer et une entrée au journal de transparence sans rien changer à ce qu’un tel lecteur tire de la version.
Un registre dont la politique n’épingle aucune clé publique et aucune identité de confiance ne fournit rien par rapport à quoi évaluer une signature, donc une référence y est signée quoi qu’elle porte déjà. Une référence ne portant que des signatures que la politique n’admet pas est signée, puisque aucune d’entre elles ne compte pour un lecteur qui vérifie selon cette politique.
La signature est un bundle Sigstore (compatible cosign), le même format que aggrega push --sign attache et que aggrega pull vérifie. Le referrer nomme le bundle signature.json, de sorte qu’un client OCI générique qui récupère le referrer par son digest écrit le bundle dans ce fichier.
Signature par lot
Passez plusieurs références pour les signer en une seule invocation :
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.0La signature keyless résout l’identité une seule fois pour tout le lot — une authentification interactive, ou sur GitHub Actions le point de terminaison OIDC ambiant du runner — et la réutilise pour chaque artefact, en émettant un nouveau certificat Fulcio de courte durée par artefact. Un jeton acquis de manière interactive ou fourni est réutilisé pour chaque signature ; le point de terminaison ambiant émet un nouveau jeton par signature. Les références peuvent cibler des registres différents : chacune est signée avec cette identité unique auprès des points de terminaison Fulcio et Rekor configurés pour son propre registre. La voie avec clé (--key) signe le lot sans aucune authentification.
La signature fonctionne en mode continuer et signaler : chaque référence signable est signée, une référence dont la résolution, la signature ou l’attachement échoue est consignée, et le lot passe à la référence suivante plutôt que de s’arrêter au premier échec. Une référence qui porte déjà une signature vérifiée est signalée comme déjà signée et compte comme signée. Une référence dont les signatures existantes ne peuvent pas être lues — le registre ne termine pas la liste, ou une signature ne peut être ni récupérée ni évaluée alors qu’aucune n’est vérifiée — est consignée comme en échec et n’est pas signée : une question sans réponse n’est jamais lue comme un artefact non signé. Après le lot, si une référence a échoué, un récapitulatif listant les références en échec est imprimé sur stderr et la commande se termine avec un code non nul. Les références qui ont réussi sont signées indépendamment des échecs des autres.
Signer plusieurs références à la fois
Par défaut, le lot signe une référence après l’autre. --jobs N signe jusqu’à N références à la fois, et jamais plus de N. Chacune est toujours signée exactement comme elle le serait seule : son digest publié est résolu, elle est laissée telle quelle lorsqu’elle porte déjà une signature vérifiée, et sinon elle reçoit sa propre signature — keyless, sa propre clé éphémère, son propre certificat de courte durée et sa propre entrée au journal de transparence. L’identité est toujours résolue une seule fois, pour tout le lot, avant qu’aucune référence ne soit lue. Une valeur inférieure à 1 est refusée, et rien n’est signé.
Quel que soit l’ordre dans lequel les références se terminent, la sortie conserve l’ordre dans lequel elles ont été données : les lignes de chaque référence sont imprimées en entier, une fois que chaque référence nommée avant elle est terminée, de sorte que les lignes de deux références ne s’entremêlent jamais, et le récapitulatif des références en échec les liste aussi dans cet ordre. Une conséquence du fait de signer chaque référence comme si elle était seule : un lot nommant deux fois le même artefact reçoit deux signatures lorsque les deux sont signées en même temps, car aucune ne voit la signature de l’autre pendant qu’elle est créée, alors que l’une après l’autre, la seconde trouve celle de la première et, lorsque la politique de confiance de son registre la vérifie, n’attache rien.
La valeur par défaut est 1 parce que la signature keyless atteint l’autorité de certification et le journal de transparence publics, à moins que votre configuration n’en nomme d’autres, et ces services limitent le nombre de requêtes qu’ils acceptent.
Un identifiant par lot
Chaque référence d’une même invocation est signée avec le même identifiant : une seule clé détenue, ou une seule identité keyless. Celui dont une référence a besoin est déterminé par la configuration de son registre — un signing.key_path qui s’applique à ce registre sélectionne la clé qu’il nomme, et là où aucun ne s’applique, la référence est signée en mode keyless. Lorsque les références nécessiteraient des identifiants différents — la configuration nomme une clé pour un registre et aucune pour un autre, ou deux clés différentes —, la commande ne signe rien et nomme les registres de chaque côté. Elle le fait avant qu’aucune identité ne soit demandée et avant qu’aucun registre ne soit lu, de sorte que rien n’est attaché et que personne n’est sollicité pour une exécution qui n’aura pas lieu.
Lancez plutôt une invocation par identifiant : l’une nommant les références sur les registres signés avec une clé, une autre nommant le reste. Une clé passée avec --key s’applique à chaque référence nommée, quoi que dise la configuration pour chaque registre, de sorte qu’une invocation avec --key n’est jamais refusée pour ce motif.
Le lot est refusé plutôt que signé avec l’identifiant dont l’une de ses références a besoin, car une signature ne peut pas être rappelée auprès de quiconque l’a récupérée. Contrairement aux échecs par référence décrits ci-dessus, il s’agit du refus du lot plutôt que de celui d’une référence : aucune référence n’est signée. Lorsqu’un registre du lot exige des signatures, le message le nomme, de sorte que le refus se lit comme portant sur la combinaison des références plutôt que comme une affirmation qu’elles ne peuvent pas être signées. Le message, et ce que nomme chacune de ses parties, se trouvent dans References signed together need different signing credentials (Les références signées ensemble nécessitent des identifiants de signature différents).
Expiration du jeton d’identité en cours de lot
Un lot long peut survivre à un jeton d’identité de courte durée. Sur GitHub Actions, ce n’est pas un problème : le point de terminaison ambiant émet un nouveau jeton pour chaque signature, de sorte qu’un lot ne survit jamais à son identité. Pour un jeton acquis de manière interactive ou fourni par l’opérateur (--identity-token, AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN), un seul jeton sert pour tout le lot ; s’il expire en cours de lot, la référence concernée est consignée en mode continuer et signaler et le lot se poursuit. Relancez la commande pour signer les références signalées — ou, pour un long lot scripté, acquérez un nouveau jeton à l’avance.
Pour les lots scriptés, acquérez le jeton une seule fois à l’avance et exportez-le, en signant chaque référence sans aller-retour par le navigateur :
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.0Voir ./aggrega-auth.md pour aggrega auth token.
Lorsqu’une étape échoue de façon transitoire
Chaque référence est signée en trois étapes : son digest publié est résolu, le digest est signé, et la signature est attachée. Deux d’entre elles sont réessayées lorsqu’elles échouent d’une manière qui permet à une tentative ultérieure de réussir :
- L’appel de signature — sur tout échec pour lequel une écriture dans le registre est réessayée, et lorsque l’autorité de certification keyless signale qu’elle n’a pas pu traiter le jeton d’identité.
- L’attachement, qui écrit le bundle de signature et le manifeste du referrer dans le registre — sur une erreur du serveur, un dépassement de délai ou une connexion réinitialisée ;
aggrega pushliste ces échecs. Chaque tentative est un nouvel envoi des mêmes octets plutôt qu’un renvoi de la requête qui a échoué, et un attachement répété laisse une seule signature, pas deux.
Chacune est tentée au plus trois fois, à une demi-seconde puis à une seconde d’intervalle. La résolution du digest est une lecture et n’est pas réessayée. Un registre qui demande de ralentir est un cas différent : chaque requête qui lui est adressée, y compris la résolution du digest et l’attachement, attend aussi longtemps qu’il le demande, comme le décrit Un registre qui demande de ralentir.
Un appel de signature keyless interroge jusqu’à trois services — l’autorité de certification pour un certificat, le journal de transparence pour une entrée et, lorsqu’une est configurée, l’autorité d’horodatage pour un horodatage — et chaque requête est réessayée indépendamment à l’intérieur de l’appel. Une requête à laquelle l’un d’eux répond par 429 Too Many Requests ou par une erreur du serveur (pour le journal de transparence, toute erreur sauf 501 Not Implemented) est renvoyée à ce service, de sorte qu’elle est tentée au plus trois fois, à une seconde puis à deux secondes d’intervalle ; seule cette requête est répétée, de sorte qu’une entrée du journal de transparence demandée à nouveau ne demande pas de second certificat. Le journal de transparence est aussi interrogé à nouveau lorsque la connexion avec lui échoue, et un Retry-After qu’il envoie avec un 429 ou un 503 est respecté aussi longtemps qu’il le demande. Une réponse de limitation de débit ou d’erreur du serveur qui revient encore après ces tentatives fait échouer l’appel de signature, qui n’est alors pas réessayé dans son ensemble.
Une étape qui échoue encore après sa dernière tentative est consignée pour cette référence en mode continuer et signaler, avec son erreur, et le lot poursuit — un attachement en échec est signalé comme la signature qui n’a pas pu être attachée ; tout autre échec est consigné immédiatement.
Modes de signature
- Keyless (par défaut) — une clé éphémère liée à une identité OIDC par un certificat Fulcio de courte durée, enregistrée dans le journal de transparence Rekor. Fulcio et Rekor utilisent par défaut les instances Sigstore publiques (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). L’horodatage de confiance keyless provient de l’inclusion dans le journal de transparence de Rekor ; une autorité d’horodatage RFC3161 distincte est facultative — fournissez--timestamp-urlavec un point de terminaison complet pour en activer une. Dans un terminal interactif, la signature keyless ne nécessite aucun flag : la CLI ouvre un navigateur pour acquérir un jeton d’identité OIDC de courte durée. Sur GitHub Actions, elle n’en nécessite pas non plus : la CLI émet automatiquement le jeton OIDC du workflow à partir du point de terminaison ambiant du runner. Pour les autres usages non interactifs / CI, exportezAGGREGA_IDENTITY_TOKEN(ouSIGSTORE_ID_TOKEN), ou passez--identity-token; sans jeton fourni, sans point de terminaison ambiant et sans terminal, la commande est refusée. - Keyed (
--key) — une clé ECDSA P-256 détenue hors ligne (PEM compatible cosign). Aucun fournisseur d’identité, aucune autorité de certification ni aucun journal de transparence n’est contacté ; le registre l’est toujours, pour résoudre chaque digest et y attacher sa signature.
Les URL keyless et le chemin de la clé peuvent aussi provenir du bloc signing: de .aggrega-config.yaml (global et par registre) ; un flag remplace la configuration, et la configuration remplace la valeur publique par défaut. Dans ce fichier, chaque URL s’écrit comme une URL https absolue — https://, un hôte et, éventuellement, un port et un chemin, comme https://fulcio.sigstore.dev — et une valeur de toute autre forme, sans schéma ou commençant par http://, est refusée au chargement du fichier, avec le nom du fichier et de la clé. Le jeton d’identité OIDC n’est jamais un champ de configuration, et la clé privée n’est jamais en ligne — seulement un chemin vers elle.
La construction et le comportement de signature et d’attachement sont partagés avec aggrega push, de sorte que les deux verbes signent de manière identique.
Variables d’environnement
Les entrées de signature peuvent être fournies par l’environnement, remplaçant le bloc signing: de .aggrega-config.yaml, tandis qu’un flag garde la priorité :
AGGREGA_IDENTITY_TOKEN— le jeton d’identité OIDC keyless (l’équivalent en variable d’environnement de--identity-token).SIGSTORE_ID_TOKENest accepté comme alias d’interopérabilité de l’écosystème sigstore, classé aprèsAGGREGA_IDENTITY_TOKENet l’endpoint ambiant de GitHub Actions. Le jeton n’est jamais un champ de configuration.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL— les URL des services keyless.AGGREGA_SIGNING_KEY_PATH— un chemin pointant vers un PEM de clé keyed (jamais le matériel de clé).
aggrega sign résout la configuration de signature et ces variables pour l’hôte du registre de l’artefact, de la même façon que aggrega push. L’ordre de priorité est flag > environnement > configuration > valeur par défaut. Voir environment-variables.md pour la liste complète.
Une URL fournie par l’une de ces variables, ou par --fulcio-url, --rekor-url ou --timestamp-url, est prise telle qu’elle est écrite. Le fichier de configuration est vérifié avant que l’une ou l’autre ne soit appliquée par-dessus, de sorte que la forme https à laquelle ses valeurs sont tenues ne les atteint pas, et une URL malformée n’échoue que lorsque la signature contacte ce service.
Voir aussi
- ./aggrega-auth.md — acquérir un jeton d’identité OIDC une seule fois pour un lot de signatures keyless.
- ./aggrega-push.md — publier, en signant éventuellement au moment du push (signature avant push).
- ./aggrega-pull.md — le côté consommateur, qui vérifie les signatures par rapport à la politique de confiance par registre.
- ./aggrega-serve.md — le daemon propose le même lot à
aggrega/signArtifacts, résolvant son identité à partir de la requête ou de l’environnement et refusant plutôt que de solliciter l’utilisateur ; une requête à cet endroit ne nomme aucune clé, de sorte que la signature avec clé lit le blocsigning:propre à l’espace de travail. - ./aggrega-mcp.md — la même capacité sous la forme de l’outil
sign-artifacts, qu’un assistant peut appeler et qui acceptekey_path. Lisez ce que cette page dit sur son autorisation avant de l’autoriser.
Synopsis
aggrega sign <reference>... [flags]Description
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.Options
| Option | Par défaut | Description |
|---|---|---|
--fulcio-url | — | URL de l’autorité de certification Fulcio pour la signature sans clé. Si elle est omise, l’instance publique de Fulcio est utilisée. |
--identity-token | — | Jeton d’identité OIDC pour la signature sans clé. Facultatif dans un terminal interactif (un flux dans le navigateur en obtient un) et sur GitHub Actions (le jeton OIDC du workflow est émis automatiquement) ; obligatoire pour les autres usages non interactifs/CI, où il peut à la place être exporté sous la forme AGGREGA_IDENTITY_TOKEN ou SIGSTORE_ID_TOKEN. |
--jobs | 1 | Nombre de références signées à la fois. Chacune est toujours signée exactement comme elle le serait seule, et la sortie conserve l’ordre dans lequel les références ont été données. Au moins 1. |
--key | — | Chemin d’un PEM de clé privée ECDSA P-256 détenue, pour la signature hors ligne avec clé. S’il est omis, la signature sans clé est utilisée. |
--rekor-url | — | URL du journal de transparence Rekor pour la signature sans clé. Si elle est omise, l’instance publique de Rekor est utilisée. |
--timestamp-url | — | URL facultative de l’autorité d’horodatage RFC3161 pour la signature sans clé. |