--- layout: "docs" page_title: "Secret Backend: Transit" sidebar_current: "docs-secrets-transit" description: |- The transit secret backend for Vault encrypts/decrypts data in-transit. It doesn't store any secrets. --- # Transit Secret Backend Name: `transit` The transit secret backend is used to encrypt/decrypt data in-transit. Vault doesn't store the data sent to the backend. It can also be viewed as "encryption as a service." The primary use case for the transit backend is to encrypt data from applications while still storing that encrypted data in some primary data store. This relieves the burden of proper encryption/decryption from application developers and pushes the burden onto the operators of Vault. Operators of Vault generally include the security team at an organization, which means they can ensure that data is encrypted/decrypted properly. Additionally, since encrypt/decrypt operations must enter the audit log, any decryption event is recorded. Due to Vault's flexible ACLs, other interesting use-cases are possible. For instance, one set of Internet-facing servers can be given permission to encrypt with a named key but not decrypt with it; a separate set of servers not directly connected to the Internet can then perform decryption, reducing the data's attack surface. As of Vault 0.2, the transit backend supports doing key derivation. This allows data to be encrypted within a context such that the same context must be used for decryption. This can be used to enable per-transaction unique keys which further increase the security of data at rest. As of Vault 0.3, the transit backend gained two new key features: key rotation and datakey generation. Key rotation allows a new version of the named key to be generated. All data encrypted with the key will use the newest version of the key; previously encrypted data can be decrypted using old versions of the key. Administrators can control which previous versions of a key are available for decryption, to prevent an attacker gaining an old copy of ciphertext to be able to successfully decrypt it. At any time, a legitimate user can "rewrap" the data, providing an old version of the ciphertext and receiving a new version encrypted with the latest key. Because rewrapping does not expose the plaintext, using Vault's ACL system, this can even be safely performed by unprivileged users or cron jobs. Datakey generation allows processes to request a high-entropy key of a given bit length be returned to them, encrypted with the named key. Normally this will also return the key in plaintext to allow for immediate use, but this can be disabled to accommodate auditing requirements. N.B.: As part of adding rotation support, the initial version of a named key now produces ciphertext starting with version 1, i.e. containing `:v1:`. Existing keys, when rotated, will jump to version 2 despite their previous ciphertext output containing `:v0:`. Decryption, however, treats version 0 and version 1 the same, so old ciphertext will still work. This page will show a quick start for this backend. For detailed documentation on every path, use `vault path-help` after mounting the backend. ## Quick Start The first step to using the transit backend is to mount it. Unlike the `generic` backend, the `transit` backend is not mounted by default. ``` $ vault mount transit Successfully mounted 'transit' at 'transit'! ``` The next step is to create a named encryption key. A named key is used so that many different applications can use the transit backend with independent keys. This is done by doing a write against the backend: ``` $ vault write -f transit/keys/foo Success! Data written to: transit/keys/foo ``` This will create the "foo" named key in the transit backend. We can inspect the settings of the "foo" key by reading it: ``` $ vault read transit/keys/foo Key Value name foo cipher_mode aes-gcm derived false ```` Now, if we wanted to encrypt a piece of plain text, we use the encrypt endpoint using our named key: ``` $ echo -n "the quick brown fox" | base64 | vault write transit/encrypt/foo plaintext=- Key Value ciphertext vault:v1:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/KUvv ``` The encryption endpoint expects the plaintext to be provided as a base64 encoded strings, so we must first convert it. Vault does not store the plaintext or the ciphertext, but only handles it _in transit_ for processing. The application is free to store the ciphertext in a database or file at rest. To decrypt, we simply use the decrypt endpoint using the same named key: ``` $ vault write transit/decrypt/foo ciphertext=vault:v1:czEwyKqGZY/limnuzDCUUe5AK0tbBObWqeZgFqxCuIqq7A84SeiOq3sKD0Y/KUvv Key Value plaintext dGhlIHF1aWNrIGJyb3duIGZveAo= $ echo "dGhlIHF1aWNrIGJyb3duIGZveAo=" | base64 -D the quick brown fox ``` Using ACLs, it is possible to restrict using the transit backend such that trusted operators can manage the named keys, and applications can only encrypt or decrypt using the named keys they need access to. ## API ### /transit/keys/ #### POST
Description
Creates a new named encryption key. This is a root protected endpoint.
Method
POST
URL
`/transit/keys/`
Parameters
Returns
A `204` response code.
#### GET
Description
Returns information about a named encryption key. The `keys` object shows the creation time of each key version; the values are not the keys themselves. This is a root protected endpoint.
Method
GET
URL
`/transit/keys/`
Parameters
None
Returns
```javascript { "data": { "cipher_mode": "aes-gcm", "deletion_allowed": false, "derived": false, "keys": { "1": 1442851412 }, "min_decryption_version": 0, "name": "foo" } } ```
#### DELETE
Description
Deletes a named encryption key. This is a root protected endpoint. It will no longer be possible to decrypt any data encrypted with the named key. Because this is a potentially catastrophic operation, the `deletion_allowed` tunable must be set in the key's `/config` endpoint.
Method
DELETE
URL
`/transit/keys/`
Parameters
None
Returns
A `204` response code.
### /transit/keys/config #### POST
Description
Allows tuning configuration values for a given key. (These values are returned during a read operation on the named key.) This is a root-protected endpoint.
Method
POST
URL
`/transit/keys//config`
Parameters
Returns
A `204` response code.
### /transit/keys/rotate/ #### POST
Description
Rotates the version of the named key. After rotation, new plaintext requests will be encrypted with the new version of the key. To upgrade ciphertext to be encrypted with the latest version of the key, use the `rewrap` endpoint. This is a root-protected endpoint.
Method
POST
URL
`/transit/keys//rotate`
Parameters
None
Returns
A `204` response code.
### /transit/encrypt/ #### POST
Description
Encrypts the provided plaintext using the named key. If the named key does not already exist, it will be automatically generated for the given name with the default parameters.
Method
POST
URL
`/transit/encrypt/`
Parameters
Returns
```javascript { "data": { "ciphertext": "vault:v1:abcdefgh" } } ```
### /transit/decrypt/ #### POST
Description
Decrypts the provided ciphertext using the named key.
Method
POST
URL
`/transit/decrypt/`
Parameters
Returns
```javascript { "data": { "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=" } } ```
### /transit/rewrap/ #### POST
Description
Rewrap the provided ciphertext using the latest version of the named key. Because this never returns plaintext, it is possible to delegate this functionality to untrusted users or scripts.
Method
POST
URL
`/transit/rewrap/`
Parameters
Returns
```javascript { "data": { "ciphertext": "vault:v2:abcdefgh" } } ```
### /transit/datakey/ #### POST
Description
Generate a new high-entropy key and the valued encrypted with the named key. Optionally return the plaintext of the key as well. Whether plaintext is returned depends on the path; as a result, you can use Vault ACL policies to control whether a user is allowed to retrieve the plaintext value of a key. This is useful if you want an untrusted user or operation to generate keys that are then made available to trusted users.
Method
POST
URL
`/transit/datakey//`
Parameters
Returns
```javascript { "data": { "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=", "ciphertext": "vault:v1:abcdefgh" } } ```