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키리스 서명은 일괄 작업 전체에 대해 ID를 한 번 확인하고(한 번의 대화형 인증, 또는 GitHub Actions에서는 러너의 앰비언트 OIDC 엔드포인트) 모든 아티팩트에 재사용하며, 아티팩트마다 수명이 짧은 Fulcio 인증서를 새로 발급합니다. 대화형으로 획득했거나 직접 제공한 토큰은 모든 서명에 재사용되고, 앰비언트 엔드포인트는 서명마다 새 토큰을 발급합니다. 참조들은 서로 다른 레지스트리를 대상으로 할 수 있으며, 각 참조는 그 하나의 ID로 해당 레지스트리에 구성된 Fulcio 및 Rekor 엔드포인트를 사용해 서명됩니다. 키 방식(--key)은 인증 없이 일괄 작업을 서명합니다.
서명은 계속 진행 후 보고 방식입니다. 서명 가능한 모든 참조가 서명되고, 확인, 서명 또는 첨부에 실패한 참조는 기록되며, 일괄 작업은 첫 실패에서 중단하지 않고 다음 참조로 진행합니다. 검증되는 서명을 이미 가진 참조는 이미 서명된 것으로 보고되고 서명된 것으로 집계됩니다. 기존 서명을 읽을 수 없는 참조(레지스트리가 목록 조회를 완료하지 않거나, 검증되는 서명이 없는 상태에서 서명을 가져오거나 판정할 수 없는 경우)는 실패로 기록되고 서명되지 않습니다. 답을 얻지 못한 질문을 서명되지 않은 아티팩트로 해석하지 않습니다. 일괄 작업 후 실패한 참조가 있으면 실패한 참조 목록 요약이 stderr에 출력되고 명령은 0이 아닌 코드로 종료됩니다. 성공한 참조는 다른 참조의 실패와 관계없이 서명된 상태로 남습니다.
여러 참조를 한 번에 서명하기
기본적으로 일괄 작업은 참조를 하나씩 차례로 서명합니다. --jobs N은 최대 N개의 참조를 한 번에 서명하며, N개를 넘지 않습니다. 각 참조는 여전히 단독으로 서명할 때와 정확히 같이 서명됩니다. 게시된 다이제스트를 확인하고, 검증되는 서명을 이미 지닌 경우 그대로 두며, 그렇지 않으면 자체 서명을 받습니다. 키리스 방식에서는 자체 임시 키, 자체 단기 인증서, 자체 투명성 로그 항목을 사용합니다. ID는 여전히 어떤 참조도 읽기 전에 일괄 작업 전체에 대해 한 번만 확인됩니다. 1보다 작은 값은 거부되며 아무것도 서명되지 않습니다.
참조가 어떤 순서로 끝나든 출력은 참조가 주어진 순서를 유지합니다. 각 참조의 줄은 그 앞에 지정된 모든 참조가 끝난 뒤에 한꺼번에 출력되므로 두 참조의 줄이 섞이지 않으며, 실패한 참조의 요약도 그 순서로 나열합니다. 각 참조를 단독인 것처럼 서명하는 데 따른 결과가 하나 있습니다. 같은 아티팩트를 두 번 지정한 일괄 작업은 둘을 한 번에 서명하면 서명이 두 개 생깁니다. 서명을 만드는 동안 어느 쪽도 다른 쪽의 서명을 보지 못하기 때문입니다. 반면 하나씩 차례로 서명하면 두 번째는 첫 번째의 서명을 찾고, 레지스트리의 신뢰 정책이 그 서명을 검증하는 경우 아무것도 첨부하지 않습니다.
기본값이 1인 이유는, 구성에서 다른 것을 지정하지 않는 한 키리스 서명은 공공 인증 기관과 투명성 로그에 접속하며, 이러한 서비스는 받아들이는 요청 수를 제한하기 때문입니다.
일괄 작업당 하나의 자격 증명
한 번의 호출에 포함된 모든 참조는 같은 자격 증명, 즉 보유한 단일 키 또는 단일 키리스 ID로 서명됩니다. 참조에 어느 것이 필요한지는 해당 레지스트리의 구성으로 결정됩니다. 그 레지스트리에 적용되는 signing.key_path가 있으면 그것이 지정하는 키가 선택되고, 적용되는 것이 없으면 참조는 키리스로 서명됩니다. 참조들에 서로 다른 자격 증명이 필요한 경우(구성이 한 레지스트리에는 키를 지정하고 다른 레지스트리에는 지정하지 않거나, 서로 다른 두 키를 지정하는 경우) 명령은 아무것도 서명하지 않고 양쪽의 레지스트리를 명시합니다. 이 판단은 ID를 요청하기 전, 그리고 레지스트리를 읽기 전에 이루어지므로, 진행되지 않을 실행에 대해 아무것도 첨부되지 않고 누구에게도 입력을 요청하지 않습니다.
대신 자격 증명마다 한 번씩 호출하십시오. 하나는 키로 서명하는 레지스트리의 참조를, 다른 하나는 나머지를 지정합니다. --key로 전달한 키는 각 레지스트리에 대한 구성과 관계없이 지정된 모든 참조에 적용되므로, --key를 사용한 호출은 이 이유로 거부되지 않습니다.
서명은 이미 가져간 사람에게서 회수할 수 없으므로, 일괄 작업은 참조 중 하나가 필요로 하는 자격 증명으로 서명되는 대신 거부됩니다. 앞에서 설명한 참조별 실패와 달리 이것은 한 참조가 아닌 일괄 작업 전체의 거부이며, 어떤 참조도 서명되지 않습니다. 일괄 작업에 서명을 요구하는 레지스트리가 있으면 메시지가 그 레지스트리를 명시하므로, 이 거부는 참조를 서명할 수 없다는 뜻이 아니라 참조를 함께 묶은 것에 대한 거부로 읽힙니다. 메시지와 그 각 부분이 가리키는 내용은 References signed together need different signing credentials (함께 서명하는 참조에 서로 다른 서명 자격 증명이 필요함)에 있습니다.
일괄 작업 중 ID 토큰 만료
긴 일괄 작업은 수명이 짧은 ID 토큰보다 오래 걸릴 수 있습니다. GitHub Actions에서는 문제가 되지 않습니다. 앰비언트 엔드포인트가 서명마다 새 토큰을 발급하므로 일괄 작업이 ID보다 오래 지속되는 일이 없습니다. 대화형으로 획득했거나 운영자가 제공한 토큰(--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.0aggrega auth token에 대해서는 ./aggrega-auth.md를 참조하십시오.
단계가 일시적으로 실패하는 경우
각 참조는 세 단계로 서명됩니다. 게시된 다이제스트를 확인하고, 다이제스트에 서명하고, 서명을 첨부합니다. 이 중 두 단계는 이후의 시도가 성공할 수 있는 방식으로 실패했을 때 재시도됩니다.
- 서명 호출 — 레지스트리 쓰기가 재시도되는 모든 실패, 그리고 키리스 인증 기관이 신원 토큰을 처리할 수 없다고 보고하는 경우에 재시도됩니다.
- 첨부는 서명 번들과 referrer manifest를 레지스트리에 기록하며, 서버 오류, 시간 초과 또는 연결 재설정 시 재시도됩니다. 해당 실패 목록은
aggrega push에 있습니다. 각 시도는 실패한 요청을 다시 보내는 것이 아니라 동일한 바이트를 새로 업로드하는 것이며, 첨부가 반복되어도 서명은 두 개가 아니라 하나만 남습니다.
각 단계는 최대 세 번 시도되며, 시도 간격은 처음에 0.5초, 그다음에 1초입니다. 다이제스트 확인은 읽기 작업이므로 재시도되지 않습니다. 속도를 늦추라고 요청하는 레지스트리는 다른 경우입니다. 다이제스트 확인과 첨부를 포함해 해당 레지스트리에 대한 모든 요청은 속도를 늦추라고 요청하는 레지스트리에서 설명하는 대로 레지스트리가 요청하는 만큼 기다립니다.
키리스 서명 호출은 최대 세 개의 서비스에 요청합니다. 인증서를 위한 인증 기관, 항목을 위한 투명성 로그, 그리고 구성된 경우 타임스탬프를 위한 타임스탬프 기관이며, 각 요청은 호출 안에서 개별적으로 재시도됩니다. 이들 중 하나가 429 Too Many Requests 또는 서버 오류(투명성 로그의 경우 501 Not Implemented를 제외한 모든 오류)로 응답한 요청은 그 서비스로 다시 보내지므로 최대 세 번, 1초 그다음 2초 간격으로 시도됩니다. 그 요청만 반복되므로, 투명성 로그 항목을 다시 요청해도 두 번째 인증서를 요청하지는 않습니다. 투명성 로그와의 연결이 실패할 때도 다시 요청하며, 투명성 로그가 429 또는 503과 함께 보내는 Retry-After는 요구하는 시간만큼 기다립니다. 이러한 시도 후에도 여전히 속도 제한이나 서버 오류 응답이 돌아오면 서명 호출은 실패하며, 이후 호출 전체가 재시도되지는 않습니다.
마지막 시도 후에도 계속 실패하는 단계는 continue-and-report 방식에 따라 해당 오류와 함께 그 참조에 대해 기록되며, 배치는 다음으로 진행됩니다. 실패한 첨부는 첨부할 수 없었던 서명으로 보고되며, 그 밖의 실패는 즉시 기록됩니다.
서명 모드
- 키리스(기본값) — 수명이 짧은 Fulcio 인증서로 OIDC ID에 바인딩된 임시 키이며, Rekor 투명성 로그에 기록됩니다. Fulcio와 Rekor는 기본적으로 공익용 Sigstore 인스턴스(
https://fulcio.sigstore.dev,https://rekor.sigstore.dev)를 사용합니다. 키리스 서명의 신뢰할 수 있는 타임스탬프는 Rekor 투명성 로그 포함 증명에서 얻으며, 별도의 RFC3161 타임스탬프 기관은 선택 사항입니다. 사용하려면 전체 엔드포인트와 함께--timestamp-url을 지정합니다. 대화형 터미널에서는 키리스 서명에 플래그가 필요하지 않습니다. CLI가 브라우저를 열어 수명이 짧은 OIDC ID 토큰을 획득합니다. GitHub Actions에서도 플래그가 필요하지 않습니다. CLI가 러너 환경의 엔드포인트에서 워크플로 OIDC 토큰을 자동으로 발급받습니다. 그 밖의 비대화형 / CI 환경에서는AGGREGA_IDENTITY_TOKEN(또는SIGSTORE_ID_TOKEN)을 내보내거나--identity-token을 전달합니다. 제공된 토큰도, 환경의 엔드포인트도, 터미널도 없으면 명령이 거부됩니다. - 키 기반(Keyed)(
--key) — 오프라인으로 보관하는 ECDSA P-256 키(cosign 호환 PEM)입니다. 신원 공급자, 인증 기관, 투명성 로그에는 접속하지 않습니다. 다만 각 다이제스트를 확인하고 서명을 첨부하기 위해 레지스트리에는 여전히 접속합니다.
키리스 URL과 키 기반 서명의 키 경로는 .aggrega-config.yaml의 signing: 블록(전역 및 레지스트리별)에서도 지정할 수 있습니다. 플래그는 구성보다 우선하고, 구성은 공익용 기본값보다 우선합니다. 이 파일에서 각 URL은 절대 https URL로 작성합니다. 즉 https://, 호스트, 그리고 선택적으로 포트와 경로로 이루어지며, 예를 들면 https://fulcio.sigstore.dev와 같습니다. 그 밖의 형태의 값, 즉 스킴이 없거나 http://로 시작하는 값은 파일을 로드할 때 해당 파일과 키를 명시하며 거부됩니다. OIDC ID 토큰은 구성 필드로 지정할 수 없으며, 개인 키는 인라인으로 작성하지 않고 그 경로만 지정합니다.
구성 방식과 서명 및 첨부 동작은 aggrega push와 공유되므로 두 명령은 동일하게 서명합니다.
환경 변수
서명 입력값은 환경을 통해 제공할 수도 있습니다. 이 값은 .aggrega-config.yaml의 signing: 블록보다 우선하지만, 플래그가 있으면 플래그가 우선합니다:
AGGREGA_IDENTITY_TOKEN— 키리스 OIDC ID 토큰입니다(--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를 참고하십시오.
이 변수 중 하나나 --fulcio-url, --rekor-url, --timestamp-url로 제공한 URL은 작성된 그대로 사용됩니다. 구성 파일은 그 위에 이 값들이 적용되기 전에 검사되므로, 구성 파일의 값에 요구되는 https 형식 검사는 이 값들에는 적용되지 않으며, 형식이 잘못된 값은 서명 과정에서 해당 서비스에 접속할 때에야 실패합니다.
참고 항목
- ./aggrega-auth.md — 키리스 서명을 일괄로 수행할 때 OIDC ID 토큰을 한 번만 획득합니다.
- ./aggrega-push.md — 게시하며, 선택적으로 푸시 시점에 서명합니다(푸시 전 서명).
- ./aggrega-pull.md — 소비하는 쪽으로, 레지스트리별 신뢰 정책에 따라 서명을 검증합니다.
- ./aggrega-serve.md — 데몬은 동일한 일괄 처리를
aggrega/signArtifacts에서 수행하며, ID를 요청 또는 환경에서 확인하고 사용자에게 묻는 대신 거부합니다. 이 요청에는 키를 지정하지 않으므로, 키 기반 서명은 워크스페이스 자체의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 | — | 키리스 서명에 사용할 Fulcio 인증 기관 URL입니다. 생략하면 공용 Fulcio 인스턴스를 사용합니다. |
--identity-token | — | 키리스 서명에 사용할 OIDC ID 토큰입니다. 대화형 터미널(브라우저 흐름으로 토큰을 획득합니다)과 GitHub Actions(워크플로 OIDC 토큰이 자동으로 발급됩니다)에서는 선택 사항입니다. 그 밖의 비대화형/CI 환경에서는 필수이며, 대신 AGGREGA_IDENTITY_TOKEN 또는 SIGSTORE_ID_TOKEN으로 내보낼 수도 있습니다. |
--jobs | 1 | 한 번에 서명하는 참조의 수입니다. 각 참조는 여전히 단독으로 서명할 때와 정확히 같이 서명되며, 출력은 참조가 주어진 순서를 유지합니다. 최소 1입니다. |
--key | — | 오프라인 키 기반 서명에 사용할, 보유 중인 ECDSA P-256 개인 키 PEM의 경로입니다. 생략하면 키리스 서명을 사용합니다. |
--rekor-url | — | 키리스 서명에 사용할 Rekor 투명성 로그 URL입니다. 생략하면 공용 Rekor 인스턴스를 사용합니다. |
--timestamp-url | — | 키리스 서명에 사용할 선택적 RFC3161 타임스탬프 기관 URL입니다. |