cosign

# cosign Signing OCI containers (and other artifacts) using [Sigstore](https://sigstore.dev/)! Cosign aims to make signatures **invisible infrastructure**. Cosign supports: * "Keyless signing" with the Sigstore public good Fulcio certificate authority and Rekor transparency log (default) * Hardware and KMS signing * Signing with a cosign generated encrypted private/public keypair * Container Signing, Verification and Storage in an OCI registry. * Bring-your-own PKI ## Info `Cosign` is developed as part of the [`sigstore`](https://sigstore.dev) project. We also use a [slack channel](https://sigstore.slack.com)! Click [here](https://join.slack.com/t/sigstore/shared_invite/zt-47srvpyn6-j8Ek5hGBwKN32IjLw8BvYA) for the invite link. ## Installation For Homebrew, Arch, Nix, GitHub Action, and Kubernetes installs see the [installation docs](https://docs.sigstore.dev/cosign/system_config/installation/). For Linux and macOS binaries see the [GitHub release assets](https://github.com/sigstore/cosign/releases/latest). :rotating_light: If you are downloading releases of cosign from our GCS bucket - please see more information on the July 31, 2023 [deprecation notice](https://blog.sigstore.dev/cosign-releases-bucket-deprecation/) :rotating_light: ## Developer Installation If you have Go 1.22+, you can setup a development environment: ```shell $ git clone https://github.com/sigstore/cosign $ cd cosign $ go install ./cmd/cosign $ $(go env GOPATH)/bin/cosign ``` ## Contributing If you are interested in contributing to `cosign`, please read the [contributing documentation](./CONTRIBUTING.md). Future Cosign development will be focused the next major release which will be based on [sigstore-go](https://github.com/sigstore/sigstore-go). Maintainers will be focused on feature development within sigstore-go. Contributions to sigstore-go, particularly around bring-your-own keys and signing, are appreciated. Please see the [issue tracker](https://github.com/sigstore/sigstore-go/issues) for good first issues. Cosign 2.x is a stable release and will continue to receive periodic feature updates and bug fixes. PRs that are small in scope and size are most likely to be quickly reviewed. PRs which significantly modify or break the API will not be accepted. PRs which are significant in size but do not introduce breaking changes may be accepted, but will be considered lower priority than PRs in sigstore-go. ## Dockerfile Here is how to install and use cosign inside a Dockerfile through the ghcr.io/sigstore/cosign/cosign image: ```shell 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" ] ``` ## Quick Start This shows how to: * sign a container image with the default identity-based "keyless signing" method (see [the documentation for more information](https://docs.sigstore.dev/cosign/signing/overview/)) * verify the container image * explore broader keyless blob signing/verification flows in the [Sigstore Cosign Quickstart](https://docs.sigstore.dev/quickstart/quickstart-cosign/) ### Sign a container and store the signature in the registry Note that you should always sign images based on their digest (`@sha256:...`) rather than a tag (`:latest`) because otherwise you might sign something you didn't intend to! ``` … ``` Cosign will prompt you to authenticate via OIDC, where you'll sign in with your email address. Under the hood, cosign will request a code signing certificate from the Fulcio certificate authority. The subject of the certificate will match the email address you logged in with. Cosign will then store the signature and certificate in the Rekor transparency log, and upload the signature to the OCI registry alongside the image you're signing. ### Verify a container To verify the image, you'll need to pass in the expected certificate subject and certificate issuer via the `--certificate-identity` and `--certificate-oidc-issuer` flags: ``` cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER ``` You can also pass in a regex for the certificate identity and issuer flags, `--certificate-identity-regexp` and `--certificate-oidc-issuer-regexp`. ### Verify a container against a public key This command returns `0` if *at least one* `cosign` formatted signature for the image is found matching the public key. See the detailed usage below for information and caveats on other signature formats. Any valid payloads are printed to stdout, in json format. Note that these signed payloads include the digest of the container image, which is how we can be sure these "detached" signatures cover the correct image. ```shell $ 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} ``` ### Verify a container in an air-gapped environment **Note:** This section is out of date. **Note:** Most verification workflows require periodically requesting service keys from a TUF repository. For airgapped verification of signatures using the public-good instance, you will need to retrieve the [trusted root](https://github.com/sigstore/root-signing/blob/main/targets/trusted_root.json) file from the production TUF repository. The contents of this file will change without notification. By not using TUF, you will need to build your own mechanism to keep your airgapped copy of this file up-to-date. Cosign can do completely offline verification by verifying a [bundle](./specs/SIGNATURE_SPEC.md#properties) which is typically distributed as an annotation on the image manifest. As long as this annotation is present, then offline verification can be done. This bundle annotation is always included by default for keyless signing, so the default `cosign sign` functionality will include all materials needed for offline verification. To verify an image in an air-gapped environment, the image and signatures must be available locally on the filesystem. An image can be saved locally using `cosign save` (note, this step must be done with a network connection): ``` cosign initialize # This will pull in the latest TUF root cosign save $IMAGE_NAME --dir ./path/to/dir ``` Now, in an air-gapped environment, this local image can be verified: ```shell 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 ``` You'll need to pass in expected values for `$CERT_IDENTITY` and `$CERT_OIDC_ISSUER` to correctly verify this image. If you signed with a keypair, the same command will work, assuming the public key material is present locally: ``` cosign verify --key cosign.pub --offline --local-image ./path/to/dir ``` ### Identity-based blob signing and verification Use keyless blob signing (`cosign sign-blob` without `--key`) and verify against the expected signer identity: ```shell $ 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" ``` ### Troubleshooting If you encounter issues with Cosign, first make sure you are using a recent release: The Cosign project actively supports the most recent release as well as the last release in the v2 series. #### Common issues and remedies 1. Verification fails with `failed to verify timestamps: threshold not met for verified log entry integrated timestamps: 0 < 1`: You may be verifying a signature that requires RFC3161 timestamp support * Upgrade to most recent Cosign or * With Cosign 2.6.x, use `--use-signed-timestamps` 1. Verification fails with `no signatures found`: You may be verifying an image signature that requires support for Rekor v2 transparency log * Upgrade to most recent Cosign 1. Signing fails with HTTP errors: Signing with Cosign depends on multiple Sigstore services. Retrying on failure may be a useful workaround if any of these services fail -- filing issues for specific failures is also appreciated #### My problem is something else Please open an [issue](https://github.com/sigstore/cosign/issues/new/choose) or ask in the [slack channel](#info). ## Working with Other Artifacts OCI registries are useful for storing more than just container images! `Cosign` also includes some utilities for publishing generic artifacts, including binaries, scripts, and configuration files using the OCI protocol. This section shows how to leverage these for an easy-to-use, backwards-compatible artifact distribution system that integrates well with the rest of Sigstore. See [the documentation](https://docs.sigstore.dev/cosign/signing/other_types/) for more information. ### Blobs You can publish an artifact with `cosign upload blob`: ``` … ``` Your users can download it from the "direct" url with standard tools like curl or wget: ```shell $ curl -L ttl.sh/v2/$BLOB_NAME/blobs/sha256:$BLOB_SUM > artifact-fetched ``` The digest is baked right into the URL, so they can check that as well: ```shell $ cat artifact-fetched | shasum -a 256 c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626 - ``` You can sign it with the normal `cosign sign` command and flags: ```shell $ cosign sign --key cosign.key $BLOB_URI_DIGEST Enter password for private key: Pushing signature to: ttl.sh/my-artifact-f42c22e0 ``` 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. ``` … ``` #### WASM Web Assembly Modules can also be stored in an OCI registry, using this [specification](https://github.com/solo-io/wasm/tree/master/spec). Cosign can upload these using the `cosign wasm upload` command: ```shell $ cosign upload wasm -f hello.wasm us.gcr.io/dlorenc-vmtest2/wasm $ cosign sign --key cosign.key us.gcr.io/dlorenc-vmtest2/wasm@sha256:9e7a511fb3130ee4641baf1adc0400bed674d4afc3f1b81bb581c3c8f613f812 Enter password for private key: tlog entry created with index: 5198 Pushing signature to: us.gcr.io/dlorenc-vmtest2/wasm:sha256-9e7a511fb3130ee4641baf1adc0400bed674d4afc3f1b81bb581c3c8f613f812.sig ``` #### eBPF [eBPF](https://ebpf.io) modules can also be stored in an OCI registry, using this [specification](https://github.com/solo-io/bumblebee/tree/main/spec). The image below was built using the `bee` tool. More information can be found [here](https://github.com/solo-io/bumblebee/) Cosign can then sign these images as they can any other OCI image. ``` … ``` #### In-Toto Attestations Cosign also has built-in support for [in-toto](https://in-toto.io) attestations. The specification for these is defined [here](https://github.com/in-toto/attestation). You can create and sign one from a local predicate file using the f