Transit secrets engine

The transit secret engine is Vault's "encryption as a service": it manages keys and performs encrypt/decrypt/sign/verify/HMAC/datakey operations without ever returning the underlying key material. Source: builtin/logical/transit/ and the heavy lifting in sdk/helper/keysutil/.

Purpose

Let applications encrypt data without reinventing key management:

• One named key per workload, rotated on demand or on a schedule.
• Multiple key types: AES-256-GCM, AES-256-SIV, ChaCha20-Poly1305, RSA, Ed25519, ECDSA, MANAGED (HSM-backed).
• Versioned keys: rewrap operations let you migrate ciphertext to the latest version.
• Convergent / batched / context-bound flavors of encryption.

Key types and operations

sdk/helper/keysutil/ defines the supported algorithms in KeyType:

Type	Operations
aes256-gcm96, aes128-gcm96	encrypt, decrypt, datakey, rewrap
aes256-cmac, aes128-cmac	HMAC-style MAC
aes256-siv	convergent encrypt
chacha20-poly1305	encrypt/decrypt
ed25519	sign, verify, generate-deterministic-key (CSPRNG-derived)
ecdsa-p256, ecdsa-p384, ecdsa-p521	sign, verify
rsa-2048, rsa-3072, rsa-4096	sign, verify, encrypt, decrypt
hmac	HMAC
managed_key	dispatch to a managed key (HSM/Cloud KMS via go-kms-wrapping)

Per-operation paths live under transit/encrypt/<key>, transit/decrypt/<key>, transit/sign/<key>, transit/verify/<key>, transit/hmac/<key>, transit/datakey/<plaintext|wrapped>/<key>, transit/rewrap/<key>.

Key lifecycle

stateDiagram-v2
    [*] --> v1: vault write transit/keys/<n>
    v1 --> v2: rotate
    v2 --> v3: rotate
    v3 --> backup: vault write transit/backup/<n>
    backup --> restored: vault write transit/restore name=<n> backup=<bundle>
    v3 --> trimmed: trim_min_version raised
    trimmed: ciphertext at v1 still decryptable
    state trimmed {
      [*] --> Active: only ≥ trim_min_version
    }
    v3 --> archive: archived (decryptable but not encryptable)
    archive --> deleted: deletion_allowed && delete

Each rotation appends a new version; old ciphertext keeps decrypting against its original version. rewrap migrates ciphertext to the current latest version. trim_min_version lets operators retire really old versions, irrevocably.

BYOK and managed keys

Two flavors of bring-your-own-key:

• Import (transit/keys/<name>/import): export your AES key wrapped with Vault's transit RSA key, send the wrapped blob, Vault unwraps and stores it. CLI: vault transit import-key. Implementation in sdk/helper/keysutil/.
• Managed key (type=managed_key): the key never lives in Vault — it lives in an external KMS or HSM. Vault calls out for every operation. Configured via the managed_keys config block.

Convergent encryption and context

For deterministic encryption (where the same plaintext always produces the same ciphertext, given the same context), use convergent_encryption=true plus a context parameter on every operation. This enables searchable encryption patterns at the cost of leaking equality information.

Caching

sdk/helper/keysutil/ keeps an in-process LRU cache of decrypted key versions. Operators can configure cache_size per backend; the cache is reset on key version changes.

Integration points

• Hosted by builtin/logical/transit/.
• Crypto primitives in sdk/helper/keysutil/.
• HSM/KMS dispatch via go-kms-wrapping (managed key flow).
• Used as a seal type by other Vault clusters: seal "transit" in another cluster's config.
• Transit can also act as a JWKS provider: transit/jwks gives third parties the public keys.

Entry points for modification

• Add a new key type: extend KeyType in sdk/helper/keysutil/policy.go and add operations.
• Add a new mode (e.g. AES-XTS): add a Backend.Encrypt/Decrypt path and the corresponding crypto.
• Tweak datakey output formats: see builtin/logical/transit/path_datakey.go.
• Managed key wiring: vault/managed_key_registry.go and sdk/logical/managed_key.go.