Demo Transit Secrets Engine

In this hands-on lab, you'll learn how to enable and configure the Vault Transit Secrets Engine. You’ll work through:

Enabling Transit at its mount point
Creating, rotating, and inspecting keys
Encrypting and decrypting data
Rewrapping ciphertext after key rotation
Enforcing a minimum decryption version

Note

This demo uses a Vault development server for simplicity. Do not use a dev server in production workloads.

Prerequisites

A running Vault development server (default mounts).
The vault CLI installed and authenticated (VAULT_ADDR, VAULT_TOKEN).

Default Mount	Type	Description
cubbyhole/	cubbyhole	Per-token private secret storage
identity/	identity	Identity store
secret/	kv	Key/value secret storage (KV v2)
sys/	system	System endpoints (control & policy)

1. Verify Installed Secret Engines

Ensure Transit is not yet enabled:

vault secrets list

Path	Type	Accessor	Description
cubbyhole/	cubbyhole	cubbyhole_XXXXXXXX	Per-token private secret storage
identity/	identity	identity_YYYYYYYY	Identity store
secret/	kv	kv_ZZZZZZZZZZZZ	Key/value secret storage (KV v2)
sys/	system	system_AAAAAAAA	System endpoints (control & policy)

2. Enable the Transit Secrets Engine

Enable at the default mount (transit/):

vault secrets enable transit

Confirm it’s listed:

vault secrets list

Path	Type	Accessor	Description
transit/	transit	transit_BBBBBBBB	Vault Transit Secrets

Optionally add a description when enabling:

vault secrets disable transit
vault secrets enable -description="My Transit Secrets Engine" transit

3. Create an Encryption Key

Create a new key named training (default: AES-256-GCM96):

vault write -f transit/keys/training

Inspect its metadata:

vault read transit/keys/training

Key metadata fields include latest_version, min_decryption_version, and supported operations.

4. Rotate the Key

Generate a new version for the training key:

vault write -f transit/keys/training/rotate
vault read transit/keys/training

You should see latest_version incremented.

5. Encrypt Data

First, Base64-encode your plaintext:

export PLAINTEXT_B64=$(echo -n "Getting Started with HashiCorp Vault" | base64)
echo $PLAINTEXT_B64

Encrypt with the training key:

vault write transit/encrypt/training plaintext=$PLAINTEXT_B64

Response fields:

Field	Description
ciphertext	Resulting ciphertext (e.g. `vault:v2:…`)
key_version	Version used for encryption

6. Rotate Again & Rewrap Ciphertext

Rotate to version 3:

vault write -f transit/keys/training/rotate

Rewrap an existing ciphertext (v2 → v3):

vault write transit/rewrap/training \
  ciphertext="vault:v2:…(old-ciphertext)…"

Response includes new ciphertext and key_version=3.

7. Decrypt Ciphertext

7.1 Decrypt Version 2

vault write transit/decrypt/training \
  ciphertext="vault:v2:…(old-ciphertext)…"

Decode the Base64 plaintext:

echo R2V0dGluZyBTdGFydGVkIHdpdGggSGFzaGlDb3JjIFZhdWx0 \
  | base64 --decode

7.2 Decrypt Version 3

vault write transit/decrypt/training \
  ciphertext="vault:v3:…(new-ciphertext)…"

8. Enforce a Minimum Decryption Version

Disallow decryption of data encrypted with older key versions:

vault write transit/keys/training/config min_decryption_version=3
vault read transit/keys/training

Key	Value
min_decryption_version	3
latest_version	3
keys	map[1:… 2:… 3:…]

Warning

After setting min_decryption_version=3, any attempt to decrypt version 2 will fail with:

Error writing data to transit/decrypt/training: ... ciphertext version is disallowed by policy