Rekeying & rotating Vault

Background

In order to prevent one person from having complete access to the system, Vault employs Shamir's Secret Sharing Algorithm. Under this process, a secret is divided into a subset of parts such that a subset of those parts are needed to reconstruct the original secret. Vault makes heavy use of this algorithm as part of the unsealing process.

When a Vault server is first initialized, Vault generates a root key (previously known as master key) and splits this root key into a series of key shares following Shamir's Secret Sharing Algorithm. The root key is used to decrypt the underlying encryption key. Vault uses the encryption key to encrypt data at rest in a storage backend such as Integrated Storage.

Each of these key shares is distributed to trusted parties in the organization. These parties must come together to "unseal" the Vault by entering their key share.

In some cases, you may want to re-generate the root key and its key shares. Here are a few examples:

• Someone joins or leaves the organization
• Security wants to change the number of shares or threshold
• Compliance mandates the keys be rotated at a regular interval

In addition to rekeying the root key, there may be an independent desire to rotate the underlying encryption key Vault uses to encrypt data at rest.

In Vault, rekeying and rotating are two separate operations. The process for generating a new root key and applying Shamir's algorithm is called "rekeying". The process for generating a new encryption key for Vault is called key "rotation".

Both the rekeying and rotating operations are fully online operations. Vault will continue to service requests uninterrupted during either of these processes.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Start interactive lab

Rekeying Vault

Rekeying the Vault requires a threshold number of unseal keys. Before continuing, you should ensure enough unseal key holders are available to assist with the rekeying to match the threshold configured when the keys were issued.

1. Initialize the rekeying operation. The flags represent the newly desired number of keys and threshold.

   $ vault operator rekey -init -key-shares=3 -key-threshold=2
   

   This will generate a nonce value and start the rekeying process. All other unseal keys must also provide this nonce value. This nonce value is not a secret, so it is safe to distribute over insecure channels like chat, email, or carrier pigeon.

   Note

   The examples in this tutorial are for Vault using the default Shamir's Secret Sharing based seal. If your Vault uses an HSM or Cloud KMS based auto unseal, then you need to run the command with -target=recovery flag to the rekey command to process recovery keys instead of unseal keys: vault operator rekey -init -key-shares=3 -key-threshold=2 -target=recovery

   Key                      Value
   ---                      -----
   Nonce                    3e6e2a84-eae4-9841-b68d-29edceb39036
   Started                  true
   Rekey Progress           0/3
   New Shares               3
   New Threshold            2
   Verification Required    false
   

2. Each key holder runs the following command and enters their unseal key.

   $ vault operator rekey
   
   Rekey operation nonce: 3e6e2a84-eae4-9841-b68d-29edceb39036
   Key (will be hidden):
   

   Example output:

   Key                      Value
   ---                      -----
   Nonce                    3e6e2a84-eae4-9841-b68d-29edceb39036
   Started                  true
   Rekey Progress           1/3
   New Shares               3
   New Threshold            2
   Verification Required    false
   

3. Repeat the step to complete the rekey operation. When the final unseal key holder enters their key, Vault will output the new unseal keys.

   Example output:

   Key 1: EDj4NZK6z5Y9rpr+TtihTulfdHvFzXtBYQk36dmBczuQ
   Key 2: sCkM1i5BGGNDFk5GsqtVolWRPyd5mWn2eZG0gUySiCF7
   Key 3: e5DUvDIH0cPU8Q+hh1KNVkkMc9lliliPVe9u3Fzbzv38
   
   Operation nonce: dc1aec3b-ae67-5780-b4b5-2a10ca05b17c
   
   Vault rekeyed with 3 keys and a key threshold of 2. Please
   securely distribute the above keys. When the vault is re-sealed,
   restarted, or stopped, you must provide at least 2 of these keys
   to unseal it again.
   
   Vault does not store the root key. Without at least 2 keys,
   your vault will remain permanently sealed.
   

   Like the initialization process, Vault supports PGP encrypting the resulting unseal keys and creating backup encryption keys for disaster recovery.

   Tip

   You can also verify that the newly generated keys are usable before the root key is actually rotated by specifying a -verify flag. You can learn more about key verification with this flag in the rekey API documentation.

Rotating the encryption key

Unlike rekeying the Vault, rotating Vault's encryption key does not require a quorum of unseal keys. Anyone with the proper permissions in Vault can perform the encryption key rotation.

Adjusting the automatic key rotation

1. View the current automatic rotation policy.

   $ vault read sys/rotate/config
   

   This returns the current status and configuration of automatic encryption key rotation.

   Example output:

   Key               Value
   ---               -----
   enabled           true
   interval          0
   max_operations    3865470566
   

2. Configure a time interval for automatic key rotation.

   $ vault write sys/rotate/config interval=2160h
   Success! Data written to: sys/rotate/config
   

3. Configure the maximum number of encryption operations per key.

   $ vault write sys/rotate/config max_operations=123456789
   Success! Data written to: sys/rotate/config
   

Manual key rotation

Trigger a key rotation.

$ vault operator rotate

Example output: The output displays the key version and installation time.

Success! Rotated key

Key Term            2
Install Time        23 Jul 21 21:41 UTC
Encryption Count    1

This adds a new key to the keyring. All new values written to the storage backend will be encrypted with this new key.

Help and Resources

• operator rekey CLI documentation
• operator rotate CLI documentation
• Rekey API documentation
• Rotate Encryption Key API documentation