GCP Cloud KMS

The Key Management secrets engine supports lifecycle management of keys in GCP Cloud KMS key rings. This is accomplished by configuring a KMS provider resource with the gcpckms provider and other provider-specific parameter values.

The following sections describe how to properly configure the secrets engine to enable the functionality.

Authentication

The Key Management secrets engine must be configured with credentials that have sufficient permissions to manage keys in an existing GCP Cloud KMS key ring. The authentication parameters are described in the credentials section of the API documentation. The authentication parameters will be set with the following order of precedence:

1. GOOGLE_CREDENTIALS environment variable
2. KMS provider credentials parameter
3. Application default credentials

The service account must be authorized with the following minimum IAM permissions on the target key ring resource:

• cloudkms.cryptoKeys.create
• cloudkms.cryptoKeys.update
• cloudkms.importJobs.create
• cloudkms.importJobs.get
• cloudkms.importJobs.useToImport
• cloudkms.cryptoKeyVersions.list
• cloudkms.cryptoKeyVersions.destroy
• cloudkms.cryptoKeyVersions.update
• cloudkms.cryptoKeyVersions.create

Setup

1. Enable the secrets engine.

   $ vault secrets enable keymgmt
   

2. Configure the KMS provider resource named, example-kms.

   $ vault write keymgmt/kms/example-kms \
       provider="gcpckms" \
       key_collection="projects/<project-id>/locations/<location>/keyRings/<keyring>" \
       credentials=service_account_file="/path/to/service_account/credentials.json"
   

   The command specified the following:

   • The full path to this KMS provider instance in Vault (keymgmt/kms/example-kms).
   • The KMS provider type is set to gcpckms.
   • A key collection, which refers to the resource ID of an existing GCP Cloud KMS key ring; this value cannot be changed after creation.
   • Credentials file to use for authentication with GCP Cloud KMS. Supplying values for this parameter is optional, as credentials may also be specified as the GOOGLE_CREDENTIALS environment variable or default application credentials.

Usage

1. Write a new key of type aes256-gcm96 to the path keymgmt/key/aes256-gcm96.

   $ vault write keymgmt/key/aes256-gcm96 type="aes256-gcm96"
   

2. Read the aes256-gcm96 key, use JSON as the output, and pipe that into jq.

   $ vault read -format=json keymgmt/key/aes256-gcm96 | jq
   

   Example output:

   {
       "request_id": "631f98de-b755-9863-40db-f789ff9ff10a",
       "lease_id": "",
       "lease_duration": 0,
       "renewable": false,
       "data": {
           "deletion_allowed": false,
           "latest_version": 1,
           "min_enabled_version": 1,
           "name": "aes256-gcm96",
           "type": "aes256-gcm96",
           "versions": {
           "1": {
               "creation_time": "2021-11-16T13:07:17.878864-05:00"
           }
           }
       },
       "warnings": null
   }
   

   Notice the value of versions; it is 1 since this is the first version of the key that Vault knows about. This will figure into the example on key rotation later.

3. To use the keys you wrote, you must distribute them to the Cloud KMS. Add the aes256-gcm96 key to the Cloud KMS at the path keymgmt/kms/example-kms/key/aes256-gcm96.

   $ vault write keymgmt/kms/example-kms/key/aes256-gcm96 \
       purpose="encrypt,decrypt" \
       protection="hsm"
   

4. List the keys that have been distributed to the Cloud KMS instance.

   $ vault list keymgmt/kms/gcpckms/key/
   Keys
   ----
   aes256-gcm96
   

5. Rotate the key.

   $ vault write -f keymgmt/key/aes256-gcm96/rotate
   

6. Confirm successful key rotation by reading the key, and get the value of .data.latest_version.

   $  vault read -format=json keymgmt/key/aes256-gcm96 | jq '.data.latest_version'
   2
   

   The key is now at version 2; in the Cloud Console, the key will be expected to have a different version string than the original value under Primary version as shown in the Cloud Console UI screenshot.

Key transfer specification

Keys are securely transferred from the secrets engine to GCP Cloud KMS in accordance with the key import specification.

Key purpose compatability

The following table defines which key purposes can be used for each key type supported by GCP Cloud KMS.