## Contributing

`cosign` への貢献に興味がある場合は、[貢献ドキュメント](https://github.com/sigstore/cosign/blob/HEAD/CONTRIBUTING.md) をお読みください。

今後の Cosign 開発は、[sigstore-go](https://github.com/sigstore/sigstore-go) をベースにした次のメジャーリリースに焦点が当てられます。メンテナは sigstore-go 内の機能開発に注力します。特に bring-your-own keys と署名に関する sigstore-go への貢献は歓迎します。最初のイシューに適したものについては、[イシュートラッカー](https://github.com/sigstore/sigstore-go/issues) をご覧ください。

Cosign 2.x は安定版リリースであり、今後も定期的な機能更新とバグ修正が行われます。スコープと規模が小さい PR は、迅速にレビューされる可能性が最も高くなります。

API を大幅に変更または破壊する PR は受け付けられません。規模は大きいが破壊的な変更を導入しない PR は受け入れられる可能性がありますが、sigstore-go の PR よりも優先度は低いと見なされます。

## Dockerfile

ghcr.io/sigstore/cosign/cosign イメージを使用して、Dockerfile 内で cosign をインストールおよび使用する方法は次のとおりです:```shell
FROM ghcr.io/sigstore/cosign/cosign:v2.4.1 as cosign-bin

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

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.

Cosign は OIDC を介した認証を求め、メールアドレスでサインインします。
内部的には、cosign は Fulcio 証明書当局からコード署名証明書を要求します。
証明書のサブジェクトは、ログインに使用したメールアドレスと一致します。
その後、cosign は署名と証明書を Rekor 透過性ログに保存し、署名を署名対象のイメージとともに OCI レジストリにアップロードします。

### コンテナを検証する

イメージを検証するには、`--certificate-identity` フラグと `--certificate-oidc-issuer` フラグを使用して、期待される証明書サブジェクトと証明書発行者を渡す必要があります。```
cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER

### エアギャップ環境でのコンテナの検証

**注:** このセクションは古くなっています。

**注:** ほとんどの検証ワークフローでは、TUFリポジトリからサービスキーを定期的に要求する必要があります。
public-goodインスタンスを使用した署名のエアギャップ検証では、本番の
TUFリポジトリから [trusted root](https://github.com/sigstore/root-signing/blob/main/targets/trusted_root.json) ファイルを取得する必要があります。
このファイルの内容は予告なく変更されます。TUFを使用しない場合、エアギャップ環境用のこのファイルのコピーを最新に保つための独自の仕組みを構築する必要があります。

Cosignは、[バンドル](https://github.com/sigstore/cosign/blob/HEAD/specs/SIGNATURE_SPEC.md#properties) を検証することで、完全にオフラインで検証を行うことができます。これは通常、イメージマニフェストのアノテーションとして配布されます。
このアノテーションが存在する限り、オフライン検証が可能です。
このバンドルアノテーションはキーレス署名の場合にデフォルトで常に含まれるため、デフォルトの `cosign sign` 機能にはオフライン検証に必要なすべての材料が含まれます。

エアギャップ環境でイメージを検証するには、イメージと署名がファイルシステム上でローカルに利用可能である必要があります。

イメージは `cosign save` を使用してローカルに保存できます（注: この手順はネットワーク接続が必要です）:```
cosign initialize # This will pull in the latest TUF root
cosign save $IMAGE_NAME --dir ./path/to/dir

`$CERT_IDENTITY` と `$CERT_OIDC_ISSUER` の期待値を渡して、このイメージを正しく検証する必要があります。キーペアで署名した場合、公開鍵のマテリアルがローカルに存在すれば、同じコマンドが機能します:```
cosign verify --key cosign.pub --offline --local-image ./path/to/dir

### トラブルシューティング

Cosignで問題が発生した場合は、まず最近のリリースを使用していることを確認してください。Cosignプロジェクトは、最新リリースとv2シリーズの最終リリースを積極的にサポートしています。

#### よくある問題とその対処法

1. 検証が `failed to verify timestamps: threshold not met for verified log entry integrated timestamps: 0 < 1` で失敗する場合: RFC3161タイムスタンプのサポートを必要とする署名を検証している可能性があります。
   * 最新のCosignにアップグレードするか、
   * Cosign 2.6.xでは、`--use-signed-timestamps`を使用してください。
1. 検証が `no signatures found` で失敗する場合: Rekor v2透明度ログのサポートを必要とするイメージ署名を検証している可能性があります。
   * 最新のCosignにアップグレードしてください。
1. HTTPエラーで署名が失敗する場合: Cosignでの署名は複数のSigstoreサービスに依存しています。いずれかのサービスが失敗した場合、再試行が有効な回避策となることがあります。特定の失敗についてのissue報告も歓迎します。

#### その他の問題

[issue](https://github.com/sigstore/cosign/issues/new/choose)を開くか、[slackチャンネル](#info)で質問してください。

## 他のアーティファクトの操作

OCIレジストリは、コンテナイメージだけでなく、さまざまなものを保存するのに便利です。
`Cosign`には、OCIプロトコルを使用してバイナリ、スクリプト、設定ファイルなどの一般的なアーティファクトを公開するためのユーティリティも含まれています。

このセクションでは、これらを活用して、Sigstoreの残りの部分とうまく統合できる、使いやすく後方互換性のあるアーティファクト配布システムを構築する方法を示します。

詳細については、[ドキュメント](https://docs.sigstore.dev/cosign/signing/other_types/)を参照してください。

### Blobs

`cosign upload blob` でアーティファクトを公開できます。```shell
$ echo "my first artifact" > artifact
$ BLOB_SUM=$(shasum -a 256 artifact | cut -d' ' -f 1) && echo "$BLOB_SUM"
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626
$ BLOB_NAME=my-artifact-$(uuidgen | head -c 8 | tr 'A-Z' 'a-z')
$ BLOB_URI=ttl.sh/$BLOB_NAME:1h

$ BLOB_URI_DIGEST=$(cosign upload blob -f artifact $BLOB_URI) && echo "$BLOB_URI_DIGEST"
Uploading file from [artifact] to [ttl.sh/my-artifact-f42c22e0:5m] with media type [text/plain]
File [artifact] is available directly at [ttl.sh/v2/my-artifact-f42c22e0/blobs/sha256:c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626]
Uploaded image to:
ttl.sh/my-artifact-f42c22e0@sha256:790d47850411e902aabebc3a684eeb78fcae853d4dd6e1cc554d70db7f05f99f

ダイジェストはURLに直接組み込まれているので、それも確認できます:```shell
$ cat artifact-fetched | shasum -a 256
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626  -

As usual, make sure to reference any images you sign by their digest to make sure you don't sign the wrong thing!

#### Tekton Bundles

[Tekton](https://tekton.dev) bundles can be uploaded and managed within an OCI registry.
The specification is [here](https://tekton.dev/docs/pipelines/tekton-bundle-contracts/).
This means they can also be signed and verified with `cosign`.

Tekton Bundles can currently be uploaded with the [tkn cli](https://github.com/tektoncd/cli), but we may add this support to
`cosign` in the future.```shell
$ tkn bundle push us.gcr.io/dlorenc-vmtest2/pipeline:latest -f task-output-image.yaml
Creating Tekton Bundle:
        - Added TaskRun:  to image

Pushed Tekton Bundle to us.gcr.io/dlorenc-vmtest2/pipeline@sha256:124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155
$ cosign sign --key cosign.key us.gcr.io/dlorenc-vmtest2/pipeline@sha256:124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155
Enter password for private key:
tlog entry created with index: 5086
Pushing signature to: us.gcr.io/dlorenc-vmtest2/demo:sha256-124e1fdee94fe5c5f902bc94da2d6e2fea243934c74e76c2368acdc8d3ac7155.sig

#### eBPF

[eBPF](https://ebpf.io) モジュールは、この [仕様](https://github.com/solo-io/bumblebee/tree/main/spec) を使用して OCI レジストリに保存することもできます。

以下のイメージは `bee` ツールを使用して構築されました。詳細は [こちら](https://github.com/solo-io/bumblebee/) で確認できます。

Cosign は、他の OCI イメージと同様に、これらのイメージに署名できます。```shell
$ bee build ./examples/tcpconnect/tcpconnect.c localhost:5000/tcpconnect:test
$ bee push localhost:5000/tcpconnect:test
$ cosign sign  --key cosign.key localhost:5000/tcpconnect@sha256:7a91c50d922925f152fec96ed1d84b7bc6b2079c169d68826f6cf307f22d40e6
Enter password for private key:
Pushing signature to: localhost:5000/tcpconnect
$ cosign verify --key cosign.pub localhost:5000/tcpconnect:test

Verification for localhost:5000/tcpconnect:test --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key

[{"critical":{"identity":{"docker-reference":"localhost:5000/tcpconnect"},"image":{"docker-manifest-digest":"sha256:7a91c50d922925f152fec96ed1d84b7bc6b2079c169d68826f6cf307f22d40e6"},"type":"cosign container image signature"},"optional":null}]

標準の鍵管理システムはすべてサポートされています。

ペイロードは、[ここ](https://github.com/secure-systems-lab/dsse)で定義されているDSSE署名仕様を使用して署名されます。

検証するには:```shell
$ cosign verify-attestation --key cosign.pub $IMAGE_URI

問題があれば、テストしてバグを報告してください。
手順は[トラッキングイシュー](https://github.com/sigstore/cosign/issues/40)にあります。

## 注意事項

### 意図的に欠落している機能

`cosign` は、一時的な鍵なし署名と管理された鍵署名の両方において、ECDSA-P256鍵のみを生成し、SHA256ハッシュを使用します。
鍵はPEMエンコードされたPKCS8形式で保存されます。
ただし、`cosign` を使用して、任意のアルゴリズムの任意の形式で署名を保存および取得できます。

### おそらく変更すべき点

#### ペイロード形式

`cosign` はペイロード形式としてRed Hatの[シンプル署名](https://www.redhat.com/en/blog/container-image-signing)のみをサポートしています。
それは次のようになります:```json
{
    "critical": {
           "identity": {
               "docker-reference": "testing/manifest"
           },
           "image": {
               "Docker-manifest-digest": "sha256:20be...fe55"
           },
           "type": "cosign container image signature"
    },
    "optional": {
           "creator": "Bob the Builder",
           "timestamp": 1458239713
    }
}

したがって、`gcr.io/dlorenc-vmtest2/demo` の署名は `gcr.io/my-new-repo/demo:sha256-DIGEST.sig` に保存されます。

注: レジストリによっては、「リポジトリ」に異なる形式を期待する場合があります。

* [GCR](https://cloud.google.com/container-registry) を使用する場合、上記の例のように `gcr.io/$REPO` のようなレジストリ名で十分です。
* [Artifact Registry](https://cloud.google.com/artifact-registry) を使用する場合は、
  `$LOCATION-docker.pkg.dev/$PROJECT/$REPO/$STORAGE_IMAGE` のような完全なイメージ名を指定してください。単なる
  リポジトリではありません。たとえば、  ```shell
  $ export COSIGN_REPOSITORY=us-docker.pkg.dev/my-new-repo/demo
  $ cosign sign --key cosign.key $IMAGE_URI_DIGEST

公開鍵は、`PUBLIC KEY` というヘッダーを持つ PEM エンコードされた標準 PKIX 形式でディスクに格納されます。```
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELigCnlLNKgOglRTx1D7JhI7eRw99
QolE9Jo4QUxnbMy5nUuBL+UZF9qqfm/Dg1BNeHRThHzWh2ki9vAEgWEDOw==
-----END PUBLIC KEY-----

さあ、署名しましょう！もちろん `cosign` を使って：```shell
$ cosign sign --key cosign.key us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact@sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef
Enter password for private key:
Pushing signature to: us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact:sha256-551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef.sig

## FAQ

### Notary v2 を使わない理由

簡単には答えにくいです。
この投稿にいくつかの比較があります:

[Notary V2 と Cosign](https://medium.com/@dlorenc/notary-v2-and-cosign-b816658f044d)

他にも比較記事を見つけたら、ここに PR を送ってください。すべてリンクします。

### containers/image 署名を使わない理由

`containers/image` 署名は `cosign` に近く、ペイロード形式を再利用しています。
`cosign` が異なる点は、PGP ではなく ECDSA-P256 キーで署名し、
署名をレジストリに保存することです。

### TUF を使わない理由?

このツールは TUF を補完するものであり、一緒に使えると信じています。
まだ試していませんが、TUF のストレージにもレジストリを再利用できると思います。

## 設計要件

* 署名の保存、照会、取得のための外部サービスは不要
* 可能な限り多くのレジストリをサポートすることを目指す
* すべてがレジストリ API 上で動作するべき
* PGP はまったく不要であるべき
* ユーザーはイメージのすべての署名を見つけられる必要がある
* 署名者は push 後にイメージに署名できる
* 複数のエンティティがイメージに署名できる
* イメージへの署名はイメージを変更しない
* Pure Go 実装

## 将来のアイデア

### レジストリ API の変更

レジストリにものを保存するために使う命名規則と read-modify-write 更新パターンは、
まあ、少し"ハッキー"です。
今日利用できる最良の（唯一の）現実的な選択肢だと思いますが、レジストリ API が変われば
これらを改善できます。

### 他のタイプ

`cosign` はレジストリ内のあらゆるものに署名できます。
これらの例は単一イメージへの署名を示していますが、マルチプラットフォームの `Index` や
他のあらゆる種類のアーティファクトにも署名できます。
これには Helm Charts、Tekton Pipelines、および現在 OCI レジストリを配布に使っている
その他すべてのものが含まれます。

これは、新しいアーティファクトタイプをレジストリにアップロードして署名できることも意味します。
保存して署名する興味深いタイプの1つは、TUF リポジトリでしょう。
まだ試していませんが、TUF はこの上に実装できるとかなり確信しています。

### タグ署名

`cosign` 署名は、レジストリに保存されたオブジェクトのダイジェストを保護します。
オプションの `annotations` サポート（`cosign sign` の `-a` フラグ経由）を使うと、
署名され保護されるペイロードに追加データを加えることができます。
このユースケースの1つは、タグからダイジェストへのマッピングに署名することかもしれません。

特定のタグ（または一連のタグ）がダイジェストを指すべきであることを証明したい場合は、
次のように実行できます:```shell
$ docker push $IMAGE_URI
The push refers to repository [dlorenc/demo]
994393dc58e7: Pushed
5m: digest: sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870 size: 528
$ TAG=sign-me
$ cosign sign --key cosign.key -a tag=$TAG $IMAGE_URI_DIGEST
Enter password for private key:
Pushing signature to: dlorenc/demo:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870.sig

ここにタイムスタンプを追加して、TUFスタイルのフリーズ攻撃防止を実装することもできます。

### ベースイメージ/レイヤーの署名

繰り返しになりますが、`cosign` はレジストリ内のあらゆるものに署名できます。
ベースイメージとしての使用を意図したイメージに `cosign` で署名し、
その来歴（provenance）メタデータを、結果として得られる派生イメージに含めることができます。
これにより、イメージが承認されたベースイメージから構築されたことを強制できます。

大まかなアイデア:
* OCIマニフェストには、注釈（annotations）を含めることができる `layer` `Descriptors` の順序付きリストがあります。
  仕様については、[こちら](https://github.com/opencontainers/image-spec/blob/master/manifest.md)を
  参照してください。
* ベースイメージは、他のレイヤーが追加される順序付きレイヤーのリストであると同時に、
  変更される初期設定オブジェクトでもあります。
  * 派生イメージは、ベースイメージの設定を完全に削除/破棄/再作成できるため、
    設定に署名しても価値は限定的です。
* 順序付けられたベースレイヤーの完全なセットに署名し、その署名を注釈として、
  結果として得られる子イメージの**最後の**レイヤーに添付できます。

このサンプルマニフェストは、2つのレイヤーを持つベースイメージから構築されたイメージを
表しています。
さらに1つのレイヤーが追加され、最終イメージが構成されます。```json
{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "size": 7023,
    "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7"
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 32654,
      "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0"
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 16724,
      "digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b",
      "annotations": {
        "dev.cosign.signature.baseimage": "Ejy6ipGJjUzMDoQFePWixqPBYF0iSnIvpMWps3mlcYNSEcRRZelL7GzimKXaMjxfhy5bshNGvDT5QoUJ0tqUAg=="
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "size": 73109,
      "digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736"
    }
  ],
}

<!-- TODO: https://github.com/sigstore/cosign/issues/2333 -->

では、その署名に覚えやすい名前を付け、それに署名してください:```shell
$ crane tag $(cosign triangulate $IMAGE_URI) mysignature
2021/02/15 20:22:55 dlorenc/demo:mysignature: digest: sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e size: 556
$ cosign sign --key cosign.key -a sig=counter dlorenc/demo:mysignature
Enter password for private key:
Pushing signature to: dlorenc/demo:sha256-71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e.sig
$ cosign verify --key cosign.pub dlorenc/demo:mysignature
{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e"},"Type":"cosign container image signature"},"Optional":{"sig":"counter"}}

## リリース頻度

必要に応じてリリースを実施します。パッチリリースは小さなバグを修正するために実施されます。マイナーリリースは、
複数のバグ修正や機能追加がある場合に定期的に実施されます。メジャーリリースは、
破壊的な変更がある場合にリリースされます。

## セキュリティ

セキュリティ上の問題を発見した場合は、sigstore の[セキュリティ
プロセス](https://github.com/sigstore/.github/blob/main/SECURITY.md)を参照してください。

## GitHub リリースアセット内のバンドルファイル

`cosign` の GitHub リリースアセットには、リリースバイナリの整合性の検証に使用される cosign blob への署名中に [GoReleaser](https://github.com/sigstore/cosign/blob/ac999344eb381ae91455b0a9c5c267e747608d76/.goreleaser.yml#L166) によって生成された Sigstore バンドルファイルが含まれています。このファイルは cosign 自体では使用されませんが、[リリースバイナリの整合性を検証](https://docs.sigstore.dev/cosign/system_config/installation/#verifying-cosign-with-artifact-key)したいユーザーのために提供されています。