Overview

Sigstore handles keys and key management internally by default. However, while the default makes it unnecessary, you can configure sigstore, through cosign, to work with KMS providers. This page contains detailed instructions on how to configure cosign to work with KMS providers. Right now cosign supports AWS KMS, GCP KMS, Azure Key Vault, Hashicorp Vault and Kubernetes Secrets with the hope to support more in the future!

Basic Usage

When referring to a key managed by a KMS provider, cosign takes a go-cloud style URI to refer to the specific provider.

For example: awskms://, gcpkms://, azurekms://, hashivault:// and k8s://. The URI path syntax is provider specific and explained in the section for each provider.

Key Generation and Management

To generate keys using a KMS provider, you can use the cosign generate-key-pair command with the --kms flag. For example:

cosign generate-key-pair --kms <some provider>://<some key>

The public key can be retrieved with:

$ cosign public-key --key <some provider>://<some key>
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXc+DQU8Pb7Xo2RWCjFG/f6qbdABN
jnVtSyKZxNzBfNMLLtVxdu8q+AigrGCS2KPmejda9bICTcHQCRUrD5OLGQ==
-----END PUBLIC KEY-----

Signing and Verification

For the following examples, we have:

IMAGE=gcr.io/user/demo
IMAGE_DIGEST=$IMAGE@sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd

To sign and verify using a key managed by a KMS provider, you can pass a provider-specific URI to the --key command:

$ cosign sign --key <some provider>://<some key> $IMAGE_DIGEST
Pushing signature to: gcr.io/user/demo:sha256-410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd.cosign

$ cosign verify --key <some provider>://<some key> $IMAGE_DIGEST

Verification for gcr.io/user/demo --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key
  - The code-signing certificate was verified using trusted certificate authority certificates

[{"critical":{"identity":{"docker-reference":"gcr.io/user/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}]

You can also export the public key and verify against that file:

cosign public-key --key <some provider>://<some key> > kms.pub
cosign verify --key kms.pub $IMAGE_DIGEST

Providers

This section contains the provider-specific documentation.

AWS

AWS KMS keys can be used in cosign for signing and verification. The URI format for AWS KMS is awskms://$ENDPOINT/$KEYID where $ENDPOINT and $KEYID are replaced with the correct values.

The $ENDPOINT value is left blank in most scenarios, but can be set for testing with KMS-compatible servers such as localstack. If omitting a custom endpoint, it is mandatory to prefix the URI with awskms:/// (with three slashes).

If a custom endpoint is used, you may disable TLS verification by setting an environment variable AWS_TLS_INSECURE_SKIP_VERIFY=1.

AWS credentials are provided using standard configuration as described in AWS docs.

The $KEYID value must conform to any AWS KMS key identifier format as described in the linked document (Key ARN, Key ID, Alias ARN, or Alias ID).

Note that key creation is not supported by cosign if using the Key ARN or Key ID formats, so it is recommended to use Key Aliases for most situations.

The following URIs are valid:

  • Key ID: awskms:///1234abcd-12ab-34cd-56ef-1234567890ab
  • Key ID with endpoint: awskms://localhost:4566/1234abcd-12ab-34cd-56ef-1234567890ab
  • Key ARN: awskms:///arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
  • Key ARN with endpoint: awskms://localhost:4566/arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
  • Alias name: awskms:///alias/ExampleAlias
  • Alias name with endpoint: awskms://localhost:4566/alias/ExampleAlias
  • Alias ARN: awskms:///arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias
  • Alias ARN with endpoint: awskms://localhost:4566/arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias

Example:

$ export AWS_REGION=us-east-1
$ export AWS_CMK_ID=$(aws kms create-key 
                           --customer-master-key-spec RSA_4096 \
                           --key-usage SIGN_VERIFY \
                           --description "Cosign Signature Key Pair" \
                           --query KeyMetadata.KeyId --output text)

$ cosign sign --key awskms:///${AWS_CMK_ID} $IMAGE_DIGEST
$ cosign verify --key awskms:///${AWS_CMK_ID} $IMAGE_DIGEST | jq .

GCP

GCP KMS keys can be used in cosign for signing and verification.

The URI format for GCP KMS is:

gcpkms://projects/$PROJECT/locations/$LOCATION/keyRings/$KEYRING/cryptoKeys/$KEY/versions/$KEY_VERSION

Where $PROJECT, $LOCATION, $KEYRING, $KEY and $KEY_VERSION are replaced with the correct values.

Cosign automatically uses GCP Application Default Credentials for authentication. See the GCP API documentation for information on how to authenticate in different environments.

The user must have the following IAM roles:

  • Safer KMS Viewer Role
  • Cloud KMS CryptoKey Signer/Verifier (roles/cloudkms.signerVerifier)

Azure Key Vault

Azure Key Vault keys can be used in cosign for signing and verification. The URI format for Azure Key Vault is: azurekms://[VAULT_NAME][VAULT_URI]/[KEY] where $VAULT_NAME, $VAULT_URI, and $KEY are replaced with the correct values.

The following environment variables must be set to let cosign authenticate to Azure Key Vault. (see this reference for more details about Azure SDK Authentication):

  • AZURE_TENANT_ID
  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET

To create a key using cosign generate-key-pair --kms azurekms://[VAULT_NAME][VAULT_URI]/[KEY] you will need a user which has permissions to create keys in Key Vault. For example Key Vault Crypto Officer role.

To sign images using cosign sign --key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] [IMAGE_DIGEST] you will need a user which has permissions to the sign action such as the Key Vault Crypto User role.

Hashicorp Vault

Hashicorp Vault keys can be used in cosign for signing and verification. The URI format for Hashicorp Vault KMS is: hashivault://$keyname

This provider requires that the standard Vault environment variables ($VAULT_ADDR, $VAULT_TOKEN) are set correctly. This provider also requires that the transit secret engine is enabled.

The token needs (at least) the following permissions, that will be defined as an ACL policy in the next example. Suppose that the transit secret engine is mounted at the path /transit, and the $keyname is cosign, the policy would look like this:

path "transit/keys/cosign" {
  capabilities = ["read"]
}

path "transit/hmac/cosign/*" {
  capabilities = ["update"]
}

path "transit/sign/cosign/*" {
  capabilities = ["update"]
}

path "transit/verify/cosign" {
  capabilities = ["create"]
}

Kubernetes Secret

Cosign can use keys stored in Kubernetes Secrets to so sign and verify signatures. In order to generate a secret you have to pass cosign generate-key-pair a k8s://[NAMESPACE]/[NAME] URI specifying the namespace and secret name:

$ cosign generate-key-pair k8s://default/testsecret
Enter password for private key: ****
Enter again: ****
Successfully created secret testsecret in namespace default
Public key written to cosign.pub

After generating the key pair, cosign will store it in a Kubernetes secret using your current context. The secret will contain the private and public keys, as well as the password to decrypt the private key.

The secret has the following structure:

apiVersion: v1
kind: Secret
metadata:
  name: testsecret
  namespace: default
type: Opaque
data:
  cosign.key: LS0tLS1CRUdJTiBFTkNSWVBURUQgQ09TSUdOIFBSSVZBVEUgS0VZLS0tLS[...]==
  cosign.password: YWJjMTIz
  cosign.pub: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQo[...]==

When verifying an image signature using cosign verify, the key will be automatically decrypted using the password stored in the kubernetes secret under the cosign.password field.

Local Setup

For a local setup, you can run Vault yourself or use the docker-compose file from sigstore/sigstore as an example.

After running it:

export VAULT_ADDR=http://localhost:8200
export VAULT_TOKEN=testtoken
vault secrets enable transit

If you enabled transit secret engine at different path with the use of -path flag (i.e., $ vault secrets enable -path="someotherpath" transit), you can use TRANSIT_SECRET_ENGINE_PATH environment variable to specify this path while generating a key pair like the following:

TRANSIT_SECRET_ENGINE_PATH="someotherpath" cosign generate-key-pair --kms hashivault://testkey
Edit this page on GitHub
← Inspecting Gitsign Commit Signatures
Signing with Self-Managed Keys →