Auto Unseal in Hashicorp Vault

A Hashicorp Vault build with Yandex Key Management Service support is available as a VM image in Cloud Marketplace and a Docker image. It differs from the primary version by a single binary Vault file that supports Key Management Service.

This build will enable you to use Key Management Service as a trusted service for encrypting secrets. This is implemented through the Auto Unseal mechanism.

In this guide, you will learn how to set up the Auto Unseal feature to work with KMS.

To set up Auto Unseal:

1. Prepare your cloud.
2. Set up Auto Unseal.

Prepare your cloudPrepare your cloud

1. Download the most recent Docker image using the command below:

   docker pull cr.yandex/yc/vault
   

2. Select one of the methods to authenticate Vault requests to KMS. You can authenticate via:

   Service account linked to your VM

   Any service account

   Yandex or federated account

   Authentication is performed using an Yandex Identity and Access Management token that is automatically extracted from the VM metadata. For more information, see Working with Yandex Cloud from inside a VM.

   Tip

   This option is the most preferable for security reasons. When configuring settings using the service account linked to the VM, you do not need to specify your credentials.

   An authorized key is used for authentication. For more information about how to use authorized keys, see Get an IAM token using the CLI.

   Authentication is done using an OAuth token or Identity and Access Management token.

   Tip

   This option is the least preferable for security reasons. We recommend that you only use it for testing.

3. Create a separate Key Management Service key for Vault (recommended).

4. Grant access to the key only to the user or service account that will be used to authenticate Vault requests to KMS. When working with KMS, Vault only performs encryption and decryption operations, so the kms.keys.encrypterDecrypter role is sufficient.

Required paid resourcesRequired paid resources

The infrastructure support costs include:

• Fee for a continuously running VM (see Yandex Compute Cloud pricing).
• Fee for using a dynamic or static external IP address (see Yandex Virtual Private Cloud pricing).
• Fee for the number of active KMS key versions and completed cryptographic operations (see Yandex Virtual Private Cloud pricing).

Set up Auto UnsealSet up Auto Unseal

To set up the Auto Unseal feature, make the following changes to the Vault configuration file:

1. Under seal, enter "yandexcloudkms" as the value.

2. Add the kms_key_id parameter with the KMS encryption key ID.

3. Authenticate using one the following methods:

   Service account linked to your VM

   Any service account

   Yandex or federated account

   Link a service account to a VM by following the instructions.

   In the service_account_key_file parameter, specify the path to the file with the service account's authorized key.

   If you are using a Yandex account, specify the OAuth token in the oauth_token parameter. For a federated account, specify the IAM token.

4. Change the configuration when performing migration based on the Vault version in use.

Sample configurationsSample configurations

...
seal "yandexcloudkms" {
  kms_key_id = "<KMS_key_ID>"
}
...

...
seal "yandexcloudkms" {
  kms_key_id               = "<KMS_key_ID>"
  service_account_key_file = "<path_to_JSON_file>"
}
...

...
seal "yandexcloudkms" {
  kms_key_id  = "<KMS_key_ID>"
  oauth_token = "<user_token>"
}
...

Key rotationKey rotation

When the Vault master key is encrypted with a KMS key, Vault also saves the key version it was encrypted with.

When the Vault master key is decrypted (at Vault restart), the saved version of the KMS key used to encrypt the Vault master key is compared with the primary version of the KMS key. If the key versions are different, the Vault master key is re-encrypted with the new primary version of the KMS key.

This way you can rotate the Vault master key through key rotation in KMS. Rotating the key in Key Management Service will automatically rotate the master key when Vault is restarted the next time.

How to delete the resources you createdHow to delete the resources you created

To stop paying for the resources you created:

• Delete the VM if you created one to run Vault.
• Delete the static public IP if you reserved one.
• Delete the Key Management Service key.

See alsoSee also

• HashiCorp Vault
• Seal/Unseal in Vault
• Seal configuration in Vault