Technical Documentation: sigstore/cosign

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

cosign

Signing OCI containers (and other artifacts) using Sigstore!

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 project.
We also use a slack channel!
Click here for the invite link.

Installation

For Homebrew, Arch, Nix, GitHub Action, and Kubernetes installs see the installation docs.

For Linux, macOS and Windows binaries, see the GitHub release assets.

:rotating_light: If you are downloading releases of cosign from our GCS bucket - please see more information on the July 31, 2023 deprecation notice :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.

Future Cosign development will be focused the next major release which will be based on
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 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)
verify the container image
explore broader keyless blob signing/verification flows in the Sigstore Cosign Quickstart

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!

shell

cosign sign $IMAGE

Generating ephemeral keys...
Retrieving signed certificate...

	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.

By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs.
Are you sure you would like to continue? [y/N] y
Your browser will now be opened to:
https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&code_challenge=OrXitVKUZm2lEWHVt1oQWR4HZvn0rSlKhLcltglYxCY&code_challenge_method=S256&nonce=2KvOWeTFxYfxyzHtssvlIXmY6Jk&redirect_uri=http%3A%2F%2Flocalhost%3A57102%2Fauth%2Fcallback&response_type=code&scope=openid+email&state=2KvOWfbQJ1caqScgjwibzK2qJmb
Successfully verified SCT...
tlog entry created with index: 12086900
Pushing signature to: $IMAGE

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:

text

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 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 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):

text

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:

text

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

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
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
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 or ask in the slack channel.

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 for more information.

Blobs

You can publish an artifact with 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

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 bundles can be uploaded and managed within an OCI registry.
The specification is here.
This means they can also be signed and verified with cosign.

Tekton Bundles can currently be uploaded with the tkn 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

WASM

Web Assembly Modules can also be stored in an OCI registry, using this specification.

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 modules can also be stored in an OCI registry, using this specification.

The image below was built using the bee tool. More information can be found here

Cosign can then sign these images as they can any other OCI image.

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}]

In-Toto Attestations

Cosign also has built-in support for in-toto attestations.
The specification for these is defined here.

You can create and sign one from a local predicate file using the following commands:

shell

$ cosign attest --predicate <file> --key cosign.key $IMAGE_URI_DIGEST

All of the standard key management systems are supported.
Payloads are signed using the DSSE signing spec, defined here.

To verify:

shell

$ cosign verify-attestation --key cosign.pub $IMAGE_URI

Detailed Usage

See the Usage documentation for more information.

Hardware-based Tokens

See the Hardware Tokens documentation for information on how to use cosign with hardware.

Registry Support

cosign uses go-containerregistry for registry
interactions, which has generally excellent compatibility, but some registries may have quirks.

Today, cosign has been tested and works against the following registries:

AWS Elastic Container Registry
GCP's Artifact Registry and Container Registry
Docker Hub
Azure Container Registry
JFrog Artifactory Container Registry
The CNCF distribution/distribution Registry
GitLab Container Registry
GitHub Container Registry
The CNCF Harbor Registry
Digital Ocean Container Registry
Sonatype Nexus Container Registry
Alibaba Cloud Container Registry
Red Hat Quay Container Registry 3.6+ / Red Hat quay.io
Elastic Container Registry
IBM Cloud Container Registry
Cloudsmith Container Registry
The CNCF zot Registry
OVHcloud Managed Private Registry

We aim for wide registry support. To sign images in registries which do not yet fully support OCI media types, one may need to use COSIGN_DOCKER_MEDIA_TYPES to fall back to legacy equivalents. For example:

shell

COSIGN_DOCKER_MEDIA_TYPES=1 cosign sign --key cosign.key legacy-registry.example.com/my/image@$DIGEST

Please help test and file bugs if you see issues!
Instructions can be found in the tracking issue.

Caveats

Intentionally Missing Features

cosign only generates ECDSA-P256 keys and uses SHA256 hashes, for both ephemeral keyless signing and managed key signing.
Keys are stored in PEM-encoded PKCS8 format.
However, you can use cosign to store and retrieve signatures in any format, from any algorithm.

Things That Should Probably Change

Payload Formats

cosign only supports Red Hat's simple signing
format for payloads.
That looks like:

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
    }
}

Note: This can be generated for an image reference using cosign generate $IMAGE_URI_DIGEST.

I'm happy to switch this format to something else if it makes sense.
See https://github.com/notaryproject/notation/issues/40 for one option.

Registry Details

cosign signatures are stored as separate objects in the OCI registry, with only a weak
reference back to the object they "sign".
This means this relationship is opaque to the registry, and signatures will not be deleted
or garbage-collected when the image is deleted.
Similarly, they can easily be copied from one environment to another, but this is not
automatic.

Multiple signatures are stored in a list which is unfortunately a race condition today.
To add a signature, clients orchestrate a "read-append-write" operation, so the last write
will win in the case of contention.

Specifying Registry

cosign will default to storing signatures in the same repo as the image it is signing.
To specify a different repo for signatures, you can set the COSIGN_REPOSITORY environment variable.

This will replace the repo in the provided image like this:

shell

$ export COSIGN_REPOSITORY=gcr.io/my-new-repo
$ cosign sign --key cosign.key $IMAGE_URI_DIGEST

So the signature for gcr.io/dlorenc-vmtest2/demo will be stored in gcr.io/my-new-repo/demo:sha256-DIGEST.sig.

Note: different registries might expect different formats for the "repository."

To use GCR, a registry name
like gcr.io/$REPO is sufficient, as in the example above.
To use Artifact Registry,
specify a full image name like
$LOCATION-docker.pkg.dev/$PROJECT/$REPO/$STORAGE_IMAGE, not just a
repository. For example,
shell
```
$ export COSIGN_REPOSITORY=us-docker.pkg.dev/my-new-repo/demo
$ cosign sign --key cosign.key $IMAGE_URI_DIGEST
```
where the sha256-DIGEST will match the digest for
gcr.io/dlorenc-vmtest2/demo. Specifying just a repo like
$LOCATION-docker.pkg.dev/$PROJECT/$REPO will not work in Artifact Registry.

Signature Specification

cosign is inspired by tools like minisign and
signify.

Generated private keys are stored in PEM format.
The keys encrypted under a password using scrypt as a KDF and nacl/secretbox for encryption.

They have a PEM header of ENCRYPTED SIGSTORE PRIVATE KEY:

shell

-----BEGIN ENCRYPTED SIGSTORE PRIVATE KEY-----
...
-----END ENCRYPTED SIGSTORE PRIVATE KEY-----

Public keys are stored on disk in PEM-encoded standard PKIX format with a header of PUBLIC KEY.

text

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAELigCnlLNKgOglRTx1D7JhI7eRw99
QolE9Jo4QUxnbMy5nUuBL+UZF9qqfm/Dg1BNeHRThHzWh2ki9vAEgWEDOw==
-----END PUBLIC KEY-----

Storage Specification

cosign stores signatures in an OCI registry, and uses a naming convention (tag based
on the sha256 of what we're signing) for locating the signature index.

reg.example.com/ubuntu@sha256:703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715 has signatures located at reg.example.com/ubuntu:sha256-703218c0465075f4425e58fac086e09e1de5c340b12976ab9eb8ad26615c3715.sig

Roughly (ignoring ports in the hostname): s/:/-/g and s/@/:/g to find the signature index.

See Race conditions for some caveats around this strategy.

Alternative implementations could use transparency logs, local filesystem, a separate repository
registry, an explicit reference to a signature index, a new registry API, grafeas, etc.

Signing subjects

cosign only works for artifacts stored as "manifests" in the registry today.
The proposed mechanism is flexible enough to support signing arbitrary things.

KMS Support

cosign supports using a KMS provider to generate and sign keys.
Right now cosign supports Hashicorp Vault, AWS KMS, GCP KMS, Azure Key Vault and we are hoping to support more in the future!

Additional KMS providers are available as external plugins, such as OVHcloud KMS.

See the KMS docs for more details.

OCI Artifacts

Push an artifact to a registry using oras (in this case, cosign itself!):

shell

$ oras push us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact ./cosign
Uploading f53604826795 cosign
Pushed us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact
Digest: sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef

Now sign it! Using cosign of course:

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

Finally, verify cosign with cosign again:

shell

$ cosign verify --key cosign.pub  us-central1-docker.pkg.dev/dlorenc-vmtest2/test/artifact@sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The claims were present in the transparency log
  - The signatures were integrated into the transparency log when the certificate was valid
  - The signatures were verified against the specified public key
  - The code-signing certificate was verified using trusted certificate authority certificates

{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:551e6cce7ed2e5c914998f931b277bc879e675b74843e6f29bc17f3b5f692bef"},"Type":"cosign container image signature"},"Optional":null}

FAQ

Why not use Notary v2

It's hard to answer this briefly.
This post contains some comparisons:

Notary V2 and Cosign

If you find other comparison posts, please send a PR here and we'll link them all.

Why not use containers/image signing

containers/image signing is close to cosign, and we reuse payload formats.
cosign differs in that it signs with ECDSA-P256 keys instead of PGP, and stores
signatures in the registry.

Why not use TUF?

I believe this tool is complementary to TUF, and they can be used together.
I haven't tried yet, but think we can also reuse a registry for TUF storage.

Design Requirements

No external services for signature storage, querying, or retrieval
We aim for as much registry support as possible
Everything should work over the registry API
PGP should not be required at all.
Users must be able to find all signatures for an image
Signers can sign an image after push
Multiple entities can sign an image
Signing an image does not mutate the image
Pure-go implementation

Future Ideas

Registry API Changes

The naming convention and read-modify-write update patterns we use to store things in
a registry are a bit, well, "hacky".
I think they're the best (only) real option available today, but if the registry API
changes we can improve these.

Other Types

cosign can sign anything in a registry.
These examples show signing a single image, but you could also sign a multi-platform Index,
or any other type of artifact.
This includes Helm Charts, Tekton Pipelines, and anything else currently using OCI registries
for distribution.

This also means new artifact types can be uploaded to a registry and signed.
One interesting type to store and sign would be TUF repositories.
I haven't tried yet, but I'm fairly certain TUF could be implemented on top of this.

Tag Signing

cosign signatures protect the digests of objects stored in a registry.
The optional annotations support (via the -a flag to cosign sign) can be used to add extra
data to the payload that is signed and protected by the signature.
One use-case for this might be to sign a tag->digest mapping.

If you would like to attest that a specific tag (or set of tags) should point at a digest, you can
run something like:

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

Then you can verify that the tag->digest mapping is also covered in the signature, using the -a flag to cosign verify.
This example verifies that the digest $TAG which points to (sha256:1304f174557314a7ed9eddb4eab12fed12cb0cd9809e4c28f29af86979a3c870)
has been signed, and also that the tag annotation has the value sign-me:

shell

$ cosign verify --key cosign.pub -a tag=$TAG $IMAGE_URI | jq .
{
  "Critical": {
    "Identity": {
      "docker-reference": ""
    },
    "Image": {
      "Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36"
    },
    "Type": "cosign container image signature"
  },
  "Optional": {
    "tag": "sign-me"
  }
}

Timestamps could also be added here, to implement TUF-style freeze-attack prevention.

Base Image/Layer Signing

Again, cosign can sign anything in a registry.
You could use cosign to sign an image that is intended to be used as a base image,
and include that provenance metadata in resulting derived images.
This could be used to enforce that an image was built from an authorized base image.

Rough Idea:

OCI manifests have an ordered list of layer Descriptors, which can contain annotations.
See here for the
specification.
A base image is an ordered list of layers to which other layers are appended, as well as an
initial configuration object that is mutated.
- A derived image is free to completely delete/destroy/recreate the config from its base image,
  so signing the config would provided limited value.
We can sign the full set of ordered base layers, and attach that signature as an annotation to
the last layer in the resulting child image.

This example manifest manifest represents an image that has been built from a base image with two
layers.
One additional layer is added, forming the final image.

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"
    }
  ],
}

Note that this could be applied recursively, for multiple intermediate base images.

Counter-Signing

Cosign signatures (and their protected payloads) are stored as artifacts in a registry.
These signature objects can also be signed, resulting in a new, "counter-signature" artifact.
This "counter-signature" protects the signature (or set of signatures) and the referenced artifact, which allows
it to act as an attestation to the signature(s) themselves.

Before we sign the signature artifact, we first give it a memorable name so we can find it later.

shell

$ cosign sign --key cosign.key -a sig=original $IMAGE_URI_DIGEST
Enter password for private key:
Pushing signature to: dlorenc/demo:sha256-97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36.sig
$ cosign verify --key cosign.pub dlorenc/demo | jq .
{
  "Critical": {
    "Identity": {
      "docker-reference": ""
    },
    "Image": {
      "Docker-manifest-digest": "97fc222cee7991b5b061d4d4afdb5f3428fcb0c9054e1690313786befa1e4e36"
    },
    "Type": "cosign container image signature"
  },
  "Optional": {
    "sig": "original"
  }
}

Now give that signature a memorable name, then sign that:

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"}}

Finally, check the original signature:

shell

$ crane manifest dlorenc/demo@sha256:71f70e5d29bde87f988740665257c35b1c6f52dafa20fab4ba16b3b1f4c6ba0e
{
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "size": 233,
    "digest": "sha256:3b25a088710d03f39be26629d22eb68cd277a01673b9cb461c4c24fbf8c81c89"
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.descriptor.v1+json",
      "size": 217,
      "digest": "sha256:0e79a356609f038089088ec46fd95f4649d04de989487220b1a0adbcc63fadae",
      "annotations": {
        "dev.sigstore.cosign/signature": "5uNZKEP9rm8zxAL0VVX7McMmyArzLqtxMTNPjPO2ns+5GJpBeXg+i9ILU+WjmGAKBCqiexTxzLC1/nkOzD4cDA=="
      }
    }
  ]
}

Release Cadence

We cut releases as needed. Patch releases are cut to fix small bugs. Minor releases are
cut periodically when there are multiple bugs fixed or features added. Major releases
will be released when there are breaking features.

Security

Should you discover any security issues, please refer to sigstore's security
process

Bundle files in GitHub Release Assets

The GitHub release assets for cosign contain Sigstore bundle files produced by GoReleaser while signing the cosign blob that is used to verify the integrity of the release binaries. This file is not used by cosign itself, but is provided for users who wish to verify the integrity of the release binaries.

Overview (`release/README.md`)

Release

This directory contain the files and scripts to run a cosign release.

Cutting a Cosign Release

Release notes: Create a PR to update and review release notes in CHANGELOG.md.

Check merged pull requests since the last release and make sure enhancements, bug fixes, and authors are reflected in the notes.

You can get a list of pull requests since the last release by substituting in the date of the last release and running:

text

git log --pretty="* %s" --after="YYYY-MM-DD"

and a list of authors by running:

text

git log --pretty="* %an" --after="YYYY-MM-DD" | sort -u

Open a Pull Request to update CHANGELOG.md
Tag the repository

WARNING: Tags should not be updated to a new ref or deleted/recreated after creation. Go provides a checksum database
that persists an immutable mapping between version and ref, and updating the tag will break clients that have already downloaded the release.

shell

$ export RELEASE_TAG=<release version, eg "v2.0.2">
$ git tag -s ${RELEASE_TAG} -m "${RELEASE_TAG}"
$ git push upstream ${RELEASE_TAG}

Note that upstream should be the upstream sigstore/cosign repository. You may have to change this if you've configured remotes.

Then go to the Actions tab and click on the Cut Release workflow. Note you need
to be in this list to trigger this workflow.

Click to run a workflow and insert the following parameters:

Release tag: the tag that use pushed for the release
Key ring for cosign key: the value is release-cosign
Key name for cosign key: the value is cosign

That will trigger a CloudBuild job and will run the release using goreleaser, which will publish images to
gcr.io and ghcr.io, and the binaries will be available in the GitHub release.

If you have permissions to access the project, you can follow the CloudBuild job in the projectsigstore(https://console.cloud.google.com/cloud-build/builds?project=projectsigstore) GCP Project.

As the last step of the CloudBuild job, goreleaser will create a draft release in GitHub.

Navigate to the Draft Release in the Github repository. Click the Publish Release button to make the Release available.

You might want/need to add any extra notes/breaking changes notices, upgrade paths.

Post on the #general and #cosign Slack channels.
If it's a significant release, send an announcement email to [email protected] mailing list.

Overview (`test/README.md`)

Cosign E2E Tests

How to add end-to-end tests for cosign:

General-purpose tests

If the test is only testing cosign itself or only needs access to Rekor and/or
Fulcio, add it to e2e_test.go. This test suite is run by the e2e_test.sh
script, which sets up Rekor, Fulcio, and an OIDC provider, so this can easily be
run in a developer environment with no additional setup steps.

In your tests, where cosign calls out to Fulcio or Rekor, make sure to set the
service URLs to the constants rekorURL or fulcioURL, which point to the
local instances of Rekor and Fulcio. Also have the test call the setLocalEnv
which downloads keys from the ephemeral Sigstore services and configures cosign
to trust them.

Environment-specific tests

If the test needs a more specific kind of environment, such as a KMS or an image
registry, create the test in its own file and designate a go:build tag for it.
In e2e_test.go, add a negation for that build tag.

In your tests, set the Rekor and Fulcio URLs to the contents of the environment
variables REKOR_URL and FULCIO_URL, if Rekor and Fulcio are needed for the
test.

Add a job for the new test in the e2e-test.yml GitHub workflow file. The job
should include the following:

If the test needs access to Sigstore services, a step that calls the
sigstore/scaffolding/actions/setup action
Steps to do whatever other custom configuration the scenario needs
A step to run the test with go test -tags=e2e,<your tag> -v ./test/...

To run these kinds of tests tests locally, you'll have to setup
scaffolding
and do the other setup steps manually.

Dos

Add E2E tests to cover any interaction that cosign has with an external service,
such as Rekor, Fulcio, a TSA, etc, or for any case where it's not possible to
cover the functionality with a unit test.

Don'ts

Do not add shell scripts that call the cosign binary directly unless the
functionality under test is the CLI itself and absolutely cannot be tested any
other way. As much as possible, tests should be runnable with go test.
Do not allow the tests to call the production or staging instances of the
Sigstore services, i.e. any *.sigstore.dev or *.sigstage.dev services.
They should use the local CI instances to avoid spamming the real
infrastructure.

Doc Cosign (`doc/cosign.md`)

cosign

A tool for Container Signing, Verification and Storage in an OCI registry

Options

text

-h, --help                 help for cosign
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Attest Blob (`doc/cosign_attest-blob.md`)

cosign attest-blob

Attest the supplied blob

text

cosign attest-blob [flags]

Examples

text

cosign attest-blob --key <key path>|<kms uri> [--predicate <path>] [--a key=value] [--f] [--r] <BLOB uri>

  # attach an attestation to a blob with a local key pair file and write the bundle to a file
  cosign attest-blob --predicate <FILE> --type <TYPE> --key cosign.key --bundle <path> <BLOB>

  # attach an attestation to a blob with a key pair stored in Azure Key Vault
  cosign attest-blob --predicate <FILE> --type <TYPE> --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] <BLOB>

  # attach an attestation to a blob with a key pair stored in AWS KMS
  cosign attest-blob --predicate <FILE> --type <TYPE> --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] <BLOB>

  # attach an attestation to a blob with a key pair stored in Google Cloud KMS
  cosign attest-blob --predicate <FILE> --type <TYPE> --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY]/versions/[VERSION] <BLOB>

  # attach an attestation to a blob with a key pair stored in Hashicorp Vault
  cosign attest-blob --predicate <FILE> --type <TYPE> --key hashivault://[KEY] <BLOB>

  # supply attestation via stdin
  echo <PAYLOAD> | cosign attest-blob --predicate - --yes

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Attest (`doc/cosign_attest.md`)

cosign attest

Attest the supplied container image

text

cosign attest [flags]

Examples

text

/* Detailed source-code truncated for AI context efficiency. */

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Bundle (`doc/cosign_bundle.md`)

cosign bundle

Interact with a Sigstore protobuf bundle

Synopsis

Tools for interacting with a Sigstore protobuf bundle

Options

text

-h, --help   help for bundle

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Bundle Create From Container (`doc/cosign_bundle_create-from-container.md`)

cosign bundle create-from-container

Create Sigstore protobuf bundles from legacy container attestations

Synopsis

Create Sigstore protobuf bundles from attestations stored in the
legacy tag-based format (.att) for a container image, and attach them to
the image as OCI 1.1 referrers. Bundles that are already attached are skipped.

text

cosign bundle create-from-container IMAGE [flags]

Examples

text

# convert keyless attestations
	cosign bundle create-from-container <IMAGE>

  # convert attestations created with a key
			cosign bundle create-from-container --key cosign.pub <IMAGE>

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Bundle Create (`doc/cosign_bundle_create.md`)

cosign bundle create

Create a Sigstore protobuf bundle

Synopsis

Create a Sigstore protobuf bundle by supplying signed material

text

cosign bundle create [flags]

Examples

text

# create a bundle from a signature and certificate
  cosign bundle create --artifact <path> --signature <sig> --certificate <cert> --out bundle.sigstore.json

  # create a bundle from an attestation
  cosign bundle create --artifact <path> --attestation <att> --out bundle.sigstore.json

Options

text

--artifact string            path to artifact FILE
      --attestation string         path to attestation FILE
      --bundle string              path to old format bundle FILE
      --certificate string         path to the signing certificate, likely from Fulcio.
  -h, --help                       help for create
      --ignore-tlog                ignore transparency log verification, to be used when an artifact signature has not been uploaded to the transparency log.
      --key string                 path to the public key file, KMS URI or Kubernetes Secret
      --out string                 path to output bundle
      --rekor-url string           address of rekor STL server (default "https://rekor.sigstore.dev")
      --rfc3161-timestamp string   path to RFC3161 timestamp FILE
      --signature string           path to base64-encoded signature over attestation in DSSE format
      --sk                         whether to use a hardware security key
      --slot string                security key slot to use for generated key (authentication|signature|card-authentication|key-management) (default "signature")

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Bundle Inspect (`doc/cosign_bundle_inspect.md`)

cosign bundle inspect

Inspect a Sigstore protobuf bundle

text

cosign bundle inspect BUNDLE [flags]

Options

text

-h, --help   help for inspect

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Bundle Upgrade (`doc/cosign_bundle_upgrade.md`)

cosign bundle upgrade

Upgrade a Sigstore protobuf bundle

Synopsis

Upgrade a Sigstore Protobuf bundle to the latest version. This command only supports standardized bundles.

text

cosign bundle upgrade <bundle> [flags]

Options

text

-h, --help               help for upgrade
      --out string         path to the output upgraded bundle file
      --rekor-url string   URL of the transparency log (default "https://rekor.sigstore.dev")

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Clean (`doc/cosign_clean.md`)

cosign clean

Remove all signatures from an image

text

cosign clean [flags]

Examples

text

cosign clean <IMAGE>

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Completion (`doc/cosign_completion.md`)

cosign completion

Generate completion script

Synopsis

To load completions:
Bash:
$ source <(cosign completion bash)

To load completions for each session, execute once:

Linux:

$ cosign completion bash > /etc/bash_completion.d/cosign

macOS:

$ cosign completion bash > /usr/local/etc/bash_completion.d/cosign
Zsh:

If shell completion is not already enabled in your environment,

you will need to enable it. You can execute the following once:

$ echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions for each session, execute once:

$ cosign completion zsh > "${fpath[1]}/_cosign"

You will need to start a new shell for this setup to take effect.

fish:
$ cosign completion fish | source

To load completions for each session, execute once:

$ cosign completion fish > ~/.config/fish/completions/cosign.fish
PowerShell:
PS> cosign completion powershell | Out-String | Invoke-Expression

To load completions for every new session, run:

PS> cosign completion powershell > cosign.ps1

and source this file from your PowerShell profile.

text

cosign completion [bash|zsh|fish|powershell]

Options

text

-h, --help   help for completion

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Download (`doc/cosign_download.md`)

cosign download

Provides utilities for downloading artifacts and attached artifacts in a registry

Options

text

-h, --help   help for download

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Download Attestation (`doc/cosign_download_attestation.md`)

cosign download attestation

Download in-toto attestations from the supplied container image

text

cosign download attestation [flags]

Examples

text

cosign download attestation <image uri> [--predicate-type]

Options

text

--allow-http-registry           whether to allow using HTTP protocol while connecting to registries. Don't use this for anything but testing
      --allow-insecure-registry       whether to allow insecure connections to registries (e.g., with expired or self-signed TLS certificates). Don't use this for anything but testing
  -h, --help                          help for attestation
      --k8s-keychain                  whether to use the kubernetes keychain instead of the default keychain (supports workload identity).
      --platform string               download attestation for a specific platform image
      --predicate-type string         download attestation with matching predicateType
      --registry-cacert string        path to the X.509 CA certificate file in PEM format to be used for the connection to the registry
      --registry-client-cert string   path to the X.509 certificate file in PEM format to be used for the connection to the registry
      --registry-client-key string    path to the X.509 private key file in PEM format to be used, together with the 'registry-client-cert' value, for the connection to the registry
      --registry-password string      registry basic auth password
      --registry-server-name string   SAN name to use as the 'ServerName' tls.Config field to verify the mTLS connection to the registry
      --registry-token string         registry bearer auth token
      --registry-username string      registry basic auth username

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Download Sbom (`doc/cosign_download_sbom.md`)

cosign download sbom

DEPRECATED: Download SBOMs from the supplied container image

Synopsis

Download SBOMs from the supplied container image

WARNING: SBOM attachments are deprecated and support will be removed in a Cosign release soon after 2024-02-22 (see https://github.com/sigstore/cosign/issues/2755). Instead, please use SBOM attestations.

text

cosign download sbom [flags]

Examples

text

cosign download sbom <image uri>

Options

text

--allow-http-registry           whether to allow using HTTP protocol while connecting to registries. Don't use this for anything but testing
      --allow-insecure-registry       whether to allow insecure connections to registries (e.g., with expired or self-signed TLS certificates). Don't use this for anything but testing
  -h, --help                          help for sbom
      --k8s-keychain                  whether to use the kubernetes keychain instead of the default keychain (supports workload identity).
      --platform string               download SBOM for a specific platform image
      --registry-cacert string        path to the X.509 CA certificate file in PEM format to be used for the connection to the registry
      --registry-client-cert string   path to the X.509 certificate file in PEM format to be used for the connection to the registry
      --registry-client-key string    path to the X.509 private key file in PEM format to be used, together with the 'registry-client-cert' value, for the connection to the registry
      --registry-password string      registry basic auth password
      --registry-server-name string   SAN name to use as the 'ServerName' tls.Config field to verify the mTLS connection to the registry
      --registry-token string         registry bearer auth token
      --registry-username string      registry basic auth username

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Download Signature (`doc/cosign_download_signature.md`)

cosign download signature

Download signatures from the supplied container image

text

cosign download signature [flags]

Examples

text

cosign download signature <image uri>

Options

text

--allow-http-registry           whether to allow using HTTP protocol while connecting to registries. Don't use this for anything but testing
      --allow-insecure-registry       whether to allow insecure connections to registries (e.g., with expired or self-signed TLS certificates). Don't use this for anything but testing
  -h, --help                          help for signature
      --k8s-keychain                  whether to use the kubernetes keychain instead of the default keychain (supports workload identity).
      --registry-cacert string        path to the X.509 CA certificate file in PEM format to be used for the connection to the registry
      --registry-client-cert string   path to the X.509 certificate file in PEM format to be used for the connection to the registry
      --registry-client-key string    path to the X.509 private key file in PEM format to be used, together with the 'registry-client-cert' value, for the connection to the registry
      --registry-password string      registry basic auth password
      --registry-server-name string   SAN name to use as the 'ServerName' tls.Config field to verify the mTLS connection to the registry
      --registry-token string         registry bearer auth token
      --registry-username string      registry basic auth username

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Env (`doc/cosign_env.md`)

cosign env

Prints Cosign environment variables

text

cosign env [flags]

Examples

text

cosign env

  # show environment variables with descriptions
  cosign env --show-descriptions

  # show environment variables including sensitive values
  cosign env --show-descriptions --show-sensitive-values

Options

text

-h, --help                    help for env
      --show-descriptions       show descriptions for environment variables (default true)
      --show-sensitive-values   show values of sensitive environment variables

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Exit Codes (`doc/cosign_exit_codes.md`)

Exit codes for cosign CLI

The following exit codes may be subject to change

Exit code	Meaning
10	Error verifying image due to no signature
11	Error verifying image due to non-existent tag
12	Error verifying image due to no matching signature
13	Error verifying image due to no certificate found on signature

Doc Cosign Generate Key Pair (`doc/cosign_generate-key-pair.md`)

cosign generate-key-pair

Generates a key-pair

Synopsis

Generates a key-pair for signing.

text

cosign generate-key-pair [flags]

Examples

text

/* Detailed source-code truncated for AI context efficiency. */

Options

text

-h, --help                       help for generate-key-pair
      --kms string                 create key pair in KMS service to use for signing
      --output-key-prefix cosign   name used for generated .pub and .key files (defaults to cosign) (default "cosign")

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Import Key Pair (`doc/cosign_import-key-pair.md`)

cosign import-key-pair

Imports a PEM-encoded RSA or EC private key

Synopsis

Imports a PEM-encoded RSA or EC private key for signing.

text

cosign import-key-pair [flags]

Examples

text

cosign import-key-pair  --key openssl.key --output-key-prefix my-key

  # import PEM-encoded RSA or EC private key and write to import-cosign.key and import-cosign.pub files
  cosign import-key-pair --key <key path>

  # import PEM-encoded RSA or EC private key and write to my-key.key and my-key.pub files
  cosign import-key-pair --key <key path> --output-key-prefix my-key

CAVEATS:
  This command interactively prompts for a password. You can use
  the COSIGN_PASSWORD environment variable to provide one.

Options

text

-h, --help                       help for import-key-pair
  -k, --key string                 import key pair to use for signing
  -o, --output-key-prefix string   name used for outputted key pairs (default "import-cosign")
  -y, --yes                        skip confirmation prompts for overwriting existing key

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Initialize (`doc/cosign_initialize.md`)

cosign initialize

Initializes SigStore root to retrieve trusted certificate and key targets for verification

Synopsis

Initializes SigStore root to retrieve trusted certificate and key targets for verification.

The following options are used by default:

The current trusted Sigstore TUF root is embedded inside cosign at the time of release.
SigStore remote TUF repository is pulled from the CDN mirror at tuf-repo-cdn.sigstore.dev.

To provide an out-of-band trusted initial root.json, use the -root flag with a file or URL reference.
This will enable you to point cosign to a separate TUF root.

Any updated TUF repository will be written to $HOME/.sigstore/root/.

Trusted keys and certificate used in cosign verification (e.g. verifying Fulcio issued certificates
with Fulcio root CA) are pulled from the trusted metadata.

text

cosign initialize [flags]

Examples

text

cosign initialize --mirror <url>

# initialize root with distributed root keys, using the default mirror.
cosign initialize

# initialize root with distributed root keys, using the staging mirror.
cosign initialize --staging

# initialize with an out-of-band root key file, using the default mirror.
cosign initialize --root <url>

# initialize with an out-of-band root key file and custom repository mirror.
cosign initialize --mirror <url> --root <url>

# initialize with an out-of-band root key file and custom repository mirror while verifying root checksum.
cosign initialize --mirror <url> --root <url> --root-checksum <sha256>

Options

text

-h, --help                   help for initialize
      --mirror string          GCS bucket to a SigStore TUF repository, or HTTP(S) base URL, or file:/// for local filestore remote (air-gap) (default "https://tuf-repo-cdn.sigstore.dev")
      --root string            path to trusted initial root. defaults to embedded root
      --root-checksum string   checksum of the initial root, required if root is downloaded via http(s). expects sha256 by default, can be changed to sha512 by providing sha512:<checksum>
      --staging                use the staging TUF repository

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Load (`doc/cosign_load.md`)

cosign load

Load a signed image on disk to a remote registry

Synopsis

Load a signed image on disk to a remote registry

text

cosign load [flags]

Examples

text

cosign load --dir <path to directory> <IMAGE>

Options

text

--allow-http-registry           whether to allow using HTTP protocol while connecting to registries. Don't use this for anything but testing
      --allow-insecure-registry       whether to allow insecure connections to registries (e.g., with expired or self-signed TLS certificates). Don't use this for anything but testing
      --dir string                    path to directory where the signed image is stored on disk
  -h, --help                          help for load
      --k8s-keychain                  whether to use the kubernetes keychain instead of the default keychain (supports workload identity).
      --registry-cacert string        path to the X.509 CA certificate file in PEM format to be used for the connection to the registry
      --registry-client-cert string   path to the X.509 certificate file in PEM format to be used for the connection to the registry
      --registry-client-key string    path to the X.509 private key file in PEM format to be used, together with the 'registry-client-cert' value, for the connection to the registry
      --registry-password string      registry basic auth password
      --registry-server-name string   SAN name to use as the 'ServerName' tls.Config field to verify the mTLS connection to the registry
      --registry-token string         registry bearer auth token
      --registry-username string      registry basic auth username

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Examples

text

# Log in to reg.example.com
  cosign login reg.example.com -u AzureDiamond -p hunter2

Options

text

-h, --help              help for login
  -p, --password string   Password
      --password-stdin    Take the password from stdin
  -u, --username string   Username

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Piv Tool (`doc/cosign_piv-tool.md`)

cosign piv-tool

Provides utilities for managing a hardware token

Options

text

-h, --help       help for piv-tool
  -f, --no-input   skip warnings and confirmations

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Piv Tool Attestation (`doc/cosign_piv-tool_attestation.md`)

cosign piv-tool attestation

Manage hardware token attestations

text

cosign piv-tool attestation [flags]

Examples

text

# print attestation information as text
  cosign piv-tool attestation --slot 9c

  # print attestation information as JSON
  cosign piv-tool attestation --slot 9c --output json

Options

text

-h, --help            help for attestation
  -o, --output string   format to output attestation information in. (text|json) (default "text")
      --slot string     Slot to use for generated key (authentication|signature|card-authentication|key-management)

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Piv Tool Generate Key (`doc/cosign_piv-tool_generate-key.md`)

cosign piv-tool generate-key

Generate a new signing key on the hardware token

text

cosign piv-tool generate-key [flags]

Examples

text

# generate a key with default settings (slot 9c, always-touch policy)
  cosign piv-tool generate-key

  # generate a key in a specific slot with custom PIN and touch policies
  cosign piv-tool generate-key --slot 9c --pin-policy once --touch-policy always

Options

text

-h, --help                    help for generate-key
      --management-key string   management key, uses default if empty
      --pin-policy string       PIN policy for slot (never|once|always)
      --random-management-key   if set to true, generates a new random management key and deletes it after
      --slot string             Slot to use for generated key (authentication|signature|card-authentication|key-management)
      --touch-policy string     Touch policy for slot (never|always|cached)

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Piv Tool Reset (`doc/cosign_piv-tool_reset.md`)

cosign piv-tool reset

Reset the hardware token completely

text

cosign piv-tool reset [flags]

Examples

text

cosign piv-tool reset

Options

text

-h, --help   help for reset

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Piv Tool Set Management Key (`doc/cosign_piv-tool_set-management-key.md`)

cosign piv-tool set-management-key

Set the management key of a hardware token

text

cosign piv-tool set-management-key [flags]

Examples

text

# set a new management key interactively (uses defaults if flags omitted)
  cosign piv-tool set-management-key

  # set a random management key
  cosign piv-tool set-management-key --random-management-key

  # set a specific new management key
  cosign piv-tool set-management-key --old-key <old-key> --new-key <new-key>

Options

text

-h, --help                    help for set-management-key
      --new-key string          new management key, uses default if empty
      --old-key string          existing management key, uses default if empty
      --random-management-key   if set to true, generates a new random management key and deletes it after

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Piv Tool Set Pin (`doc/cosign_piv-tool_set-pin.md`)

cosign piv-tool set-pin

Set the PIN on a hardware token

text

cosign piv-tool set-pin [flags]

Examples

text

# set a new PIN interactively (uses defaults if flags omitted)
  cosign piv-tool set-pin

  # set a specific PIN
  cosign piv-tool set-pin --old-pin <old-pin> --new-pin <new-pin>

Options

text

-h, --help             help for set-pin
      --new-pin string   new PIN, uses default if empty
      --old-pin string   existing PIN, uses default if empty

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Piv Tool Set Puk (`doc/cosign_piv-tool_set-puk.md`)

cosign piv-tool set-puk

Set the PUK on a hardware token

text

cosign piv-tool set-puk [flags]

Examples

text

# set a new PUK interactively (uses defaults if flags omitted)
  cosign piv-tool set-puk

  # set a specific PUK
  cosign piv-tool set-puk --old-puk <old-puk> --new-puk <new-puk>

Options

text

-h, --help             help for set-puk
      --new-puk string   new PUK, uses default if empty
      --old-puk string   existing PUK, uses default if empty

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Piv Tool Unblock (`doc/cosign_piv-tool_unblock.md`)

cosign piv-tool unblock

Unblock a hardware token and set a new PIN

text

cosign piv-tool unblock [flags]

Examples

text

# unblock the token using the PUK and set a new PIN
  cosign piv-tool unblock --puk <puk> --new-PIN <new-pin>

Options

text

-h, --help             help for unblock
      --new-PIN string   new PIN, uses default if empty
      --puk string       existing PUK, uses default if empty

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Pkcs11 Tool (`doc/cosign_pkcs11-tool.md`)

cosign pkcs11-tool

Provides utilities for retrieving information from a PKCS11 token.

Options

text

-h, --help       help for pkcs11-tool
  -f, --no-input   skip warnings and confirmations

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Pkcs11 Tool List Keys Uris (`doc/cosign_pkcs11-tool_list-keys-uris.md`)

cosign pkcs11-tool list-keys-uris

List URIs of all keys in a PKCS11 token

text

cosign pkcs11-tool list-keys-uris [flags]

Examples

text

# list key URIs in a specific PKCS11 token slot
  cosign pkcs11-tool list-keys-uris --module-path /usr/lib/libp11kit.so --slot-id 0

Options

text

-h, --help                 help for list-keys-uris
      --module-path string   absolute path to the PKCS11 module
      --pin string           pin of the PKCS11 slot, uses environment variable COSIGN_PKCS11_PIN if empty
      --slot-id uint         id of the PKCS11 slot, uses 0 if empty

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Pkcs11 Tool List Tokens (`doc/cosign_pkcs11-tool_list-tokens.md`)

cosign pkcs11-tool list-tokens

List all PKCS11 tokens linked to a module

text

cosign pkcs11-tool list-tokens [flags]

Examples

text

# list all tokens for a PKCS11 module
  cosign pkcs11-tool list-tokens --module-path /usr/lib/libp11kit.so

Options

text

-h, --help                 help for list-tokens
      --module-path string   absolute path to the PKCS11 module

Options inherited from parent commands

text

-f, --no-input             skip warnings and confirmations
      --output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Public Key (`doc/cosign_public-key.md`)

cosign public-key

Gets a public key from the key-pair

Synopsis

Gets a public key from the key-pair and
writes to a specified file. By default, it will write to standard out.

text

cosign public-key [flags]

Examples

text

# extract public key from private key to a specified out file.
  cosign public-key --key <PRIVATE KEY FILE> --outfile <OUTPUT>

  # extract public key from URL.
  cosign public-key --key https://host.for/<FILE> --outfile <OUTPUT>

  # extract public key from Azure Key Vault
  cosign public-key --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY]

  # extract public key from AWS KMS
  cosign public-key --key awskms://[ENDPOINT]/[ID/ALIAS/ARN]

  # extract public key from Google Cloud KMS
  cosign public-key --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY]

  # extract public key from Hashicorp Vault KMS
  cosign public-key --key hashivault://[KEY]

  # extract public key from GitLab with project name
  cosign public-key --key gitlab://[OWNER]/[PROJECT_NAME] <IMAGE>

  # extract public key from GitLab with project id
  cosign public-key --key gitlab://[PROJECT_ID] <IMAGE>

Options

text

-h, --help             help for public-key
      --key string       path to the private key file, KMS URI or Kubernetes Secret
      --outfile string   path to a payload file to use rather than generating one
      --sk               whether to use a hardware security key
      --slot string      security key slot to use for generated key (default: signature) (authentication|signature|card-authentication|key-management)

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Save (`doc/cosign_save.md`)

cosign save

Save the container image and associated signatures to disk at the specified directory

Synopsis

Save the container image and associated signatures to disk at the specified directory.

text

cosign save [flags]

Examples

text

cosign save --dir <path to directory> <IMAGE>

Options

text

--allow-http-registry           whether to allow using HTTP protocol while connecting to registries. Don't use this for anything but testing
      --allow-insecure-registry       whether to allow insecure connections to registries (e.g., with expired or self-signed TLS certificates). Don't use this for anything but testing
      --dir string                    path to dir where the signed image should be stored on disk
  -h, --help                          help for save
      --k8s-keychain                  whether to use the kubernetes keychain instead of the default keychain (supports workload identity).
      --registry-cacert string        path to the X.509 CA certificate file in PEM format to be used for the connection to the registry
      --registry-client-cert string   path to the X.509 certificate file in PEM format to be used for the connection to the registry
      --registry-client-key string    path to the X.509 private key file in PEM format to be used, together with the 'registry-client-cert' value, for the connection to the registry
      --registry-password string      registry basic auth password
      --registry-server-name string   SAN name to use as the 'ServerName' tls.Config field to verify the mTLS connection to the registry
      --registry-token string         registry bearer auth token
      --registry-username string      registry basic auth username

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Sign Blob (`doc/cosign_sign-blob.md`)

cosign sign-blob

Sign the supplied blob, outputting the base64-encoded signature to stdout

text

cosign sign-blob [flags]

Examples

text

cosign sign-blob --key <key path>|<kms uri> <blob>

  # sign a blob with a local key pair file
  cosign sign-blob --key cosign.key <FILE>

  # sign a blob with a key stored in an environment variable
  cosign sign-blob --key env://[ENV_VAR] <FILE>

  # sign a blob with a key pair stored in Azure Key Vault
  cosign sign-blob --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] <FILE>

  # sign a blob with a key pair stored in AWS KMS
  cosign sign-blob --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] <FILE>

  # sign a blob with a key pair stored in Google Cloud KMS
  cosign sign-blob --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY] <FILE>

  # sign a blob with a key pair stored in Hashicorp Vault
  cosign sign-blob --key hashivault://[KEY] <FILE>

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Sign (`doc/cosign_sign.md`)

cosign sign

Sign the supplied container image

Synopsis

Sign the supplied container image.

Make sure to sign the image by its digest (@sha256:...) rather than by tag
(:latest) so that you actually sign what you think you're signing! This prevents
race conditions or (worse) malicious tampering.

text

cosign sign [flags]

Examples

text

/* Detailed source-code truncated for AI context efficiency. */

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Signing Config (`doc/cosign_signing-config.md`)

cosign signing-config

Interact with a Sigstore protobuf signing config

Synopsis

Tool for interacting with a Sigstore protobuf signing config

Options

text

-h, --help   help for signing-config

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Signing Config Create (`doc/cosign_signing-config_create.md`)

cosign signing-config create

Create a Sigstore protobuf signing config

Synopsis

Create a Sigstore protobuf signing config by supplying verification material for Fulcio, Rekor, OIDC, and TSA services.
Each service is specified via a repeatable flag (--fulcio, --rekor, --oidc-provider, --tsa) that takes a comma-separated list of key-value pairs.

Use --base-config to start from an existing signing config and override specific services. Service flags will replace services from the base config.

text

cosign signing-config create [flags]

Examples

text

# Create from scratch
cosign signing-config create \
    --fulcio="url=https://fulcio.sigstore.dev,api-version=1,start-time=2024-01-01T00:00:00Z,end-time=2025-01-01T00:00:00Z,operator=sigstore.dev" \
    --rekor="url=https://rekor.sigstore.dev,api-version=1,start-time=2024-01-01T00:00:00Z,operator=sigstore.dev" \
    --rekor-config="ANY" \
    --oidc-provider="url=https://oauth2.sigstore.dev/auth,api-version=1,start-time=2024-01-01T00:00:00Z,operator=sigstore.dev" \
    --tsa="url=https://timestamp.sigstore.dev/api/v1/timestamp,api-version=1,start-time=2024-01-01T00:00:00Z,operator=sigstore.dev" \
    --tsa-config="EXACT:1" \
    --out signing-config.json

# Use Sigstore TUF defaults
cosign signing-config create \
    --with-default-services \
    --out sigstore-signing-config.json

# Override OIDC provider from base config
cosign signing-config create \
    --base-config signing_config.v0.2.json \
    --oidc-provider="url=https://custom-oidc.example.com,api-version=1,start-time=2024-01-01T00:00:00Z,operator=example.com" \
    --out custom-signing-config.json

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Tree (`doc/cosign_tree.md`)

cosign tree

Display supply chain security related artifacts for an image such as signatures, SBOMs and attestations

text

cosign tree [flags]

Examples

text

cosign tree <IMAGE>

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Trusted Root (`doc/cosign_trusted-root.md`)

cosign trusted-root

Interact with a Sigstore protobuf trusted root

Synopsis

Tools for interacting with a Sigstore protobuf trusted root

Options

text

-h, --help   help for trusted-root

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Trusted Root Create (`doc/cosign_trusted-root_create.md`)

cosign trusted-root create

Create a Sigstore protobuf trusted root

Synopsis

Create a Sigstore protobuf trusted root by supplying verification material.

Each service is specified via a repeatable flag (--fulcio, --rekor, --ctfe, --tsa) that takes a comma-separated list of key-value pairs.

text

cosign trusted-root create [flags]

Examples

text

cosign trusted-root create \
    --fulcio="url=https://fulcio.sigstore.dev,certificate-chain=/path/to/fulcio.pem,end-time=2025-01-01T00:00:00Z" \
    --rekor="url=https://rekor.sigstore.dev,public-key=/path/to/rekor.pub,start-time=2024-01-01T00:00:00Z" \
    --ctfe="url=https://ctfe.sigstore.dev,public-key=/path/to/ctfe.pub,start-time=2024-01-01T00:00:00Z" \
    --tsa="url=https://timestamp.sigstore.dev/api/v1/timestamp,certificate-chain=/path/to/tsa.pem" \
    --out trusted-root.json

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Verify Attestation (`doc/cosign_verify-attestation.md`)

cosign verify-attestation

Verify an attestation on the supplied container image

Synopsis

Verify an attestation on an image by checking the claims
against the transparency log.

text

cosign verify-attestation [flags]

Examples

text

/* Detailed source-code truncated for AI context efficiency. */

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Verify Blob Attestation (`doc/cosign_verify-blob-attestation.md`)

cosign verify-blob-attestation

Verify an attestation on the supplied blob

Synopsis

Verify an attestation on the supplied blob input using the specified key reference.
You may specify either a key or a kms reference to verify against.

Signed material is provided with the --bundle flag.
The blob may be specified as a path to a file.

text

cosign verify-blob-attestation [flags]

Examples

text

cosign verify-blob-attestation --bundle <path> --certificate-identity <identity> --certificate-oidc-issuer <issuer> <blob>

  # Verify a blob attestation (keyless)
  cosign verify-blob-attestation --bundle artifact.sigstore.json --certificate-identity [email protected] --certificate-oidc-issuer https://accounts.google.com <blob>

  # Verify a blob attestation with a public key
  cosign verify-blob-attestation --bundle artifact.sigstore.json --key cosign.pub <blob>

  # Verify a blob attestation with Azure KMS
  cosign verify-blob-attestation --bundle artifact.sigstore.json --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] <blob>

  # Verify a blob attestation with AWS KMS
  cosign verify-blob-attestation --bundle artifact.sigstore.json --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] <blob>

  # Verify a blob attestation with GCP KMS
  cosign verify-blob-attestation --bundle artifact.sigstore.json --key gcpkms://projects/[PROJECT]/locations/global/keyRings/[KEYRING]/cryptoKeys/[KEY] <blob>

  # Verify a blob attestation with Hashicorp Vault
  cosign verify-blob-attestation --bundle artifact.sigstore.json --key hashivault://[KEY] <blob>

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Verify Blob (`doc/cosign_verify-blob.md`)

cosign verify-blob

Verify a signature on the supplied blob

Synopsis

Verify a signature on the supplied blob input using the specified key reference.
You may specify either a key, a bundle (optionally with trusted root), or a kms reference to verify against.
If you use a key, bundle, or trusted root, you must specify the path to them on disk.

The preferred way to provide verification material is via a Sigstore bundle using --bundle,
which contains the signature, certificate, and transparency log proof.
The blob may be specified as a path to a file or - for stdin.

text

cosign verify-blob [flags]

Examples

text

cosign verify-blob --bundle <path> --certificate-identity <identity> --certificate-oidc-issuer <issuer> <blob>

  # Verify a signature with a bundle and trusted root
  cosign verify-blob --bundle artifact.sigstore.json --trusted-root trusted_root.json <blob>

  # Verify a blob (keyless)
  cosign verify-blob --bundle artifact.sigstore.json --certificate-identity [email protected] --certificate-oidc-issuer https://accounts.google.com <blob>

  # Verify a blob with an on-disk public key
  cosign verify-blob --bundle artifact.sigstore.json --key cosign.pub <blob>

  # Verify a blob against Azure Key Vault
  cosign verify-blob --bundle artifact.sigstore.json --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] <blob>

  # Verify a blob against AWS KMS
  cosign verify-blob --bundle artifact.sigstore.json --key awskms://[ENDPOINT]/[ID/ALIAS/ARN] <blob>

  # Verify a blob against Google Cloud KMS
  cosign verify-blob --bundle artifact.sigstore.json --key gcpkms://projects/[PROJECT ID]/locations/[LOCATION]/keyRings/[KEYRING]/cryptoKeys/[KEY] <blob>

  # Verify a blob against Hashicorp Vault
  cosign verify-blob --bundle artifact.sigstore.json --key hashivault://[KEY] <blob>

  # Verify a blob against GitLab with project name
  cosign verify-blob --bundle artifact.sigstore.json --key gitlab://[OWNER]/[PROJECT_NAME] <blob>

  # Verify a blob against GitLab with project id
  cosign verify-blob --bundle artifact.sigstore.json --key gitlab://[PROJECT_ID] <blob>

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Verify (`doc/cosign_verify.md`)

cosign verify

Verify a signature on the supplied container image

Synopsis

Verify signature and annotations on an image by checking the claims
against the transparency log.

text

cosign verify [flags]

Examples

text

/* Detailed source-code truncated for AI context efficiency. */

Options

text

/* Detailed source-code truncated for AI context efficiency. */

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Doc Cosign Version (`doc/cosign_version.md`)

cosign version

Prints the version

text

cosign version [flags]

Options

text

-h, --help   help for version
      --json   print JSON instead of text

Options inherited from parent commands

text

--output-file string   log output to a file
  -t, --timeout duration     timeout for commands (default 3m0s)
  -d, --verbose              log debug output

Docker & Self-Hosted Deployment Verified OCI

Technical Documentation: sigstore/cosign

Overview (`README.md`) Copy Section

cosign

Info Copy Chapter

Installation Copy Chapter

Developer Installation Copy Chapter

Contributing Copy Chapter

Dockerfile Copy Chapter

Quick Start Copy Chapter

Sign a container and store the signature in the registry Copy Section

Verify a container Copy Section

Verify a container against a public key Copy Section

Verify a container in an air-gapped environment Copy Section

Identity-based blob signing and verification Copy Section

Troubleshooting Copy Section

Common issues and remedies

My problem is something else

Working with Other Artifacts Copy Chapter

Blobs Copy Section

Tekton Bundles

WASM

eBPF

In-Toto Attestations

Detailed Usage Copy Chapter

Hardware-based Tokens Copy Chapter

Registry Support Copy Chapter

Caveats Copy Chapter

Intentionally Missing Features Copy Section

Things That Should Probably Change Copy Section

Payload Formats

Registry Details

Specifying Registry

Signature Specification Copy Chapter

Storage Specification Copy Chapter

Signing subjects Copy Section

KMS Support Copy Section

OCI Artifacts Copy Section

FAQ Copy Chapter

Why not use Notary v2 Copy Section

Why not use containers/image signing Copy Section

Why not use TUF? Copy Section

Design Requirements Copy Chapter

Future Ideas Copy Chapter

Registry API Changes Copy Section

Other Types Copy Section

Tag Signing Copy Section

Base Image/Layer Signing Copy Section

Counter-Signing Copy Section

Release Cadence Copy Chapter

Security Copy Chapter

Bundle files in GitHub Release Assets Copy Chapter

Overview (`release/README.md`) Copy Section

Release

Cutting a Cosign Release

Overview (`test/README.md`) Copy Section

Cosign E2E Tests

General-purpose tests Copy Chapter

Environment-specific tests Copy Chapter

Dos Copy Chapter

Don'ts Copy Chapter

Doc Cosign (`doc/cosign.md`) Copy Section

cosign Copy Chapter

Options Copy Section

SEE ALSO Copy Section

Doc Cosign Attest Blob (`doc/cosign_attest-blob.md`) Copy Section

cosign attest-blob Copy Chapter

Examples Copy Section

Options Copy Section

Options inherited from parent commands Copy Section

SEE ALSO Copy Section

Doc Cosign Attest (`doc/cosign_attest.md`) Copy Section

cosign attest Copy Chapter

Examples Copy Section

Options Copy Section

Options inherited from parent commands Copy Section

SEE ALSO Copy Section

Doc Cosign Bundle (`doc/cosign_bundle.md`) Copy Section

cosign bundle Copy Chapter

Synopsis Copy Section

Overview (`README.md`)

Info

Installation

Developer Installation

Contributing

Dockerfile

Quick Start

Sign a container and store the signature in the registry

Verify a container

Verify a container against a public key

Verify a container in an air-gapped environment

Identity-based blob signing and verification

Troubleshooting

Working with Other Artifacts

Blobs

Detailed Usage

Hardware-based Tokens

Registry Support

Caveats

Intentionally Missing Features

Things That Should Probably Change

Signature Specification

Storage Specification

Signing subjects

KMS Support

OCI Artifacts

FAQ

Why not use Notary v2

Why not use containers/image signing

Why not use TUF?

Design Requirements

Future Ideas

Registry API Changes

Other Types

Tag Signing

Base Image/Layer Signing

Counter-Signing

Release Cadence

Security

Bundle files in GitHub Release Assets

Overview (`release/README.md`)

Overview (`test/README.md`)

General-purpose tests

Environment-specific tests

Dos

Don'ts

Doc Cosign (`doc/cosign.md`)

cosign

Options

SEE ALSO

Doc Cosign Attest Blob (`doc/cosign_attest-blob.md`)

cosign attest-blob

Examples

Options

Options inherited from parent commands

SEE ALSO

Doc Cosign Attest (`doc/cosign_attest.md`)

cosign attest

Examples

Options

Options inherited from parent commands

SEE ALSO

Doc Cosign Bundle (`doc/cosign_bundle.md`)

cosign bundle

Synopsis

Options

Options inherited from parent commands

SEE ALSO

Doc Cosign Bundle Create From Container (`doc/cosign_bundle_create-from-container.md`)

cosign bundle create-from-container

Synopsis

Examples

Options

Options inherited from parent commands

SEE ALSO

Doc Cosign Bundle Create (`doc/cosign_bundle_create.md`)

cosign bundle create

Synopsis

Examples

Options