Key Management Secrets Engine with GCP Cloud KMS

15min
|
Enterprise
Vault

Note

Key Management Secrets Engine requires Vault Enterprise Advanced Data Protection (ADP) license.

Challenge

You need to use security features of cloud providers, which involve encryption keys issued and stored by the provider in its own key management system (KMS), but you must also maintain root of trust and control of the encryption key lifecycle outside of the cloud.

Solution

The Vault Key Management Secrets Engine provides distribution and lifecycle management features for cloud provider keys.

Currently, it manages keys for the following cloud providers.

Personas

The end-to-end scenario described in this tutorial involves one persona:

admin a user with with privileged permissions to configure secrets engines.

Prerequisites

To perform the tasks described in this tutorial, you need to have:

A Google Cloud account with sufficient permissions to manage applications, service accounts, and Cloud Key Management Service (Cloud KMS).
Vault Enterprise with the Advanced Data Protection Module at version 1.9.0 or later.
jq is required to pretty print JSON output.

Policy requirements

Each persona requires a different set of capabilities. These are expressed in policies. If you are not familiar with policies, complete the policies tutorial.

The admin tasks require these capabilities.

# Mount secrets engines
path "sys/mounts/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Configure the default Key Management Secrets Engine instance
path "keymgmt/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

Start Vault dev server

In a new terminal session, start a Vault dev server with the value of the initial root token set to root.

$ vault server -dev -dev-root-token-id root

The Vault dev server defaults to listening at 127.0.0.1:8200. The server is also automatically initialized and unsealed.

Insecure operation

Do not run a Vault dev server in production. This approach starts a Vault server with an in-memory database and runs in an insecure way.

In another new terminal session, export an environment variable for the vault CLI to address the dev server.

$ export VAULT_ADDR=http://127.0.0.1:8200

Then export an environment variable for the vault CLI to authenticate with the Vault server.

$ export VAULT_TOKEN=root

Note

For these tasks, you can use Vault's root token. However, it is recommended that root tokens are only used for enough initial setup or in emergencies. As a best practice, use an authentication method or token that meets the policy requirements.

Refer to Dev Options to learn more about Vault dev server options.

The Vault dev server is now ready for use.

Scenario introduction

You will configure a Cloud KMS instance, then use the Vault CLI or HTTP API to configure a Vault development mode server and enable management of the Cloud KMS key with the Key Management secrets engine.

After initial configuration, you will perform some lifecycle operations with the secrets engine, like writing, reading, updating, and rotating keys.

Configure Cloud KMS

To follow this tutorial, you must configure a Google Cloud project, enable billing for the project, and enable the required Cloud KMS API.

You must then create a KMS keyring and note its resource name. The example used in this tutorial is projects/learn-kmse/locations/global/keyRings/learn-keyring.

You must also create a service account, and assign it the proper roles in the project to manage Cloud KMS keys. The minimum roles required are as follows:

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

You then need to generate a JSON based credential file for this service account that Vault will use to connect to and manage the Cloud KMS instance. You can also specify the credentials using the GOOGLE_CREDENTIALS environment variable or application default credentials. Consult the Key Management Secrets Engine documentation for more details.

Note

In this tutorial, the Cloud KMS instance is named learn-kmse and the service account is named learn-vault-kmse. As you follow the step-by-step instruction, be sure to use the Cloud KMS instance name and service account name that matches what you created if different.

You can refer to the Cloud KMS Quickstart documentation for further details on these steps.

When complete, you should have a Cloud KMS and keyring available in the Google Cloud Console as shown in this screenshot.

Screenshot showing Cloud KMS in Google Cloud

Enable Key Management secrets engine

You must first enable an instance of the Key Management Secrets engine before you can use it. The default behavior without specifying a path to enable the secrets engine on is to enable it at the path keymgmt/.

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"

Be sure to replace learn-kmse and learn-keyring with the appropriate project name and keyring name for your account if different.

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-gcm96
ecdsa-p256

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

Screenshot showing distribution of keys to Cloud KMS

Inspecting the key aes256-gcm96 shows its current version.

Screenshot showing Cloud KMS key 1 version

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

Screenshot showing Cloud KMS key 2 permitted operation

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

Note

This command line uses the force flag (-f) because there are no parameters passed as key/value pairs and in such cases, it is required to avoid an error.

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.

Screenshot showing key versions in Google Cloud Console

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_917bda48
identity_ae2e72fe
keymgmt_1342ce2f
kv_6bcb2c03
system_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

Be sure to replace learn-kmse and learn-keyring with the appropriate project name and keyring name for your account if different.

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.

Screenshot showing distribution of keys to Cloud KMS

Inspecting the key aes256-gcm96 shows its current version.

Screenshot showing Cloud KMS key 1 version

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

Screenshot showing Cloud KMS key 2 permitted operation

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

Note

This command line uses the force flag (-f) because there are no parameters passed as key/value pairs and in such cases, it is required to avoid an error.

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"
    }
  }
}

Screenshot showing key versions in Google Cloud Console

Cleanup

If you wish to clean up your environment after completing the tutorial, follow the steps in this section.

Unset the environment variables.

$ unset ROOT_TOKEN UNSEAL_KEY VAULT_ADDR LEARN_VAULT

Remove the credential file.

$ rm -f /tmp/credentials.json

Remove the JSON payload files.

$ rm -f \
    /tmp/kmse-gcpckms.json \
    /tmp/aes256-gcm96-key.json \
    /tmp/ecdsa-p256-key.json

You can stop the Vault server by pressing Ctrl+C where the server is running. Or, execute the following command.

$ pgrep -f vault | xargs kill

Summary

You have learned the basics about the Key Management secrets engine, including configuring Cloud KMS, enabling the secrets engine, and performing basic key lifecycle management operations.

From here, you can learn can learn about other Vault secrets engines in the Secrets tutorial collection.

Help and reference

Key management with Azure Key Vault

Next Collection

Secrets management

This tutorial also appears in:

28 tutorials

Vault Enterprise
Learn features that are only available to Vault Enterprise.
- Vault
6 tutorials

Advanced data protection
Advanced Data Protection is a Vault Enterprise module focused on securely connect, control, and integrate advanced encryption keys. Learn features that provide advanced data protection.
- Vault