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  ```