cosign

Sigstore를 사용하여 OCI 컨테이너(및 기타 아티팩트)에 서명합니다!

Cosign은 서명을 보이지 않는 인프라로 만드는 것을 목표로 합니다.

Cosign은 다음을 지원합니다:

• Sigstore 공익 Fulcio 인증 기관 및 Rekor 투명성 로그를 사용한 "키리스 서명" (기본값)
• 하드웨어 및 KMS 서명
• cosign이 생성한 암호화된 개인/공개 키 쌍을 사용한 서명
• OCI 레지스트리에서의 컨테이너 서명, 검증 및 저장.
• 자체 PKI 사용

정보

Cosign은 sigstore 프로젝트의 일부로 개발되었습니다. 우리는 또한 slack 채널을 사용합니다! 초대 링크는 여기를 클릭하세요.

설치

Homebrew, Arch, Nix, GitHub Action 및 Kubernetes 설치에 대해서는 설치 문서를 참조하세요.

Linux, macOS 및 Windows 바이너리에 대해서는 GitHub 릴리스 자산을 참조하세요.

🚨 GCS 버킷에서 cosign 릴리스를 다운로드하는 경우 - 2023년 7월 31일 지원 중단 공지에 대한 자세한 정보를 확인하세요 🚨

개발자 설치

Go 1.22+가 있다면 개발 환경을 설정할 수 있습니다:

$ git clone https://github.com/sigstore/cosign
$ cd cosign
$ go install ./cmd/cosign
$ $(go env GOPATH)/bin/cosign

기여하기

cosign에 기여하는 데 관심이 있으시다면 기여 문서를 읽어 주세요.

향후 Cosign 개발은 sigstore-go를 기반으로 하는 다음 메이저 릴리스에 집중될 예정입니다. 메인테이너들은 sigstore-go 내의 기능 개발에 집중할 것입니다. sigstore-go에 대한 기여, 특히 자체 키(BYOK) 및 서명과 관련된 기여를 환영합니다. 좋은 첫 이슈(good first issues)는 이슈 트래커를 참고해 주세요.

Cosign 2.x는 안정 릴리스이며 주기적인 기능 업데이트와 버그 수정이 계속 제공될 것입니다. 범위와 규모가 작은 PR이 빠르게 리뷰될 가능성이 높습니다.

API를 크게 수정하거나 중단시키는 PR은 허용되지 않습니다. 규모는 크지만 호환성을 깨뜨리는 변경을 도입하지 않는 PR은 허용될 수 있으나, sigstore-go의 PR보다 낮은 우선순위로 간주됩니다.

Dockerfile

다음은 ghcr.io/sigstore/cosign/cosign 이미지를 통해 Dockerfile 내에서 cosign을 설치하고 사용하는 방법입니다:

FROM ghcr.io/sigstore/cosign/cosign:v2.4.1 as cosign-bin

# Source: https://github.com/chainguard-images/images/tree/main/images/static
FROM cgr.dev/chainguard/static:latest
COPY --from=cosign-bin /ko-app/cosign /usr/local/bin/cosign
ENTRYPOINT [ "cosign" ]

빠른 시작

이것은 다음 방법을 보여줍니다:

• 기본 신원 기반 "키리스 서명" 방식으로 컨테이너 이미지에 서명하기 (자세한 내용은 문서를 참조하세요)
• 컨테이너 이미지 검증하기
• Sigstore Cosign Quickstart에서 더 넓은 키리스 블롭 서명/검증 흐름 살펴보기

컨테이너에 서명하고 레지스트리에 서명 저장하기

항상 태그(:latest)가 아닌 다이제스트(@sha256:...)를 기준으로 이미지에 서명해야 한다는 점에 유의하세요. 그렇지 않으면 의도하지 않은 것에 서명할 수 있습니다!

 cosign sign $IMAGE

Generating ephemeral keys...
Retrieving signed certificate...

	Note that there may be personally identifiable information associated with this signed artifact.
	This may include the email address associated with the account with which you authenticate.
	This information will be used for signing this artifact and will be stored in public transparency logs and cannot be removed later.

By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs.
Are you sure you would like to continue? [y/N] y
Your browser will now be opened to:
https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&code_challenge=OrXitVKUZm2lEWHVt1oQWR4HZvn0rSlKhLcltglYxCY&code_challenge_method=S256&nonce=2KvOWeTFxYfxyzHtssvlIXmY6Jk&redirect_uri=http%3A%2F%2Flocalhost%3A57102%2Fauth%2Fcallback&response_type=code&scope=openid+email&state=2KvOWfbQJ1caqScgjwibzK2qJmb
Successfully verified SCT...
tlog entry created with index: 12086900
Pushing signature to: $IMAGE

Cosign은 OIDC를 통해 인증하라는 메시지를 표시하며, 여기서 이메일 주소로 로그인하게 됩니다. 내부적으로 cosign은 Fulcio 인증 기관에 코드 서명 인증서를 요청합니다. 인증서의 주체는 로그인한 이메일 주소와 일치합니다. 그런 다음 Cosign은 서명과 인증서를 Rekor 투명성 로그에 저장하고, 서명을 서명 중인 이미지와 함께 OCI 레지스트리에 업로드합니다.

컨테이너 검증

이미지를 검증하려면 --certificate-identity 및 --certificate-oidc-issuer 플래그를 통해 예상되는 인증서 주체와 인증서 발급자를 전달해야 합니다:

cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER

인증서 ID 및 발급자 플래그에 정규식을 전달할 수도 있습니다: --certificate-identity-regexp 및 --certificate-oidc-issuer-regexp.

공개 키에 대해 컨테이너 검증

이 명령은 이미지에 대해 공개 키와 일치하는 적어도 하나의 cosign 형식 서명이 발견되면 0을 반환합니다. 다른 서명 형식에 대한 정보와 주의사항은 아래의 자세한 사용법을 참조하세요.

유효한 페이로드는 모두 json 형식으로 stdout에 출력됩니다. 이러한 서명된 페이로드에는 컨테이너 이미지의 다이제스트가 포함되어 있으며, 이를 통해 이러한 "분리된" 서명이 올바른 이미지를 대상으로 하는지 확인할 수 있습니다.

$ cosign verify --key cosign.pub $IMAGE_URI:1h
The following checks were performed on these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key
{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null}

에어갭 환경에서 컨테이너 검증하기

참고: 이 섹션은 최신 정보가 아닙니다.

참고: 대부분의 검증 워크플로는 TUF 저장소에서 서비스 키를 주기적으로 요청해야 합니다. public-good 인스턴스를 사용하여 서명을 에어갭 검증하려면, 프로덕션 TUF 저장소에서 trusted root 파일을 가져와야 합니다. 이 파일의 내용은 예고 없이 변경될 수 있습니다. TUF를 사용하지 않으면, 이 파일의 에어갭 복사본을 최신 상태로 유지하기 위한 자체 메커니즘을 구축해야 합니다.

Cosign은 일반적으로 이미지 매니페스트의 어노테이션으로 배포되는 bundle을 검증하여 완전한 오프라인 검증을 수행할 수 있습니다. 이 어노테이션이 존재하는 한, 오프라인 검증이 가능합니다. 이 bundle 어노테이션은 키리스 서명의 경우 항상 기본적으로 포함되므로, 기본 cosign sign 기능은 오프라인 검증에 필요한 모든 자료를 포함합니다.

에어갭 환경에서 이미지를 검증하려면, 이미지와 서명이 파일 시스템에 로컬로 존재해야 합니다.

이미지는 cosign save를 사용하여 로컬에 저장할 수 있습니다 (참고: 이 단계는 네트워크 연결이 있는 상태에서 수행해야 합니다):

cosign initialize # This will pull in the latest TUF root
cosign save $IMAGE_NAME --dir ./path/to/dir

이제, 에어갭 환경에서 이 로컬 이미지를 검증할 수 있습니다:

cosign verify \
  --certificate-identity $CERT_IDENTITY \
  --certificate-oidc-issuer $CERT_OIDC_ISSUER \
  --offline=true \
  --new-bundle-format=false \ # for artifacts signed without the new protobuf bundle format
  --trusted-root ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json \ # default location of trusted root
  --local-image ./path/to/dir

$CERT_IDENTITY와 $CERT_OIDC_ISSUER에 대한 예상 값을 전달해야 이 이미지를 올바르게 검증할 수 있습니다. 키페어로 서명한 경우, 공개 키 자료가 로컬에 존재한다면 동일한 명령이 작동합니다:

cosign verify --key cosign.pub --offline --local-image ./path/to/dir

ID 기반 블롭 서명 및 검증

키리스 블롭 서명(--key 없이 cosign sign-blob)을 사용하고 예상 서명자 ID에 대해 검증하세요:

$ cosign sign-blob artifact --bundle artifact.sigstore.json --yes
$ cosign verify-blob artifact \
  --bundle artifact.sigstore.json \
  --certificate-identity "https://github.com/ORG/REPO/.github/workflows/release.yml@refs/heads/main" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

문제 해결

Cosign 사용 중 문제가 발생하면 먼저 최신 릴리스를 사용하고 있는지 확인하세요. Cosign 프로젝트는 최신 릴리스와 v2 시리즈의 마지막 릴리스를 적극적으로 지원합니다.

일반적인 문제와 해결 방법