Key Management Secrets Engine with GCP Cloud KMS

Enable the secrets engine.

$ vault secrets enable keymgmt

The secrets engine is now enabled and ready for use.

Write keys

The Key Management secrets engine currently supports generation of the key types specified in Key Types.

Write a aes256-gcm96 key to the secrets engine.

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

With this command line syntax, you are instructing Vault to write a new key of type aes256-gcm96 to the path keymgmt/key/aes256-gcm96. The key that is written is for general purpose use, but you will set its specific use later.

You can do the same again to write the second key, but change the type to ecdsa-p256, and the path to keymgmt/key/ecdsa-p256.

$ vault write keymgmt/key/ecdsa-p256 type="ecdsa-p256"

Read keys

To learn about the content of a key, you can read it back. Let's read the aes256-gcm96 key, use JSON as the output, and pipe that into jq.

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

Your output should resemble this example.

{  "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.

Read the second key.

$ vault read -format=json keymgmt/key/ecdsa-p256 | jq

Your output should resemble this example.

{  "request_id": "858f8b0d-043c-113f-6f53-e5043cfdaf6f",  "lease_id": "",  "lease_duration": 0,  "renewable": false,  "data": {    "deletion_allowed": false,    "latest_version": 1,    "min_enabled_version": 1,    "name": "ecdsa-p256",    "type": "ecdsa-p256",    "versions": {      "1": {        "creation_time": "2021-11-16T13:08:23.499803-05:00",        "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAES7Zln/7LeCRHsNLXGQCgz23wwiZp\n97oiTsi9Jvpcsuf6pX2A2XipLWIhZfW2XvvUjAqS5oKnGw/XZc0jR+yF3g==\n-----END PUBLIC KEY-----\n"      }    }  },  "warnings": null}

Create KMS provider

The next step is to create the KMS provider configuration in Vault; this corresponds to the Cloud KMS instance you previously created in Google Cloud.

Create the KMS provider at the path keymgmt/kms/gcpckms.

$ vault write keymgmt/kms/gcpckms \    provider="gcpckms" \    key_collection="projects/learn-kmse/locations/global/keyRings/learn-keyring" \    credentials=service_account_file="/tmp/credentials.json"

In this command line example, you specified 4 pieces of information to successfully configure the Cloud KMS instance.

• The full path to this KMS provider instance in Vault (keymgmt/kms/gcpckms).
• 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.

Distribute keys to key vault

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

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

Write the second key to the path keymgmt/kms/gcpckms/key/ecdsa-p256 next, but specify that its purpose is for signing.

$ vault write keymgmt/kms/gcpckms/key/ecdsa-p256 \    purpose="sign" \    protection="hsm"

Verify keys

You can use the vault CLI to list the keys that have been distributed to the Cloud KMS instance.

$ vault list keymgmt/kms/gcpckms/key/Keys----aes256-gcm96ecdsa-p256

You can also visit the Cloud Console to confirm the key distribution.

Inspecting the key aes256-gcm96 shows its current version.

Inspecting the key ecdsa-p256 shows its permitted operations, which includes only Sign.

Rotate key

Key rotation is a fundamental part of the key management lifecycle. Let's use Vault to rotate the aes256-gcm96 key and then verify its version with the vault CLI and Cloud Console.

Rotate the key.

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

Confirm key rotation

You can confirm successful key rotation by reading the key with the CLI, and getting 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.

Enable the secrets engine.

$ curl \    --header "X-Vault-Token: root" \    --request POST \    --data '{"type": "keymgmt"}' \    $VAULT_ADDR/v1/sys/mounts/keymgmt

Successful execution produces no output.

Confirm the secrets engine is enabled.

$ curl \    --silent \    --header "X-Vault-Token: root" \    $VAULT_ADDR/v1/sys/mounts | jq -r '.data[].accessor'

Your output should resemble this example.

cubbyhole_917bda48identity_ae2e72fekeymgmt_1342ce2fkv_6bcb2c03system_a22e502b

The secrets engine is now enabled and ready for use. In the example output, its accessor is keymgmt_1342ce2f.

Write keys

The Key Management secrets engine currently supports generation of the key types specified in Key Types.

Write an aes256-gcm96 key to the secrets engine.

$ curl \    --header "X-Vault-Token: root" \    --request POST \    --data '{"type": "aes256-gcm96"}' \    $VAULT_ADDR/v1/keymgmt/key/aes256-gcm96

Successful execution produces no output.

You are instructing Vault to write a new key of type aes256-gcm96 to the path keymgmt/key/aes256-gcm96. The key that is written is for general purpose use, but you will set its specific use later.

You can do the same again to write the second key, but change the type to ecdsa-p256, and the path to keymgmt/key/ecdsa-p256.

$ curl \    --header "X-Vault-Token: root" \    --request POST \    --data '{"type": "ecdsa-p256"}' \    $VAULT_ADDR/v1/keymgmt/key/ecdsa-p256

Read keys

To learn about the content of a key, you can read it back. Let's read the aes256-gcm96 key, use JSON as the output, and pipe that into jq.

$ curl \    --silent \    --header "X-Vault-Token: root" \    $VAULT_ADDR/v1/keymgmt/key/aes256-gcm96 | jq

Your output should resemble this example.

{  "request_id": "624f7df2-02da-9e29-ddc9-7dc7c881fb05",  "lease_id": "",  "renewable": false,  "lease_duration": 0,  "data": {    "deletion_allowed": false,    "latest_version": 1,    "min_enabled_version": 1,    "name": "aes256-gcm96",    "type": "aes256-gcm96",    "versions": {      "1": {        "creation_time": "2021-11-16T13:24:29.122505-05:00"      }    }  },  "wrap_info": null,  "warnings": null,  "auth": null}

Notice the value of data.latest_version; 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.

Read the second key.

$ curl \    --silent \    --header "X-Vault-Token: root" \    $VAULT_ADDR/v1/keymgmt/key/ecdsa-p256 | jq

Output is similar to that of the aes256-gcm96 key:

{  "request_id": "4d7d116f-1d43-ce87-dbea-479ddeec215e",  "lease_id": "",  "renewable": false,  "lease_duration": 0,  "data": {    "deletion_allowed": false,    "latest_version": 1,    "min_enabled_version": 1,    "name": "ecdsa-p256",    "type": "ecdsa-p256",    "versions": {      "1": {        "creation_time": "2021-11-16T13:24:36.404709-05:00",        "public_key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEm6sK41Af7uLA9fBV4nK8mm3fFJkI\nVL4Phdx5ocfstqYQq84c77Bn+a9niqJQPOraKpOYYpVPo9Bb9WJbWYZ0gg==\n-----END PUBLIC KEY-----\n"      }    }  },  "wrap_info": null,  "warnings": null,  "auth": null}

Create KMS provider

The next step is to create the KMS provider configuration in Vault; this corresponds to the Cloud KMS instance you previously created in GCP.

Create the KMS provider at the path keymgmt/kms/gcpckms.

Write a JSON payload containing the KMS provider configuration.

$ cat > /tmp/kmse-gcpckms.json << EOF{  "key_collection": "projects/learn-kmse/locations/global/keyRings/learn-keyring",  "provider": "gcpckms",  "credentials": [ "service_account_file=/tmp/credentials.json" ]}EOF

Then, create the KMS provider using the JSON payload configuration.

$ curl \    --header "X-Vault-Token: root" \    --request PUT \    --data @/tmp/kmse-gcpckms.json \    $VAULT_ADDR/v1/keymgmt/kms/gcpckms

In this API example, you specified 4 pieces of information to successfully configure the Cloud KMS instance.

• The full path to this KMS provider instance in Vault (keymgmt/kms/gcpckms).
• 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 to use for authentication with GCP Cloud KMS. Supplying values for this parameter is optional, as credentials may also be specified as environment variables.

Distribute keys to key vault

To use the keys you wrote in step 3, you must first distribute them to the key vault you just created in step 5. Add the aes256-gcm96 key to the key vault at the path keymgmt/kms/gcpckms/key/aes256-gcm96.

Create a JSON payload to contain the aes256-gcm96 key configuration.

$ cat > /tmp/aes256-gcm96-key.json << EOF{  "protection": "hsm",  "purpose": "encrypt,decrypt"}EOF

$ curl \    --silent \    --header "X-Vault-Token: root" \    --request PUT \    --data @/tmp/aes256-gcm96-key.json \    $VAULT_ADDR/v1/keymgmt/kms/gcpckms/key/aes256-gcm96

Create a JSON payload to contain the ecdsa-p256 key configuration.

$ cat > /tmp/ecdsa-p256-key.json << EOF{  "protection": "hsm",  "purpose": "sign"}EOF

Write the second key to the path keymgmt/kms/gcpckms/key/ecdsa-p256.

$ curl \    --silent \    --header "X-Vault-Token: root" \    --request PUT \    --data @/tmp/ecdsa-p256-key.json \    $VAULT_ADDR/v1/keymgmt/kms/gcpckms/key/ecdsa-p256

Verify keys

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

$ curl \    --header "X-Vault-Token: root" \    --request LIST \    $VAULT_ADDR/v1/keymgmt/kms/gcpckms/key

Your output should resemble this example.

{  "data": {    "keys": ["aes256-gcm96", "ecdsa-p256"]  }}

You can also visit the Cloud Console to confirm the key distribution.

Inspecting the key aes256-gcm96 shows its current version.

Inspecting the key ecdsa-p256 shows its permitted operations, which includes only Sign.

Rotate key

Key rotation is a fundamental part of the key management lifecycle. Let's use Vault to rotate the aes256-gcm96 key and then verify its version with the vault CLI and Cloud Console.

Rotate the key.

$ curl \    --silent \    --header "X-Vault-Token: root" \    --request PUT \    $VAULT_ADDR/v1/keymgmt/key/aes256-gcm96/rotate

Confirm key rotation

You can confirm successful key rotation by reading the key, and getting the value of .data.latest_version.

$  curl \    --silent \    --header "X-Vault-Token: root" \    --request GET \    $VAULT_ADDR/v1/keymgmt/kms/gcpckms/key/aes256-gcm96

Your output should resemble this example.

{  "data": {    "name": "aes256-gcm96",    "protection": "hsm",    "purpose": "encrypt,decrypt",    "versions": {      "1": "96a8956194f4632bc1b45b13837b64ac",      "2": "ce657d33f64eb38f943012be543f3f52"    }  }}

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.