Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

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.0
aggrega sign hub.example.com/component/core/worker:1.0.0

Описание aggrega auth token см. в ./aggrega-auth.md.

Когда шаг завершается временным сбоем

Каждая ссылка подписывается в три шага: разрешается её опубликованный дайджест, дайджест подписывается, и подпись прикрепляется. Два из этих шагов повторяются, если они завершаются сбоем такого рода, при котором последующая попытка может оказаться успешной:

  • Вызов подписи — при любом сбое, при котором повторяется запись в реестр, а также когда удостоверяющий центр бесключевой подписи сообщает, что не смог обработать токен идентичности.
  • Прикрепление, при котором в реестр записываются пакет подписи и манифест-referrer, — при ошибке сервера, тайм-ауте или сброшенном соединении; эти сбои перечислены в 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 — публикация с необязательной подписью во время отправки (подпись перед отправкой).
  • ./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.
--jobs1Число ссылок, подписываемых одновременно. Каждая по-прежнему подписывается ровно так, как если бы была одна, и вывод сохраняет порядок, в котором были переданы ссылки. Не меньше 1.
--key—Путь к имеющемуся закрытому ключу ECDSA P-256 в формате PEM для автономной подписи ключом. Если не указан, используется подпись без ключа.
--rekor-url—URL журнала прозрачности Rekor для подписи без ключа. Если не указан, используется общедоступный экземпляр Rekor.
--timestamp-url—Необязательный URL службы меток времени RFC3161 для подписи без ключа.