github.com/venafi-iw/cosign@v1.3.4/KMS.md (about) 1 # KMS Integrations 2 3 This page contains detailed instructions on how to configure `cosign` to work with KMS providers. 4 Right now `cosign` supports Hashicorp Vault, AWS KMS, and GCP KMS, and we are hoping to support more in the future! 5 6 ## Basic Usage 7 8 When referring to a key managed by a KMS provider, `cosign` takes a [go-cloud](https://gocloud.dev) style URI to refer to the specific provider. 9 For example: 10 11 `gcpkms://`, `awskms://`, or `hashivault://` 12 13 The URI path syntax is provider specific and explained in the section for each provider. 14 15 ### Key Generation and Management 16 17 To generate keys using a KMS provider, you can use the `cosign generate-key-pair` command with the `--kms` flag. 18 For example: 19 20 ```shell 21 $ cosign generate-key-pair --kms <some provider>://<some key> 22 ``` 23 24 The public key can be retrieved with: 25 26 ```shell 27 $ cosign public-key --key <some provider>://<some key> 28 -----BEGIN PUBLIC KEY----- 29 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXc+DQU8Pb7Xo2RWCjFG/f6qbdABN 30 jnVtSyKZxNzBfNMLLtVxdu8q+AigrGCS2KPmejda9bICTcHQCRUrD5OLGQ== 31 -----END PUBLIC KEY----- 32 ``` 33 34 ### Signing and Verification 35 36 To sign and verify using a key managed by a KMS provider, you can pass a provider-specific URI to the `--key` command: 37 38 ```shell 39 $ cosign sign --key <some provider>://<some key> gcr.io/dlorenc-vmtest2/demo 40 Pushing signature to: gcr.io/dlorenc-vmtest2/demo:sha256-410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd.cosign 41 42 $ cosign verify --key <some provider>://<some key> gcr.io/dlorenc-vmtest2/demo 43 44 Verification for gcr.io/dlorenc-vmtest2/demo -- 45 The following checks were performed on each of these signatures: 46 - The cosign claims were validated 47 - The signatures were verified against the specified public key 48 - Any certificates were verified against the Fulcio roots. 49 50 [{"critical":{"identity":{"docker-reference":"gcr.io/dlorenc-vmtest2/demo"},"image":{"docker-manifest-digest":"sha256:410a07f17151ffffb513f942a01748dfdb921de915ea6427d61d60b0357c1dcd"},"type":"cosign container image signature"},"optional":null}] 51 ``` 52 53 You can also export the public key and verify against that file: 54 55 ```shell 56 $ cosign public-key --key <some provider>://<some key> > kms.pub 57 $ cosign verify --key kms.pub gcr.io/dlorenc-vmtest2/demo 58 ``` 59 60 ### Providers 61 62 This section contains the provider-specific documentation. 63 64 65 ### AWS 66 67 AWS KMS keys can be used in `cosign` for signing and verification. 68 The URI format for AWS KMS is: 69 70 `awskms://$ENDPOINT/$KEYID` 71 72 where ENDPOINT and KEYID are replaced with the correct values. 73 74 The ENDPOINT value is left blank in most scenerios, but can be set for testing with KMS-compatible servers such as [localstack](https://localstack.cloud/). 75 If omitting a custom endpoint, it is mandatory to prefix the URI with `awskms:///` (with three slashes). 76 77 If a custom endpoint is used, you may disable TLS verification by setting an environment variable: `AWS_TLS_INSECURE_SKIP_VERIFY=1`. 78 79 AWS credentials are provided using standard configuration as [described in AWS docs](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials). 80 81 The KEYID value must conform to any [AWS KMS key identifier](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) 82 format as described in the linked document (Key ARN, Key ID, Alias ARN, or Alias ID). 83 84 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](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html) 85 for most situations. 86 87 The following URIs are valid: 88 89 - Key ID: `awskms:///1234abcd-12ab-34cd-56ef-1234567890ab` 90 - Key ID with endpoint: `awskms://localhost:4566/1234abcd-12ab-34cd-56ef-1234567890ab` 91 - Key ARN: `awskms:///arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab` 92 - Key ARN with endpoint: `awskms://localhost:4566/arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab` 93 - Alias name: `awskms:///alias/ExampleAlias` 94 - Alias name with endpoint: `awskms://localhost:4566/alias/ExampleAlias` 95 - Alias ARN: `awskms:///arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias` 96 - Alias ARN with endpoint: `awskms://localhost:4566/arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias` 97 98 ### GCP 99 100 GCP KMS keys can be used in `cosign` for signing and verification. 101 The URI format for GCP KMS is: 102 103 `gcpkms://projects/$PROJECT/locations/$LOCATION/keyRings/$KEYRING/cryptoKeys/$KEY/versions/$KEY_VERSION` 104 105 where PROJECT, LOCATION, KEYRING, KEY and KEY_VERSION are replaced with the correct values. 106 107 Cosign automatically uses GCP Application Default Credentials for authentication. 108 See the GCP [API documentation](https://cloud.google.com/docs/authentication/production) for information on how to authenticate in different environments. 109 110 The user must have the following IAM roles: 111 * Safer KMS Viewer Role 112 * Cloud KMS CryptoKey Signer/Verifier (`roles/cloudkms.signerVerifier`) 113 114 ### Azure Key Vault 115 116 Azure Key Vault keys can be used in `cosign` for signing and verification. 117 118 The URI format for Azure Key Vault is: 119 `azurekms://[VAULT_NAME][VAULT_URI]/[KEY]` 120 121 where VAULT_NAME, VAULT_URI, and KEY are replaced with the correct values. 122 123 The following environment variables must be set to let cosign authenticate to Azure Key Vault. (see this [reference](https://devblogs.microsoft.com/azure-sdk/authentication-and-the-azure-sdk/#environment-variables) for more details about Azure SDK Authentication) 124 - AZURE_TENANT_ID 125 - AZURE_CLIENT_ID 126 - AZURE_CLIENT_SECRET 127 128 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. 129 130 To sign images using `cosign sign -key azurekms://[VAULT_NAME][VAULT_URI]/[KEY] [IMAGE]` you will need a user which has permissions to the sign action such as the `Key Vault Crypto User` role. 131 132 ### Hashicorp Vault 133 134 Hashicorp Vault keys can be used in `cosign` for signing and verification. 135 The URI format for Hashicorp Vault KMS is: 136 137 `hashivault://$keyname` 138 139 This provider requires that the standard Vault environment variables (VAULT_ADDR, VAULT_TOKEN) are set correctly. 140 This provider also requires that the `transit` secret engine is enabled 141 142 ### Kubernetes Secret 143 144 Cosign can use keys stored in Kubernetes Secrets to so sign and verify signatures. In 145 order to generate a secret you have to pass `cosign generate-key-pair` a 146 `k8s://[NAMESPACE]/[NAME]` URI specifying the namespace and secret name: 147 148 ``` 149 cosign generate-key-pair k8s://default/testsecret 150 Enter password for private key: **** 151 Enter again: **** 152 Successfully created secret testsecret in namespace default 153 Public key written to cosign.pub 154 ``` 155 156 After generating the key pair, cosign will store it in a Kubernetes secret using 157 your current context. The secret will contain the private and public keys, as 158 well as the password to decrypt the private key. 159 160 The secret has the following structure: 161 162 ``` 163 apiVersion: v1 164 kind: Secret 165 metadata: 166 name: testsecret 167 namespace: default 168 type: Opaque 169 data: 170 cosign.key: LS0tLS1CRUdJTiBFTkNSWVBURUQgQ09TSUdOIFBSSVZBVEUgS0VZLS0tLS[...]== 171 cosign.password: YWJjMTIz 172 cosign.pub: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQo[...]== 173 ``` 174 175 When verifying an image signature using `cosign verify`, the key will be automatically 176 decrypted using the password stored in the kubernetes secret under the `cosign.password` 177 field. 178 179 #### Local Setup 180 181 For a local setup, you can run Vault yourself or use the `docker-compose` file from [sigstore/sigstore](https://github.com/sigstore/sigstore/blob/main/test/e2e/docker-compose.yml) as an example. 182 183 After running it: 184 185 ```shell 186 $ export VAULT_ADDR=http://localhost:8200 187 $ export VAULT_TOKEN=testtoken 188 $ vault secrets enable transit 189 ``` 190 191 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: 192 193 ```shell 194 $ TRANSIT_SECRET_ENGINE_PATH="someotherpath" cosign generate-key-pair --kms hashivault://testkey 195 ```