Use envelope encryption

Transit facilitates the use of envelope encryption, a pattern where Transit produces sets of Data Encryption Keys (DEKs) and Encrypted Data Keys (EDKs), which a client side library uses to encrypt information client side and embed the EDK into the result.

At decryption time, the client:

1. Authenticates to Vault.
2. Provides the EDK and requests decryption from Transit.
3. Transit provides the decrypted DEK.
4. The client uses the DEK to decrypt the data.

Setup and permissions

The data key set endpoints are applicable to Transit symmetric encryption keys. To use Envelope Encryption, create a symmetric encryption The data key set endpoints apply to Transit symmetric encryption keys. To use envelope encryption, create a symmetric encryption key, ideally aes256-gcm96 or chacha20-poly1305.

Assuming a transit mount called transit_mount and a symmetric key named encryption_key, you need to create an ACL policy for callers that perform client-side envelope encryption with the following permissions:

path "transit_mount/encryption_key/datakeys" {  
  capabilities = ["create", "update"]
}

path "transit_mount_/encryption_key/derived_keys" {  
  capabilities = ["create", "update"]
}

For decryption, include the /decrypt endpoint:

path "transit_mount/encryption_key/decrypt" {  
  capabilities = ["create", "update"]
}

SDK

To simplify the encryption and decryption process in application logic, we provide a Go SDK that handles key fetching from Transit and provides functions for encrypting and decrypting from streams.

Command Line

The Vault CLI includes commands for using the data key set endpoints to easily encrypt and decrypt files and streams locally.