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
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:
| 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
| Path | Type | Accessor | Description |
|---|
| transit/ | transit | transit_BBBBBBBB | Vault Transit Secrets |
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
vault read transit/keys/training
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
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
training key:
vault write transit/encrypt/training plaintext=$PLAINTEXT_B64
| 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
vault write transit/rewrap/training \
ciphertext="vault:v2:…(old-ciphertext)…"
ciphertext and key_version=3.
7. Decrypt Ciphertext
7.1 Decrypt Version 2
vault write transit/decrypt/training \
ciphertext="vault:v2:…(old-ciphertext)…"
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:…] |
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
References
