Sign container images using cosign KMS plugin
Before signing an image, ensure that it has already been pushed to the container registry. Cosign resolves the image tag to its immutable digest and signs the digest rather than the tag.
Wichtig
The Cosign KMS plugin feature is supported with Cosign version 3.x and later.
cosign sign --key "digicert://alias/my-cosign-key" registry.example.com/myapp@sha256:<DIGEST>
By default, cosign also uploads the signature to the public Rekor transparency log.
cosign sign-blob \ --key "digicert://alias/my-cosign-key" \ --bundle artifact.sigstore.json \ artifact.bin
The --bundle file contains both the signature and associated verification material. Distribute it alongside the artifact and provide it to verify-blob during verification.
cosign attest \ --key "digicert://alias/my-cosign-key" \ --predicate sbom.spdx.json \ --type spdxjson \ registry.example.com/myapp@sha256:<DIGEST>
Many enterprise users sign artifacts with a private, Software Trust Manager-managed key and prefer not to have the signing event recorded in the public Rekor transparency log. Use the following methods to skip transparency logging:
Where no_tlog.json contains:
{
"mediaType": "application/vnd.dev.sigstore.signingconfig.v0.2+json",
"rekorTlogUrls": [],
"tsaUrls": []
}# Container images cosign verify --key "digicert://alias/my-cosign-key" registry.example.com/myapp@sha256:<DIGEST> # Blobs cosign verify-blob \ --key "digicert://alias/my-cosign-key" \ --bundle artifact.sigstore.json \ artifact.bin # Attestations cosign verify-attestation --key "digicert://alias/my-cosign-key" registry.example.com/myapp@sha256:<DIGEST>
If the signature was created with an empty rekorTlogUrls signing config), include the --insecure-ignore-tlog option when verifying the signature because no transparency log entry is available for verification.
Verification methods: Local vs. Server-side
The plugin supports two verification modes, controlled by SM_VERIFY_SERVER_SIDE:
Mode | How to enable | Behavior |
|---|---|---|
Local (default) | (no action needed) | The plugin retrieves the keypair's public key or certificate once and performs signature verification locally using Go's standard cryptographic libraries. This approach minimizes network calls and provides fast, efficient verification. |
Server-side | | The plugin sends the digest and signature to the Software Trust Manager Verify API, which verifies the signature and validates the certificate's revocation status and the signing key's status. This approach requires network access during verification but provides stronger compliance and audit assurance. |
Error | Description | Solution |
|---|---|---|
| Plugin not found by cosign |
|
| Authentication failures |
|
| Keypair not found |
|
| | |
| Signature verification fails after signing without a transparency log | Add |
Enable KMS cosign debugging for detailed logs and troubleshooting.
export SM_LOG_LEVEL=debug export SM_LOG_OUTPUT=stdout cosign sign --key "digicert://alias/my-cosign-key" --yes <IMAGE DIGEST>
Logs are also written to $SM_HOME/logs/ by default.