Cosign

Cosign supports container signing, verification and storage in an OCI registry. Cosign aims to make signatures invisible infrastructure.

Cosign supports:

Hardware and KMS signing
Bring-your-own PKI
Our free OIDC PKI (Fulcio https://github.com/sigstore/fulcio)
Built-in binary transparency and timestamping service (Rekor)
Kubernetes policy enforcement
Rego and Cuelang integrations for policy definition

Cosign is part of the sigstore project. Join us on our Slack channel (need an invite?)

Getting Started

Quick Start

This shows how to:

  1. generate a keypair
  2. sign a container image and store that signature in the registry
  3. find signatures for a container image, and verify them against a public key

See the Usage documentation for detailed information, and see the further usage docs for some fun tips and tricks!

Prereqs

You'll need to install cosign first, and you will need access to a container registry for cosign to work with. To install cosign, see the Installation instructions.

ttl.sh offers free, short-lived (ie: hours), anonymous container image hosting if you just want to try these commands out.

1. Generate a keypair

$ cosign generate-key-pair
Enter password for private key:
Enter again:
Private key written to cosign.key
Public key written to cosign.pub

2. Sign a container and store the signature in the registry

$ cosign sign --key cosign.key dlorenc/demo
Enter password for private key:
Pushing signature to: index.docker.io/dlorenc/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig

The cosign command above prompts the user to enter the password for the private key. The user can either manually enter the password, or if the environment variable COSIGN_PASSWORD is set then it is used automatically.

3. 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.

$ cosign verify --key cosign.pub dlorenc/demo
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}

Kubernetes Integrations

cosign comes with a few builtin Kubernetes integrations: Secret generation and a policy webhook called cosigned. In addition to cosigned, cosign is also compatible with and supported in other policy engines such as:

To learn how to use cosign with Kubernetes, see kubernetes.

More Info

cosign can do lots more than is shown here. To see more information on the commands, checkout the detailed usage.

Other Formats

cosign is primarly for containers and container-related artifacts, but it can also be used for other file types! To learn how to sign SBOMs, WASM modules, Tekton bundles and more, see other types. For basic blobs, see the documentation on working with blobs.

SCM Integration

cosign integrates natively with SCM systems like GitHub and GitLab. You can use the official GitHub Action or use cosign to generate and work safely with SCM secrets with native API integration.

Attestations

In addition to signatures, cosign can be used with In-Toto Attestations. Attestations provide an additional semantic-layer on top of plain cryptographic signatures that can be used in policy systems.

Edit this page on GitHub Updated at Fri, Jun 24, 2022