cosign: a tool for Container Signing, Verification and Storage in an OCI registry (Sigstore cosign)
cosign generate-key-pair [--output-key-prefix NAME]
cosign sign --key cosign.key [-y] IMAGE@DIGEST
cosign verify --key cosign.pub IMAGE...
cosign version
What it does
Signs container images and verifies their signatures. With a key pair, sign signs the image's manifest digest with the private key; verify checks the signatures attached to the image against the public key. In v3 a signature travels as a Sigstore bundle attached to the image as an OCI 1.1 referrer, and signing uploads an entry to the Rekor transparency log by default.
Options you will use
--key PATH- sign: path to the private key file, KMS URI or Kubernetes Secret. verify: path to the public key file, KMS URI or Kubernetes Secret.
-y, --yes- Skip confirmation prompts for non-destructive operations.
-a, --annotations KEY=VALUE- Extra key=value pairs to sign (verify: annotations that must be present).
-r, --recursive- sign: if a multi-arch image is specified, additionally sign each discrete image.
--upload- sign: whether to upload the signature (default true).
--bundle FILE- sign: write everything required to verify the image to FILE.
--tlog-upload- sign: whether or not to upload to the tlog (default true). Deprecated in v3: prefer a --signing-config file with no transparency log services.
--insecure-ignore-tlog- verify: ignore transparency log verification, to be used when an artifact signature has not been uploaded to the transparency log. Artifacts cannot be publicly verified when not included in a log.
--certificate-identity ID- verify (keyless): the identity expected in a valid Fulcio certificate (email, DNS name, IP or URI).
--certificate-oidc-issuer URL- verify (keyless): the OIDC issuer expected in a valid Fulcio certificate, e.g. https://token.actions.githubusercontent.com.
--check-claims- verify: whether to check the claims found (default true).
-o, --output FORMAT- verify: output format for the signing image information (json|text) (default "json").
--output-key-prefix NAME- generate-key-pair: name used for generated .pub and .key files (defaults to cosign).
--kms URI- generate-key-pair: create key pair in KMS service to use for signing.
-t, --timeout DURATION- Timeout for commands (default 3m0s).
-d, --verbose- Log debug output.
Examples
$ COSIGN_PASSWORD= cosign generate-key-paircosign.key + cosign.pub in the current directory
$ cosign sign --key cosign.key -y registry.lab/shop/api@sha256:<digest>sign by digest, no prompt
$ cosign verify --key cosign.pub registry.lab/shop/api:2.3is this image signed with our key?
Gotchas
- Sign the image by its digest (@sha256:...) rather than by tag so that you actually sign what you think you're signing: cosign resolves a tag to a digest and the signature belongs to that digest, so a tag moved to another build has no signature.
- generate-key-pair interactively prompts for a password; the COSIGN_PASSWORD environment variable provides one (COSIGN_PASSWORD= for an empty one in a lab).
- A key-based sign in v3 uploads an entry to the public Rekor transparency log and asks first (the Sigstore privacy statement); -y answers yes.
- verify prints the checks it performed on stderr and the verified claims as JSON on stdout; no signature or a wrong key = a non-zero exit, which is what an admission policy or a CI step relies on.
On the blog
Try cosign in a real terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.