Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท Dynamic Secrets and Encryption

Vault Transit Engine: Encryption as a Service

Use the Vault transit engine to encrypt data without storing keys in your app: create keys, encrypt and decrypt, understand vault:v1 ciphertext, sign, hash and generate data keys.

Applications often need to encrypt things: credit card numbers, personal data, tokens. Doing it in the app means managing keys, algorithms and mistakes. The transit secrets engine moves cryptography into Vault. Your app sends plaintext, Vault returns ciphertext, and the key never leaves Vault. Vault does not store the data; your database does. That is why transit is called "encryption as a service".

Vault is not available on this site. CLI calls are real. The JavaScript example uses a deliberately toy, insecure cipher purely to illustrate the data flow and the ciphertext format; never use it for real data.

Set up

Terminal
vault secrets enable transit
vault write -f transit/keys/orders          # default type aes256-gcm96
vault read transit/keys/orders

Key types include aes256-gcm96 (default, symmetric), chacha20-poly1305, rsa-2048/4096, ecdsa-p256, ed25519 (signing) and more. Plaintext must be base64-encoded for the API.

Terminal
vault write transit/encrypt/orders plaintext=$(echo -n "card 4111" | base64)
# ciphertext  vault:v1:8SDd3WHDOjf7mq69CyCqYjBXAiQQAVZRkFM13ok481zoCmHnSeDX9vyf7w==

vault write transit/decrypt/orders ciphertext="vault:v1:8SDd..."
# plaintext   Y2FyZCA0MTEx   (base64 again)

The prefix vault:v1: tells Vault which key version encrypted the data (see rotation). Store the whole string in your database.

Why use transit

  • Keys never enter application memory or logs.
  • Access is a policy: update on transit/encrypt/orders for writers, update on transit/decrypt/orders for readers. You can let a service encrypt without being able to decrypt.
  • All operations are audited.
  • Rotation and rewrapping need no application change.
HCL
path "transit/encrypt/orders" { capabilities = ["update"] }
path "transit/decrypt/orders" { capabilities = ["update"] }
JS Stand-in: the transit data flow (toy cipher)

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

No output.

Beyond encrypt and decrypt

  • Datakey: transit/datakey/plaintext/<key> returns a fresh data key in plaintext plus the same key encrypted by Vault. Your app encrypts large files locally with the plaintext key, stores the encrypted key beside them and discards the plaintext (envelope encryption). Use wrapped to get only the encrypted key.
  • Sign and verify: transit/sign/<key> and transit/verify/<key> with asymmetric keys, plus hmac for message authentication.
  • Hash and random: transit/hash and transit/random/32.
  • Convergent encryption: with convergent_encryption=true and a context value, the same plaintext and context produce the same ciphertext, enabling equality search at the cost of leaking duplicates.
  • Batch input: send many items in one request for throughput.
  • Format-preserving and tokenization are available through the transform engine (Enterprise).
JS Stand-in: envelope encryption idea

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

No output.

Limits

Transit is not a database: it does not keep your ciphertext. Treat the ciphertext string as opaque, store it in a column sized for the growth, and make sure the app can survive Vault being briefly unavailable (cache data keys carefully, or queue work).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must plaintext be when sent to transit/encrypt?

    The API accepts base64 so arbitrary bytes can travel as JSON.
  2. 2. What does the vault:v2: prefix in a ciphertext tell you?

    Vault uses the version to pick the right key to decrypt.
  3. 3. Where does transit store your ciphertext?

    Transit does not persist data; you store the returned ciphertext.
  4. 4. What is the purpose of a datakey?

    Datakeys enable envelope encryption of big payloads.

Summary

  • Transit does cryptography for you; keys stay inside Vault.
  • Ciphertext looks like vault:v<N>:... and is stored by your application.
  • Policies can separate who may encrypt from who may decrypt.
  • Datakeys, signing, HMAC and convergent mode extend the engine.

Next: Transit Key Rotation and Rewrap