aggrega sign
aggrega sign підписує один або кілька вже опублікованих артефактів каталогу й прикріплює кожен підпис як OCI referrer. Це відповідник aggrega push --sign для етапу після публікації: використовуйте її, щоб підписати артефакт, опублікований без підпису, або щоб підписати цілий пакет артефактів за один виклик. Вона не додає другого підпису до артефакту, який уже має підпис, що його перевіряє політика довіри його реєстру.
Що вона робить
aggrega sign визначає дайджест, який реєстр уже зберігає для кожного <reference>, підписує цей дайджест і долучає пакет підпису як referrer. Вона ніколи не надсилає повторно, не перетеговує і жодним іншим чином не змінює опубліковані байти — артефакт незмінний, а підпис є сусіднім маніфестом, що вказує на нього. Тому артефакт можна підписати згодом без підвищення версії.
Перед підписуванням вона зчитує підписи, які посилання вже має, і оцінює їх за політикою довіри, яку цей робочий простір зберігає для реєстру посилання, — політикою, за якою перевіряє aggrega pull. Якщо один із них проходить перевірку, хоч би хто його підписав, посилання вже підписане: команда виводить Already signed: із посиланням, його дайджестом, ідентичністю підписувача і, якщо журнал прозорості зафіксував підпис, часом підписання — найранішого такого підпису, якщо їх кілька, — нічого не долучає і зараховує посилання як підписане. Читач, що перевіряє безключові підписи, датує версію за найранішим із них, що проходить перевірку, і називає підписувача цього підпису, як описано в aggrega registry update, тож ще один підпис додав би referrer і запис у журналі прозорості, але не змінив би нічого з того, що такий читач бере з версії.
Реєстр, політика якого не закріплює жодного відкритого ключа й жодної довіреної ідентичності, не дає нічого, за чим оцінити підпис, тому посилання в ньому підписується незалежно від того, що воно вже має. Посилання, що має лише підписи, яких політика не допускає, підписується, оскільки жоден із них не зараховується для читача, який перевіряє за цією політикою.
Підпис — це пакет Sigstore (сумісний із cosign), той самий формат, який долучає aggrega push --sign і перевіряє aggrega pull. Referrer називає пакет signature.json, тож універсальний клієнт OCI, що завантажує referrer за його дайджестом, записує пакет у цей файл.
Пакетне підписування
Передайте кілька посилань, щоб підписати їх за один виклик:
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Безключове підписування визначає ідентичність один раз для всього пакета — одна інтерактивна автентифікація або, на GitHub Actions, навколишня кінцева точка OIDC раннера — і повторно використовує її для кожного артефакту, видаючи для кожного артефакту новий короткоживучий сертифікат Fulcio. Токен, отриманий інтерактивно або переданий, повторно використовується для кожного підпису; навколишня кінцева точка видає новий токен для кожного підпису. Посилання можуть вказувати на різні реєстри: кожне підписується тією самою ідентичністю з використанням кінцевих точок Fulcio і Rekor, налаштованих для його власного реєстру. Шлях із ключем (--key) підписує пакет взагалі без автентифікації.
Підписування працює за принципом продовжити й повідомити: кожне посилання, яке можна підписати, підписується, посилання, яке не вдалося визначити, підписати або приєднати, фіксується, і пакет переходить до наступного посилання, а не зупиняється на першій невдачі. Посилання, яке вже має підпис, що проходить перевірку, позначається як уже підписане й зараховується як підписане. Посилання, наявні підписи якого неможливо прочитати — реєстр не завершує перелік або підпис не вдається отримати чи оцінити, тоді як жоден не проходить перевірку, — фіксується як невдале й не підписується: питання без відповіді ніколи не тлумачиться як непідписаний артефакт. Після пакета, якщо будь-яке посилання зазнало невдачі, у stderr виводиться підсумок зі списком невдалих посилань, і команда завершується з ненульовим кодом. Успішні посилання підписуються незалежно від невдач інших.
Підписування кількох посилань одночасно
Типово пакет підписує посилання одне за одним. --jobs N підписує до N посилань одночасно й ніколи більше за N. Кожне однаково підписується точно так, як було б підписане окремо: його опублікований дайджест визначається, воно залишається як є, якщо вже має підпис, що проходить перевірку, а інакше отримує власний підпис — у безключовому режимі з власним ефемерним ключем, власним короткочасним сертифікатом і власним записом у журналі прозорості. Ідентичність однаково визначається один раз, для всього пакета, до читання будь-якого посилання. Значення менше за 1 відхиляється, і нічого не підписується.
У якому б порядку не завершувалися посилання, вивід зберігає порядок, у якому їх надано: рядки кожного посилання виводяться цілком, щойно завершиться кожне посилання, назване перед ним, тож рядки двох посилань ніколи не перемішуються, а підсумок невдалих посилань теж перелічує їх у цьому порядку. Один наслідок підписування кожного посилання так, ніби воно єдине: пакет, що називає той самий артефакт двічі, отримує два підписи, коли обидва підписуються одночасно, бо жоден не бачить підпису іншого, поки той створюється; натомість при підписуванні одне за одним друге знаходить підпис першого і, якщо політика довіри його реєстру цей підпис перевіряє, нічого не прикріплює.
Типове значення — 1, бо безключове підписування звертається до загальнодоступного центру сертифікації та журналу прозорості, якщо ваша конфігурація не називає інших, а ці служби обмежують кількість запитів, які приймають.
Одні облікові дані на пакет
Кожне посилання в одному виклику підписується тими самими обліковими даними: одним ключем або однією безключовою ідентичністю. Які саме потрібні посиланню, визначає конфігурація його реєстру — signing.key_path, що застосовується до цього реєстру, вибирає вказаний у ньому ключ, а якщо жоден не застосовується, посилання підписується без ключа. Коли посиланням потрібні різні облікові дані — конфігурація вказує ключ для одного реєстру й жодного для іншого або два різні ключі, — команда нічого не підписує й називає реєстри з кожного боку. Вона робить це до запиту будь-якої ідентичності та до читання будь-якого реєстру, тож нічого не приєднується й нікому не пропонується автентифікуватися для запуску, який не відбудеться.
Натомість виконайте один виклик на кожні облікові дані: один із посиланнями на реєстри, які підписуються ключем, інший — з рештою. Ключ, переданий через --key, застосовується до кожного вказаного посилання, незалежно від того, що конфігурація задає для кожного реєстру, тож виклик із --key ніколи не відхиляється з цієї причини.
Пакет відхиляється, а не підписується обліковими даними, потрібними одному з його посилань, оскільки підпис неможливо відкликати в того, хто вже його отримав. На відміну від описаних вище невдач окремих посилань, це відмова всього пакета, а не одного посилання: жодне посилання не підписується. Якщо реєстр у пакеті вимагає підписів, повідомлення називає його, тож відмова читається як така, що стосується поєднання посилань, а не як твердження, що їх неможливо підписати. Повідомлення та те, що називає кожна його частина, описано в References signed together need different signing credentials (Посилання, що підписуються разом, потребують різних облікових даних для підписування).
Закінчення терміну дії токена ідентичності посеред пакета
Довгий пакет може пережити короткоживучий токен ідентичності. На GitHub Actions це не проблема: навколишня кінцева точка видає новий токен для кожного підпису, тож пакет ніколи не переживає свою ідентичність. Для токена, отриманого інтерактивно або переданого оператором (--identity-token, AGGREGA_IDENTITY_TOKEN або SIGSTORE_ID_TOKEN), один токен обслуговує весь пакет; якщо термін його дії спливає посеред пакета, відповідне посилання фіксується за принципом «продовжити й повідомити», і пакет продовжується. Повторно запустіть команду, щоб підписати зазначені посилання, — або, для довгого скриптового пакета, заздалегідь отримайте новий токен.
Для скриптових пакетів отримайте токен один раз заздалегідь і експортуйте його, підписуючи кожне посилання без звернення до браузера:
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.0Про aggrega auth token див. ./aggrega-auth.md.
Коли крок тимчасово завершується невдачею
Кожне посилання підписується в три кроки: визначається його опублікований дайджест, дайджест підписується, і підпис прикріплюється. Два з цих кроків повторюються, якщо вони завершуються невдачею так, що наступна спроба може бути успішною:
- Виклик підписування — у разі будь-якої невдачі, для якої повторюється запис у реєстр, а також коли центр сертифікації для безключового підписування повідомляє, що не зміг обробити токен ідентичності.
- Прикріплення, яке записує пакет підпису та маніфест-реферер у реєстр, — у разі помилки сервера, тайм-ауту або скинутого з’єднання; ці невдачі перелічено в
aggrega push. Кожна спроба — це нове завантаження тих самих байтів, а не повторне надсилання запиту, що завершився невдачею, і повторне прикріплення залишає один підпис, а не два.
Кожен із них виконується щонайбільше тричі, з інтервалом пів секунди, а потім секунда. Визначення дайджесту — це читання, і воно не повторюється. Реєстр, який просить сповільнитися, — інший випадок: кожен запит до нього, включно з визначенням дайджесту та прикріпленням, чекає стільки, скільки він просить, як описано в розділі Реєстр, який просить сповільнитися.
Виклик безключового підписування звертається щонайбільше до трьох служб — до центру сертифікації по сертифікат, до журналу прозорості по запис і, якщо її налаштовано, до служби позначок часу по позначку часу, — і кожен запит повторюється окремо всередині виклику. Запит, на який одна з них відповідає 429 Too Many Requests або помилкою сервера (для журналу прозорості — будь-якою, крім 501 Not Implemented), надсилається цій службі знову, тож виконується щонайбільше тричі, з інтервалом секунда, а потім дві секунди; повторюється лише цей запит, тож повторний запит запису в журналі прозорості не запитує другого сертифіката. До журналу прозорості також звертаються знову, коли з’єднання з ним не вдається, а Retry-After, який він надсилає разом із 429 або 503, витримується стільки, скільки він вимагає. Якщо після цих спроб усе ще надходить відповідь про обмеження частоти або помилку сервера, виклик підписування завершується невдачею й потім не повторюється цілком.
Крок, який і після останньої спроби завершується невдачею, записується для цього посилання за принципом continue-and-report разом із його помилкою, і пакет переходить далі: невдале прикріплення повідомляється як підпис, який не вдалося прикріпити; будь-яка інша невдача записується одразу.
Режими підписування
- Безключовий (за замовчуванням) — ефемерний ключ, прив’язаний до ідентичності OIDC короткостроковим сертифікатом Fulcio і записаний у журнал прозорості Rekor. За замовчуванням Fulcio і Rekor — це загальнодоступні екземпляри Sigstore (
https://fulcio.sigstore.dev,https://rekor.sigstore.dev). Довірена позначка часу для безключового підписування береться з включення до журналу прозорості Rekor; окремий центр позначок часу RFC3161 є необов’язковим — щоб увімкнути його, вкажіть--timestamp-urlз повною кінцевою точкою. В інтерактивному терміналі безключове підписування не потребує прапорців: CLI відкриває браузер, щоб отримати короткостроковий токен ідентичності OIDC. У GitHub Actions прапорці також не потрібні: CLI автоматично отримує токен OIDC робочого процесу з вбудованої кінцевої точки виконавця. Для іншого неінтерактивного використання / CI експортуйтеAGGREGA_IDENTITY_TOKEN(абоSIGSTORE_ID_TOKEN) чи передайте--identity-token; якщо токен не надано, вбудованої кінцевої точки немає і термінала немає, команда відхиляється. - Keyed (
--key) — ключ ECDSA P-256, що зберігається офлайн (PEM, сумісний із cosign). Ні до постачальника ідентичності, ні до центру сертифікації, ні до журналу прозорості звернень немає; до реєстру звернення все ж виконується — щоб визначити кожен дайджест і прикріпити його підпис.
URL-адреси безключового підписування та шлях до ключа для підписування з ключем також можна задати в блоці signing: файлу .aggrega-config.yaml (глобально та для окремого реєстру); прапорець має пріоритет над конфігурацією, а конфігурація — над загальнодоступним значенням за замовчуванням. У цьому файлі кожна URL-адреса записується як абсолютна URL-адреса https — https://, хост і, за потреби, порт і шлях, наприклад https://fulcio.sigstore.dev, — а значення будь-якої іншої форми, без схеми або таке, що починається з http://, відхиляється під час завантаження файлу з указанням файлу та ключа. Токен ідентичності OIDC ніколи не є полем конфігурації, а приватний ключ ніколи не вказується безпосередньо — лише шлях до нього.
Побудова підпису та поведінка підписування й прикріплення спільні з aggrega push, тож обидві команди підписують однаково.
Змінні середовища
Вхідні дані для підписування можна передати через змінні середовища; вони перевизначають блок signing: у .aggrega-config.yaml, але прапорець усе одно має пріоритет:
AGGREGA_IDENTITY_TOKEN— токен ідентичності OIDC для безключового підписування (відповідник--identity-tokenу змінних середовища).SIGSTORE_ID_TOKENвраховується як псевдонім для сумісності з екосистемою sigstore і має нижчий пріоритет, ніжAGGREGA_IDENTITY_TOKENта вбудована кінцева точка GitHub Actions. Токен ніколи не є полем конфігурації.AGGREGA_SIGNING_FULCIO_URL,AGGREGA_SIGNING_REKOR_URL,AGGREGA_SIGNING_TIMESTAMP_URL— URL-адреси служб безключового підписування.AGGREGA_SIGNING_KEY_PATH— шлях до PEM-файлу ключа для підписування з ключем (ніколи не сам ключ).
aggrega sign визначає конфігурацію підписування та ці змінні для хоста реєстру артефакту так само, як це робить aggrega push. Порядок пріоритету: прапорець > середовище > конфігурація > значення за замовчуванням. Повний список див. у environment-variables.md.
URL, переданий через одну з цих змінних або через --fulcio-url, --rekor-url чи --timestamp-url, використовується так, як його записано. Файл конфігурації перевіряється до того, як будь-яке з цих значень застосовується поверх нього, тож вимога до форми https, яка діє для значень файлу, на них не поширюється, і некоректний URL призводить до помилки лише тоді, коли під час підписування відбувається звернення до відповідної служби.
Див. також
- ./aggrega-auth.md — одноразове отримання токена ідентичності OIDC для пакета безключових підписувань.
- ./aggrega-push.md — публікація з необов’язковим підписуванням під час push (підписування перед push).
- ./aggrega-pull.md — сторона споживання, яка перевіряє підписи за політикою довіри для кожного реєстру.
- ./aggrega-serve.md — демон виконує той самий пакет через
aggrega/signArtifacts, визначаючи ідентичність із запиту або середовища і відмовляючи, а не запитуючи; запит там не вказує ключа, тож підписування з ключем читає власний блокsigning:робочого простору. - ./aggrega-mcp.md — та сама можливість у вигляді інструмента
sign-artifacts, який може викликати асистент і який приймаєkey_path. Прочитайте, що ця сторінка каже про його дозвіл, перш ніж дозволити його.
Синтаксис
aggrega sign <reference>... [flags]Опис
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.Прапорці
| Прапорець | За замовчуванням | Опис |
|---|---|---|
--fulcio-url | — | URL центру сертифікації Fulcio для безключового підписування. Якщо не вказано, використовується загальнодоступний екземпляр Fulcio. |
--identity-token | — | Токен ідентичності OIDC для безключового підписування. Необов’язковий в інтерактивному терміналі (його отримує процес у браузері) і в GitHub Actions (токен OIDC робочого процесу випускається автоматично); обов’язковий для іншого неінтерактивного використання або використання в CI, де його натомість можна експортувати як AGGREGA_IDENTITY_TOKEN або SIGSTORE_ID_TOKEN. |
--jobs | 1 | Кількість посилань, що підписуються одночасно. Кожне однаково підписується точно так, як було б підписане окремо, а вивід зберігає порядок, у якому надано посилання. Щонайменше 1. |
--key | — | Шлях до наявного закритого ключа ECDSA P-256 у форматі PEM для офлайн-підписування ключем. Якщо не вказано, використовується безключове підписування. |
--rekor-url | — | URL журналу прозорості Rekor для безключового підписування. Якщо не вказано, використовується загальнодоступний екземпляр Rekor. |
--timestamp-url | — | Необов’язковий URL центру позначок часу RFC3161 для безключового підписування. |