Encryption as a Service · Topic 2 of 2
Rotating Transit Keys and Rewrapping
Vault Associate (003): rotate a transit key, see why old ciphertext still decrypts, rewrap data to the newest version and use min_decryption_version.
- 4 min
- Includes a diagram
- Rotate with
vault write -f transit/keys/<name>/rotate; it adds a new key version. - New encryptions use the latest version and show
vault:v2:after one rotation. - Old ciphertext still decrypts after rotation, as long as its version is at or above the minimum decryption version.
What it is
Key rotation adds a new version to a transit key. From then on, Vault uses the newest version to encrypt, and it keeps the older versions so existing ciphertext can still be decrypted.
Rotation is good practice even when no key is compromised, because it limits how much data is protected by one key version. Rewrap then moves old ciphertext onto the new version without ever showing the plaintext.
How it works
Rotate the key
Rotation is a single write to the rotate path of the key. No data is needed, so use -f.
vault write -f transit/keys/my-key/rotate
The API is POST /transit/keys/:name/rotate. The key now holds versions 1 and 2.
What happens to ciphertext
Data encrypted before the rotation still carries vault:v1: in its prefix, and Vault still decrypts it, because the old version stays in the keyring. Data encrypted after the rotation starts with vault:v2:.
Walking through it: you encrypt a record on Monday and get vault:v1:.... You rotate on Tuesday, and on Wednesday you encrypt a new record and get vault:v2:.... Decrypting either value works.
Rotation does not touch stored ciphertext. The old record stays on version 1 until you rewrap it.
Rewrap
Rewrap decrypts a ciphertext with the right key version and re-encrypts it with the newest one. The plaintext is never returned, so a process can be allowed to rewrap without being allowed to read the data.
vault write transit/rewrap/my-key ciphertext=vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U=
The response contains a new ciphertext starting with vault:v2:. The application then stores that value in place of the old one. The API is POST /transit/rewrap/:name.
A policy needs only update on transit/rewrap/my-key for this, so a batch job can rewrap stored records with no decrypt access.
Limit old versions with min_decryption_version
Each key has a min_decryption_version. Versions below it are archived and cannot be used to decrypt, and the remaining versions form the working set.
vault write transit/keys/my-key/config min_decryption_version=2
After this, a vault:v1: ciphertext can no longer be decrypted. That keeps obsolete, sensitive data out of reach, and the value can be lowered again in an emergency to restore access. Rewrap everything first, or the old data becomes unreadable.
A related setting, min_encryption_version, sets the lowest version allowed for encryption. Its default of 0 means the latest version.
Automatic rotation
A key can rotate on a schedule through auto_rotate_period. The default is 0, which means disabled, and the minimum when set is one hour.
vault write transit/keys/my-key/config auto_rotate_period=720h
How the exam asks about this
- "A key is rotated. Can data encrypted before the rotation still be decrypted?" Yes, because older versions remain available.
- "How do you move old ciphertext to the new key version without exposing plaintext?" Use rewrap.
- "Which setting stops old key versions from decrypting data?" min_decryption_version.
What to remember for the exam
- Rotate with
vault write -f transit/keys/<name>/rotate; it adds a new key version. - New encryptions use the latest version and show
vault:v2:after one rotation. - Old ciphertext still decrypts after rotation, as long as its version is at or above the minimum decryption version.
- Rewrap re-encrypts ciphertext under the latest version without revealing the plaintext.
- Raising
min_decryption_versionarchives older versions, so rewrap the data first. auto_rotate_periodrotates a key automatically; the minimum value is one hour.
Rotating a key does not re-encrypt data already stored. Until you rewrap it, old ciphertext stays on the old version, and raising min_decryption_version too early makes that data impossible to decrypt.
Common mistakes
Believing rotation breaks old data. It does not. The older versions stay in the keyring, so ciphertext with a v1 prefix still decrypts until the minimum decryption version is raised.
Assuming rotation re-encrypts everything. Only new encryption calls use the new version. Existing ciphertext changes only when you rewrap it and store the result.
Using decrypt then encrypt to upgrade data. That exposes the plaintext to the application. Rewrap does the same job inside Vault.
Check yourself
What does vault write -f transit/keys/my-key/rotate do?
It adds a new version to the key. New encryptions use it, and the older versions remain so old ciphertext still decrypts.
Why use rewrap instead of decrypt followed by encrypt?
Rewrap re-encrypts under the latest key version inside Vault and never returns the plaintext, so the caller does not need access to the data.
What does setting min_decryption_version=2 do?
It archives key versions below 2, so
vault:v1:ciphertext can no longer be decrypted. Rewrap the data first.
Topic 2 of 2 in Encryption as a Service
Test yourself on Encryption as a Service
The full HashiCorp Vault Associate 003 question bank has 600 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.