Sign Artifacts with Cosign
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 Spec | Signing Algorithm |
|---|---|
ECC_NIST_P256 | ECDSA_SHA_256 |
ECC_NIST_P384 | ECDSA_SHA_384 |
ECC_NIST_P521 | ECDSA_SHA_512 |
RSA_3072, RSA_4096 | RSASSA_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
- Cosign v3.1.4 or later.
- The Exoscale CLI v1.104.0 or later, to create the signing key.
- An Exoscale API key, ideally restricted as described in Restrict the API Key.
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:
| Variable | Purpose |
|---|---|
EXOSCALE_API_KEY | API key |
EXOSCALE_API_SECRET | API secret |
EXOSCALE_ZONE | Zone 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 Reference | Zone |
|---|---|
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.gzCosign 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.pubVerify a file:
cosign verify-blob --key cosign.pub --bundle artifact.sigstore.json artifact.tar.gzVerify 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.