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 リポジトリからサービスキーを定期的に要求する必要があります。 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 ベースの 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 シリーズの直前のリリースを積極的にサポートしています。

よくある問題と対処法