
cosign v3.1.3
コンテナとバイナリ向けのコード署名と透明性
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 へのコントリビューション、特に bring-your-own keys や署名に関するものは歓迎します。取り組みやすい最初の issue については、issue trackerをご覧ください。
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" ]
クイックスタート
ここでは次の方法を説明します:
- デフォルトの ID ベースの「キーレス署名」方式でコンテナイメージに署名する(詳細はドキュメントを参照)
- コンテナイメージを検証する
- Sigstore Cosign Quickstart で、より広範なキーレス blob 署名/検証のフローを確認する
コンテナに署名し、署名をレジストリに保存する
イメージには常にタグ(: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
証明書のアイデンティティと発行者のフラグには、正規表現を渡すこともできます。--certificate-identity-regexp と --certificate-oidc-issuer-regexp です。
公開鍵に対してコンテナを検証する
このコマンドは、イメージに対して公開鍵に一致する 少なくとも1つ の 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 リポジトリからサービスキーを定期的に要求する必要があります。 パブリックグッドインスタンスを使用した署名のエアギャップ検証を行うには、本番環境の TUF リポジトリから trusted root ファイルを取得する必要があります。このファイルの内容は予告なく変更されます。TUF を使用しない場合、このファイルのエアギャップコピーを最新の状態に保つための独自の仕組みを構築する必要があります。
Cosign は Sigstore bundle を検証することで完全にオフラインでの検証を行うことができます。このバンドルは cosign sign によってレジストリ内のイメージに添付されます。
バンドルには、署名時に生成された検証用の素材(証明書、包含証明付きの透明性ログエントリ、および RFC 3161 タイムスタンプなど)が含まれています。
これらの素材と trusted root のローカルコピーがあれば、検証にネットワークアクセスは不要です。
エアギャップ環境でイメージを検証するには、イメージと署名がローカルファイルシステム上で利用可能である必要があります。
イメージは cosign save を使用してローカルに保存できます(この手順はネットワーク接続のある状態で行う必要があることに注意してください):
cosign initialize # This will pull in the latest TUF root
cosign save $IMAGE_NAME --dir ./path/to/dir
ここで、エアギャップ環境において、このローカルイメージを検証できます:
# --trusted-root points to the default location of the trusted root
cosign verify \
--certificate-identity $CERT_IDENTITY \
--certificate-oidc-issuer $CERT_OIDC_ISSUER \
--trusted-root ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json \
--local-image ./path/to/dir
$CERT_IDENTITY と $CERT_OIDC_ISSUER に期待値を渡して、このイメージを正しく検証する必要があります。
キーペアで署名した場合、公開鍵の素材がローカルに存在することを前提として、同じコマンドが機能します:
cosign verify --key cosign.pub --trusted-root ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json --local-image ./path/to/dir
ID ベースの blob 署名と検証
キーレス blob 署名(--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 シリーズの直前のリリースを積極的にサポートしています。