Setup guide - GCP Cloud KMS

To manage the lifecycle of the GCP Cloud KMS key rings, you need to setup the key management secrets engine using gcpckms provider.

Setup

1. Enable the key management 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.