You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.
sigstore / cosign Public
Code signing and transparency for containers and binaries
Notifications You must be signed in to change notification settings
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Go to fileCosign is developed as part of the sigstore project. We also use a slack channel! Click here for the invite link.
For Homebrew, Arch, Nix, GitHub Action, and Kubernetes installs see the installation docs.
For Linux and macOS binaries see the GitHub release assets.
🚨 If you are downloading releases of cosign from our GCS bucket - please see more information on the July 31, 2023 deprecation notice 🚨
If you have Go 1.22+, you can setup a development environment:
$ git clone https://github.com/sigstore/cosign $ cd cosign $ go install ./cmd/cosign $ $(go env GOPATH)/bin/cosign
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.
Here is how to install and use cosign inside a Dockerfile through the gcr.io/projectsigstore/cosign image:
FROM gcr.io/projectsigstore/cosign:v1.13.0 as cosign-bin # Source: https://github.com/chainguard-images/static FROM cgr.dev/chainguard/static:latest COPY --from=cosign-bin /ko-app/cosign /usr/local/bin/cosign ENTRYPOINT [ "cosign" ]
This shows how to:
Note that you should always sign images based on their digest ( @sha256. ) rather than a tag ( :latest ) because otherwise you might sign something you didn't intend to!
cosign 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.
To verify the image, you'll need to pass in the expected certificate subject and certificate issuer via the --certificate-identity and --certificate-oidc-issuer flags:
cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER You can also pass in a regex for the certificate identity and issuer flags, --certificate-identity-regexp and --certificate-oidc-issuer-regexp .
This command returns 0 if at least one cosign formatted signature for the image is found matching the public key. See the detailed usage below for information and caveats on other signature formats.
Any valid payloads are printed to stdout, in json format. Note that these signed payloads include the digest of the container image, which is how we can be sure these "detached" signatures cover the correct image.
$ cosign verify --key cosign.pub $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>
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):
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:
cosign verify --certificate-identity $CERT_IDENTITY --certificate-oidc-issuer $CERT_OIDC_ISSUER --offline --local-image ./path/to/dir You'll need to pass in expected values for $CERT_IDENTITY and $CERT_OIDC_ISSUER to correctly verify this image. If you signed with a keypair, the same command will work, assuming the public key material is present locally:
cosign verify --key cosign.pub --offline --local-image ./path/to/dir While parts of cosign are stable, we are continuing to experiment and add new features. The following feature set is not considered stable yet, but we are committed to stabilizing it over time!
While the cosign code for uploading, signing, retrieving, and verifying several artifact types is stable, the format specifications for some of those types may not be considered stable yet. Some of these are developed outside of the cosign project, so we are waiting for them to stabilize first.
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.
You can publish an artifact with cosign upload blob :
$ 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:
$ 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:
$ cat artifact-fetched | shasum -a 256 c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626 -
You can sign it with the normal cosign sign command and flags:
$ 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 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.
$ 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
Web Assembly Modules can also be stored in an OCI registry, using this specification.
Cosign can upload these using the cosign wasm upload command:
$ 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 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.
$ 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>]
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:
$ 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.
$ cosign verify-attestation --key cosign.pub $IMAGE_URI
See the Usage documentation for more information.