The transit secrets engine handles cryptographic functions on data in-transit. OpenBao doesn't store the data sent to the secrets engine. Enable the transit secrets engine to provide encryption-as-a-service for application data. Follows the Transit secrets engine guide.
Prerequisites checklist
Confirm these before running steps:
- OpenBao deployed, initialised, and unsealed
- Token or auth method with transit engine access
- Understanding of envelope encryption concepts
1Enable the transit secrets engine
bao secrets enable transit2Create a named encryption key for PII data
Usually each application has its own encryption key.
bao write -f transit/keys/pii-key type=aes256-gcm963Encrypt a plaintext value (email)
Let's encrypt the email address user@example.com.
bao write transit/encrypt/pii-key plaintext=$(echo -n 'user@example.com' | base64)Key Value
--- -----
ciphertext vault:v1:8NqVMvkSQZtbEWQYM4oGsPOH5Y2JowtV/OCbk8Kcqz2kKNFlBRfRrhdBlOk=
key_version 14Decrypt the ciphertext back to plaintext
Use the
ciphertext from the previous step to decrypt the value.bao write transit/decrypt/pii-key ciphertext=vault:v1:<ciphertext>Key Value
--- -----
plaintext dXNlckBleGFtcGxlLmNvbQ==Decode the base64 plaintext:
echo dXNlckBleGFtcGxlLmNvbQ== | base64 -d→ Success: prints user@example.com
5Encrypt a batch of values
POST a batch over HTTPS and encode each plaintext dynamically with base64.
curl -sSk -H "X-Vault-Token: $BAO_TOKEN" \
--data "{\"batch_input\":[\
{\"plaintext\":\"$(echo -n 'user@example.com' | base64)\"},\
{\"plaintext\":\"$(echo -n '123-45-6789' | base64)\"}\
]}" \
"$BAO_ADDR/v1/transit/encrypt/pii-key"→ Success: Batch encryption returns an array of ciphertexts.
6Verify the current key version (should be 1)
bao read transit/keys/pii-key→ Success: latest_version should be 1
7Rotate the encryption key
bao write -f transit/keys/pii-key/rotate→ Success: latest_version should now be incremented to 2
8Rewrap existing ciphertext with the new key version
Decrypt with the old key version and re-encrypt with the latest — without exposing plaintext to the caller.
bao write transit/rewrap/pii-key ciphertext=vault:v1:<old-ciphertext>9Set minimum decryption version to enforce key rotation
Reject decryption with older key versions so obsolete ciphertext cannot be read.
bao write transit/keys/pii-key/config min_decryption_version=2Verify the config:
bao read transit/keys/pii-key→ Success:
min_decryption_version is 2Confirm old ciphertext is rejected:
bao write transit/decrypt/pii-key ciphertext=vault:v1:<old-ciphertext>→ Success: error — * ciphertext or signature version is disallowed by policy (too old)