Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Dynamic Secrets and Encryption

Vault Transit Key Rotation, Rewrap and Key Versions

Rotate Vault transit keys without downtime: key versions, min_decryption_version, min_encryption_version, rewrapping old ciphertext, auto rotation and a version timeline simulator.

Good cryptographic hygiene means changing keys on a schedule and after any suspected exposure. With transit you rotate the key, not your application. Vault keeps older versions so old ciphertext still decrypts, new data uses the newest version, and a rewrap operation upgrades stored ciphertext without ever exposing plaintext to your app.

Vault is not available on this site. CLI commands are real; JavaScript blocks are stand-ins that model versions and rewrapping with a toy cipher.

Rotating a key

Terminal
vault write -f transit/keys/orders/rotate
vault read transit/keys/orders
# latest_version         2
# min_decryption_version 1
# min_encryption_version 0

After rotation, transit/encrypt produces vault:v2:.... Old vault:v1:... values still decrypt because version 1 is kept. Nothing breaks, and nothing needs a deploy.

Version limits

Setting Meaning
latest_version Newest key version, used for new encryptions
min_encryption_version Lowest version allowed to encrypt (0 = latest)
min_decryption_version Lowest version allowed to decrypt

Raising min_decryption_version makes old versions unusable and lets you archive them out of memory; data still on those versions can no longer be read, so do this only after rewrapping.

Terminal
vault write transit/keys/orders/config min_decryption_version=2
vault write transit/keys/orders/trim min_available_version=2   # permanently deletes older versions

Trimming or raising the minimum decryption version is irreversible in practice. Rewrap and verify everything first, and keep backups of your own ciphertext.

Rewrapping

Rewrap takes ciphertext, decrypts it inside Vault with the old version and re-encrypts it with the latest, returning new ciphertext. The plaintext never leaves Vault.

Terminal
vault write transit/rewrap/orders ciphertext="vault:v1:8SDd3WHDOjf7mq69..."
# ciphertext  vault:v2:Q0xk...

A typical job reads rows whose prefix is older than the latest version, rewraps them in batches and updates the row. The policy needs update on transit/rewrap/orders.

JS Stand-in: rotate and rewrap

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Automatic rotation

Terminal
vault write transit/keys/orders/config auto_rotate_period=720h

Vault will rotate on that period. Combine it with a periodic rewrap job so old data follows. Consider your compliance rules: some standards require rotation at least every year; high-volume keys may rotate more often because AES-GCM has usage limits.

Planning a rotation program

flowchart LR
    A["Rotate key (v+1)"] --> B["New writes use v+1"]
    B --> C["Batch rewrap old rows"]
    C --> D["Check: no v-old prefixes left"]
    D --> E["Raise min_decryption_version"]
    E --> F["Trim old versions"]

The order matters: never raise the minimum before step D.

JS Stand-in: find rows that need rewrapping

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. After rotating a transit key, what happens to existing vault:v1: ciphertext?

    Old versions stay available until you raise the minimum or trim.
  2. 2. What does rewrap do?

    The plaintext never leaves Vault during rewrap.
  3. 3. When is it safe to raise min_decryption_version?

    Raising it earlier would make older data undecryptable.
  4. 4. Which setting makes Vault rotate on a schedule?

    auto_rotate_period on the key config enables periodic rotation.

Summary

  • Rotation adds a version; new data uses it, old data still decrypts.
  • Rewrap upgrades ciphertext without exposing plaintext.
  • Raise min_decryption_version and trim only after rewrapping.
  • Automate rotation and the rewrap job.

Next: Production Server Configuration