Skip to content

Sign Artifacts with Cosign

This guide is provided for informational purposes. Because it involves third party tooling we cannot guarantee things still work exactly as described here.

Cosign from the Sigstore project signs container images and files, so that consumers can check before use that a trusted party produced them. With the sigstore-kms-exoscalekms plugin, cosign signs with an asymmetric KMS key, and the private key never leaves Exoscale KMS.

How It Works

Cosign hands signing to the plugin whenever a key reference starts with exoscalekms://. Only the digest of the artifact goes to the KMS, never the artifact itself.

Verification only needs the public key. Cosign verifies locally and never calls the KMS verify operation, so verifiers need no Exoscale credentials.

The plugin derives the signing algorithm from the key-spec of the KMS key, using an algorithm that cosign verifies by default:

Key SpecSigning Algorithm
ECC_NIST_P256ECDSA_SHA_256
ECC_NIST_P384ECDSA_SHA_384
ECC_NIST_P521ECDSA_SHA_512
RSA_3072, RSA_4096RSASSA_PKCS1_V1_5_SHA_256

ECC_EDWARDS25519, ML_DSA_65 and ML_DSA_87 keys are not supported.

For the underlying KMS operations, see Sign and Verify with Asymmetric KMS Keys.

Prerequisites

Install the Plugin

Install the plugin as described in the plugin README. Cosign looks for a binary named sigstore-kms-exoscalekms on your PATH.

Create a Signing Key

exo kms key create cosign-signing --usage sign-verify --key-spec ECC_NIST_P256 --zone <zone-name>

The command returns the key’s UUID. The plugin references keys by UUID only, not by name. It does not create keys either, so cosign generate-key-pair --kms fails.

Note

Asymmetric KMS keys cannot be rotated. To move to a new key pair, create a new KMS key and distribute its public key to your verifiers.

Restrict the API Key

The plugin only calls the KMS get-public-key and sign operations. Create an IAM role limited to these operations on the signing key, then an API key with this role. Replace <key-uuid> with the key’s UUID:

{
  "default-service-strategy": "deny",
  "services": {
    "kms": {
      "type": "rules",
      "rules": [
        {
          "expression": "operation in ['sign', 'get-public-key'] && resources.kms_key.id == '<key-uuid>'",
          "action": "allow"
        }
      ]
    }
  }
}

The plugin reads its configuration from environment variables only, not from the Exoscale CLI configuration file:

VariablePurpose
EXOSCALE_API_KEYAPI key
EXOSCALE_API_SECRETAPI secret
EXOSCALE_ZONEZone of the key, when the key reference has none
export EXOSCALE_API_KEY=<api-key>
export EXOSCALE_API_SECRET=<api-secret>

Sign

The key reference tells cosign which KMS key to use:

Key ReferenceZone
exoscalekms://<zone-name>/<key-uuid><zone-name>
exoscalekms:///<key-uuid>Value of EXOSCALE_ZONE

Sign a File

cosign sign-blob --key exoscalekms://<zone-name>/<key-uuid> --bundle artifact.sigstore.json artifact.tar.gz

Cosign writes the signature to the bundle file artifact.sigstore.json. Distribute it next to the artifact.

Sign a Container Image

Sign the image by digest rather than by tag:

cosign sign --key exoscalekms://<zone-name>/<key-uuid> <registry>/<image>@sha256:<digest>

Cosign pushes the signature to the registry next to the image, so you need write access to the registry.

Note

With its default settings, cosign records every signature in the public Rekor transparency log. Pass -y to skip the confirmation prompt in non-interactive pipelines. Timestamp and transparency log settings are cosign options and work as with any other key, see the cosign documentation.

Verify

Export the public key and distribute it to your verifiers:

cosign public-key --key exoscalekms://<zone-name>/<key-uuid> > cosign.pub

Verify a file:

cosign verify-blob --key cosign.pub --bundle artifact.sigstore.json artifact.tar.gz

Verify a container image:

cosign verify --key cosign.pub <registry>/<image>@sha256:<digest>

Verifying with the public key file needs neither the plugin nor Exoscale credentials. Passing --key exoscalekms://<zone-name>/<key-uuid> also works: cosign fetches the public key from the KMS and verifies locally.

To admit only signed images to a Kubernetes cluster such as SKS, use the public key in an admission policy, as shown in Sign Container Images With Cosign.

Last updated on