open-vault/website/source/docs/secrets/transit/index.html.md

layout	page_title	sidebar_current	description
docs	Secret Backend: Trasit	docs-secrets-transit	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/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.

This page will show a quick start for this backend. For detailed documentation on every path, use vault 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 transit/policy/foo test=1
Success! Data written to: transit/policy/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/policy/foo
Key        	Value
name       	foo
cipher_mode	aes-gcm
key        	PhKFTALCmhAhVQfMBAH4+UwJ6J2gybapUH9BsrtIgR8=

Here we can see that the randomly generated encryption key being used, as well as the AES-GCM cipher mode. We don't need to know any of this to use the key however.

Now, if we wanted to encrypt a piece of plain text, we use the encrypt endpoint using our named key:

$ echo "the quick brown fox" | base64 | vault write transit/encrypt/foo plaintext=-
Success! Data written to: transit/encrypt/foo

TODO: Should return the cipher text

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=foo
$ echo "dGhlIHF1aWNrIGJyb3duIGZveAo=" | base64 -D
the quick brown fox

TODO: Should return the plaintext

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/policy/ ### POST

Description

Creates a new named encryption key. This is a root protected endpoint.

Method

POST

URL

`/transit/policy/`

Parameters

None

Returns

```javascript
{
  "data": {
      "name":        "foo",
      "cipher_mode": "aes-gcm",
      "key":         "PhKFTALCmhAhVQfMBAH4+UwJ6J2gybapUH9BsrtIgR8="
  }
}
```

GET

Description

Returns information about a named encryption key. This is a root protected endpoint.

Method

GET

URL

`/transit/policy/`

Parameters

None

Returns

```javascript
{
  "data": {
      "name":        "foo",
      "cipher_mode": "aes-gcm",
      "key":         "PhKFTALCmhAhVQfMBAH4+UwJ6J2gybapUH9BsrtIgR8="
  }
}
```

DELETE

Description

Deletes a named encryption key. This is a root protected endpoint. All data encrypted with the named key will no longer be decryptable.

Method

DELETE

URL

`/transit/policy/`

Parameters

None

Returns

A `204` response code.

/transit/encrypt/

POST

Description

Encrypts the provided plaintext using the named key.

Method

POST

URL

`/transit/encrypt/`

Parameters

• plaintext required The plaintext to encrypt, provided as base64 encoded.

Returns

```javascript
{
    "data": {
        "ciphertext": "vault:v0:abcdefgh"
    }
}
```

/transit/decrypt/

POST

Description

Dencrypts the provided ciphertext using the named key.

Method

POST

URL

`/transit/decrypt/`

Parameters

• ciphertext required The ciphertext to decrypt, provided as returned by encrypt.

Returns

```javascript
{
    "data": {
        "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo="
    }
}
```