Cosign

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

Cosign supports:

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

Getting Started (Quick Start)

To get up and running we'll demonstrate 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

Prerequisites

You'll need to install Cosign first, and you will need access to a container registry.

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

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 user/demo
Enter password for private key:
Pushing signature to: index.docker.io/user/demo:sha256-87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8.sig

The cosign command above prompts the user to enter the password for the private key. The user can manually enter the password, or set an environment variable with COSIGN_PASSWORD to use a password 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. Review the other sections of this site 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 built-in Kubernetes integrations: Secret generation, and a policy webhook policy-controller. In addition to the policy-controller, Cosign is also compatible with and supported by other policy engines such as:

• Conaisseur
• Kyverno
• OPA Gatekeeper

To learn how to use Cosign with Kubernetes, review Kubernetes.

More Info

Cosign can do much more than what is discussed here. Review more information on the commands by checking out the other sections of this site.

Other Formats

Cosign is useful not only for containers and container-related artifacts; it can also be used for other file types.

To learn how to sign SBOMs, WASM modules, Tekton bundles and more, review Signing Other Types. For basic blobs, review Working with Blobs.

SCM Integration

Cosign integrates natively with source code management (SCM) systems like GitHub and GitLab. You can use the official GitHub Actions Cosign installer 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.