2018-07-27 23:08:52 +00:00
|
|
|
---
|
2020-01-18 00:18:09 +00:00
|
|
|
layout: guides
|
|
|
|
page_title: Encryption as a Service - Guides
|
|
|
|
sidebar_title: Encryption as a Service
|
|
|
|
description: >-
|
|
|
|
HashiCorp Vault's transit secrets engine handles cryptographic functions on
|
|
|
|
data in-transit. It can also viewed as _encryption as a service_.
|
2018-07-27 23:08:52 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
# Encryption as a Service: Transit Secrets Engine
|
|
|
|
|
|
|
|
Vault's `transit` secrets engine handles cryptographic functions on
|
|
|
|
data-in-transit. Vault doesn't store the data sent to the secrets engine, so it
|
2020-01-18 00:18:09 +00:00
|
|
|
can also be viewed as **_encryption as a service_**.
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
Although the `transit` secrets engine provides additional features (sign and
|
|
|
|
verify data, generate hashes and HMACs of data, and act as a source of random
|
|
|
|
bytes), its primary use case is to encrypt data. This relieves the burden of
|
|
|
|
proper encryption/decryption from application developers and pushes the burden
|
|
|
|
onto the operators of Vault.
|
|
|
|
|
|
|
|
## Reference Materials
|
|
|
|
|
2020-01-22 20:05:41 +00:00
|
|
|
- [Transit Secret Engine](/docs/secrets/transit)
|
|
|
|
- [Transit Secret Engine API](/api/secret/transit)
|
2018-07-27 23:08:52 +00:00
|
|
|
- [Transparent Data Encryption in the Modern Datacenter](https://www.hashicorp.com/blog/transparent-data-encryption-in-the-modern-datacenter)
|
|
|
|
|
|
|
|
~> **NOTE:** An [interactive
|
|
|
|
tutorial](https://www.katacoda.com/hashicorp/scenarios/vault-transit) is
|
|
|
|
also available if you do not have a Vault environment to perform the steps
|
|
|
|
described in this guide.
|
|
|
|
|
|
|
|
## Estimated Time to Complete
|
|
|
|
|
|
|
|
10 minutes
|
|
|
|
|
|
|
|
## Personas
|
|
|
|
|
|
|
|
The end-to-end scenario described in this guide involves two personas:
|
|
|
|
|
|
|
|
- **operator** with privileged permissions to manage the encryption keys
|
|
|
|
- **app** with un-privileged permissions encrypt/decrypt secrets via API
|
|
|
|
|
|
|
|
## Challenge
|
|
|
|
|
|
|
|
Think of the following scenario:
|
|
|
|
|
|
|
|
_Example Inc._ recently made headlines for a massive data breach which exposed
|
|
|
|
millions of their users' payment card accounts online. When they tracked down the
|
|
|
|
problem they found that a new HVAC system with management software had been put
|
|
|
|
into their data centers and had created vulnerabilities in their networks and
|
|
|
|
exposed ports and IPs to the databases publicly.
|
|
|
|
|
|
|
|
## Solutions
|
|
|
|
|
|
|
|
The `transit` secrets engine enables security teams to fortify data during
|
|
|
|
transit and at rest. So even if an intrusion occurs, your data is encrypted with
|
|
|
|
AES 256-bit CBC encryption (TLS in transit). Even if an attacker were able to
|
|
|
|
access the raw data, they would only have encrypted bits. This means attackers
|
|
|
|
would need to compromise multiple systems before exfiltrating data.
|
|
|
|
|
New Docs Website (#5535)
* conversion stage 1
* correct image paths
* add sidebar title to frontmatter
* docs/concepts and docs/internals
* configuration docs and multi-level nav corrections
* commands docs, index file corrections, small item nav correction
* secrets converted
* auth
* add enterprise and agent docs
* add extra dividers
* secret section, wip
* correct sidebar nav title in front matter for apu section, start working on api items
* auth and backend, a couple directory structure fixes
* remove old docs
* intro side nav converted
* reset sidebar styles, add hashi-global-styles
* basic styling for nav sidebar
* folder collapse functionality
* patch up border length on last list item
* wip restructure for content component
* taking middleman hacking to the extreme, but its working
* small css fix
* add new mega nav
* fix a small mistake from the rebase
* fix a content resolution issue with middleman
* title a couple missing docs pages
* update deps, remove temporary markup
* community page
* footer to layout, community page css adjustments
* wip downloads page
* deps updated, downloads page ready
* fix community page
* homepage progress
* add components, adjust spacing
* docs and api landing pages
* a bunch of fixes, add docs and api landing pages
* update deps, add deploy scripts
* add readme note
* update deploy command
* overview page, index title
* Update doc fields
Note this still requires the link fields to be populated -- this is solely related to copy on the description fields
* Update api_basic_categories.yml
Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages.
* Add bottom hero, adjust CSS, responsive friendly
* Add mega nav title
* homepage adjustments, asset boosts
* small fixes
* docs page styling fixes
* meganav title
* some category link corrections
* Update API categories page
updated to reflect the second level headings for api categories
* Update docs_detailed_categories.yml
Updated to represent the existing docs structure
* Update docs_detailed_categories.yml
* docs page data fix, extra operator page remove
* api data fix
* fix makefile
* update deps, add product subnav to docs and api landing pages
* Rearrange non-hands-on guides to _docs_
Since there is no place for these on learn.hashicorp, we'll put them
under _docs_.
* WIP Redirects for guides to docs
* content and component updates
* font weight hotfix, redirects
* fix guides and intro sidenavs
* fix some redirects
* small style tweaks
* Redirects to learn and internally to docs
* Remove redirect to `/vault`
* Remove `.html` from destination on redirects
* fix incorrect index redirect
* final touchups
* address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
|
|
|
![Encryption as a Service](/img/vault-encryption.png)
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
This guide demonstrates the basics of the `transit` secrets engine.
|
|
|
|
|
|
|
|
## Prerequisites
|
|
|
|
|
|
|
|
To perform the tasks described in this guide, you need to have a Vault
|
2020-01-18 00:18:09 +00:00
|
|
|
environment. Refer to the [Getting
|
2020-01-22 20:05:41 +00:00
|
|
|
Started](/intro/getting-started/install) guide to install Vault. Make sure
|
2018-07-27 23:08:52 +00:00
|
|
|
that your Vault server has been [initialized and
|
2020-01-22 20:05:41 +00:00
|
|
|
unsealed](/intro/getting-started/deploy).
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
### Policy requirements
|
|
|
|
|
|
|
|
-> **NOTE:** For the purpose of this guide, you can use **`root`** token to work
|
|
|
|
with Vault. However, it is recommended that root tokens are only used for just
|
|
|
|
enough initial setup or in emergencies. As a best practice, use tokens with
|
|
|
|
appropriate set of policies based on your role in the organization.
|
|
|
|
|
|
|
|
To perform all tasks demonstrated in this guide, your policy must include the
|
|
|
|
following permissions:
|
|
|
|
|
|
|
|
```shell
|
|
|
|
# Enable transit secrets engine
|
|
|
|
path "sys/mounts/transit" {
|
|
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
|
|
}
|
|
|
|
|
|
|
|
# To read enabled secrets engines
|
|
|
|
path "sys/mounts" {
|
|
|
|
capabilities = [ "read" ]
|
|
|
|
}
|
|
|
|
|
|
|
|
# Manage the transit secrets engine
|
|
|
|
path "transit/*" {
|
|
|
|
capabilities = [ "create", "read", "update", "delete", "list" ]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
If you are not familiar with policies, complete the
|
2020-01-22 20:05:41 +00:00
|
|
|
[policies](/guides/identity/policies) guide.
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
## Steps
|
|
|
|
|
|
|
|
You will perform the following:
|
|
|
|
|
|
|
|
1. [Configure Transit Secret Engine](#step1)
|
|
|
|
1. [Encrypt Secrets](#step2)
|
|
|
|
1. [Decrypt a cipher-text](#step3)
|
|
|
|
1. [Rotate the Encryption Key](#step4)
|
|
|
|
1. [Update Key Configuration](#step5)
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
### Step 1: Configure Transit Secret Engine ((#step1))
|
2020-01-18 00:18:09 +00:00
|
|
|
|
2018-07-27 23:08:52 +00:00
|
|
|
(**Persona:** operator)
|
|
|
|
|
|
|
|
The `transit` secrets engine must be configured before it can perform its
|
2020-01-18 00:18:09 +00:00
|
|
|
operations. This step is usually done by an **operator** or configuration
|
2018-07-27 23:08:52 +00:00
|
|
|
management tool.
|
|
|
|
|
|
|
|
#### CLI command
|
|
|
|
|
|
|
|
Enable the `transit` secret engine by executing the following command:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault secrets enable transit
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
> By default, the secrets engine will mount at the name of the engine. If you
|
|
|
|
> wish to enable it at a different path, use the `-path` argument.
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
> **Example:** `vault secrets enable -path=encryption transit`
|
|
|
|
|
|
|
|
Now, create an encryption key ring named, `orders` by executing the following
|
|
|
|
command:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write -f transit/keys/orders
|
|
|
|
```
|
|
|
|
|
|
|
|
#### API call using cURL
|
|
|
|
|
|
|
|
Enable `transit` secret engine using `/sys/mounts` endpoint:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: <TOKEN>" \
|
|
|
|
--request POST \
|
|
|
|
--data <PARAMETERS> \
|
|
|
|
<VAULT_ADDRESS>/v1/sys/mounts/<PATH>
|
|
|
|
```
|
|
|
|
|
|
|
|
Where `<TOKEN>` is your valid token, and `<PARAMETERS>` holds [configuration
|
2020-01-22 20:05:41 +00:00
|
|
|
parameters](/api/system/mounts#enable-secrets-engine) of the secret engine.
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
**Example:**
|
|
|
|
|
|
|
|
The following example enables transit secret engine at `sys/mounts/transit`
|
|
|
|
path, and passed the secret engine type (`transit`) in the request payload.
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
|
|
|
--data '{"type":"transit"}' \
|
|
|
|
https://127.0.0.1:8200/v1/sys/mounts/transit
|
|
|
|
```
|
|
|
|
|
|
|
|
Now, create an encryption key ring named, `orders` using the `transit/keys`
|
|
|
|
endpoint:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
2020-01-18 00:18:09 +00:00
|
|
|
https://127.0.0.1:8200/v1/transit/keys/orders
|
2018-07-27 23:08:52 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
#### Web UI
|
|
|
|
|
|
|
|
Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui) and then login.
|
|
|
|
|
|
|
|
1. Select **Enable new engine** and select **Transit** from **Secrets engine type**
|
2020-01-18 00:18:09 +00:00
|
|
|
drop-down list.
|
|
|
|
![Enable new engine](/img/vault-secrets-enable.png)
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
1. Click **Enable Engine**.
|
|
|
|
|
|
|
|
1. Select **Create encryption key** and enter `orders` in the **Name** field.
|
2020-01-18 00:18:09 +00:00
|
|
|
![Create a key](/img/vault-transit-1.png)
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
1. Click **Create encryption key** to complete.
|
|
|
|
|
|
|
|
~> **NOTE:** Typically, you want to create an encryption key ring for each
|
|
|
|
application.
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
### Step 2: Encrypt Secrets ((#step2))
|
2020-01-18 00:18:09 +00:00
|
|
|
|
2018-07-27 23:08:52 +00:00
|
|
|
(**Persona:** operator)
|
|
|
|
|
|
|
|
Once the `transit` secrets engine has been configured, any client with a valid
|
|
|
|
token with proper permission can send data to encrypt.
|
|
|
|
|
|
|
|
Here, you are going to encrypt a plaintext, _"credit-card-number"_.
|
|
|
|
|
|
|
|
-> **NOTE:** You can pass non-text binary file such as a PDF or image.
|
|
|
|
When you encrypt a plaintext, it must be base64-encoded.
|
|
|
|
|
|
|
|
#### CLI command
|
|
|
|
|
|
|
|
To encrypt your secret, use the `transit/encrypt` endpoint:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write transit/encrypt/<key_ring_name>
|
|
|
|
```
|
|
|
|
|
|
|
|
Execute the following command to encrypt a plaintext:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write transit/encrypt/orders plaintext=$(base64 <<< "credit-card-number")
|
|
|
|
|
|
|
|
Key Value
|
|
|
|
--- -----
|
|
|
|
ciphertext vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U=
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
Vault does _NOT_ store any of this data. The output you received is the
|
2018-07-27 23:08:52 +00:00
|
|
|
ciphertext. You can store this ciphertext at the desired location (e.g. MySQL
|
|
|
|
database) or pass it to another application.
|
|
|
|
|
|
|
|
#### API call using cURL
|
|
|
|
|
|
|
|
To encrypt your secret, use the [`transit/encrypt`
|
2020-01-22 20:05:41 +00:00
|
|
|
endpoint](/api/secret/transit#encrypt-data).
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
**Example:**
|
|
|
|
|
|
|
|
```shell
|
|
|
|
# Generate base64-encoded plaintext
|
|
|
|
$ base64 <<< "credit-card-number"
|
|
|
|
Y3JlZGl0LWNhcmQtbnVtYmVyCg==
|
|
|
|
|
|
|
|
# Pass the base64-encoded plaintext in the request payload
|
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
|
|
|
--data '{"plaintext": "Y3JlZGl0LWNhcmQtbnVtYmVyCg=="}' \
|
|
|
|
https://127.0.0.1:8200/v1/transit/encrypt/orders | jq
|
|
|
|
{
|
|
|
|
"request_id": "f483d9b6-8132-782e-1665-ad432c2461ab",
|
|
|
|
"lease_id": "",
|
|
|
|
"renewable": false,
|
|
|
|
"lease_duration": 0,
|
|
|
|
"data": {
|
|
|
|
"ciphertext": "vault:v1:/9hdQutaWpZR72s3+VSCLK1JNhV1wKM49hYVjh7RjmuxIy/OvshtgV4L4uVB+aQ="
|
|
|
|
},
|
|
|
|
...
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
Vault does _NOT_ store any of this data. The output you received is the
|
2018-07-27 23:08:52 +00:00
|
|
|
ciphertext. You can store this ciphertext at the desired location (e.g. MySQL
|
|
|
|
database) or pass it to another application.
|
|
|
|
|
|
|
|
#### Web UI
|
|
|
|
|
|
|
|
1. Select the **orders** encryption key.
|
|
|
|
|
|
|
|
1. Select **Key actions**.
|
2020-01-18 00:18:09 +00:00
|
|
|
![Key action](/img/vault-transit-2.png)
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
1. Make sure that **Encrypt** is selected under **TRANSIT ACTIONS**, and then
|
2020-01-18 00:18:09 +00:00
|
|
|
enter "credit-card-number" in the **Plaintext** field.
|
|
|
|
![Encrypt plaintext](/img/vault-transit-3.png)
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
1. Click **Encode to base64** to encode the plaintext.
|
|
|
|
|
|
|
|
1. Click **Encrypt**.
|
2020-01-18 00:18:09 +00:00
|
|
|
Vault does _NOT_ store any of this data. The output you received is the
|
|
|
|
ciphertext. You can click **Copy** to copy the resulting ciphertext and store it
|
|
|
|
at the desired location (e.g. MySQL database) or pass it to another application.
|
|
|
|
![Encrypt plaintext](/img/vault-transit-4.png)
|
2018-07-27 23:08:52 +00:00
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
### Step 3: Decrypt a cipher-text ((#step3))
|
2020-01-18 00:18:09 +00:00
|
|
|
|
2018-07-27 23:08:52 +00:00
|
|
|
(**Persona:** operator)
|
|
|
|
|
|
|
|
Any client with a valid token with proper permission can decrypt the ciphertext
|
|
|
|
generated by Vault. To decrypt the ciphertext, invoke the `transit/decrypt`
|
|
|
|
endpoint.
|
|
|
|
|
|
|
|
#### CLI command
|
|
|
|
|
|
|
|
Execute the following command to decrypt the ciphertext resulted in [Step
|
|
|
|
2](#step2):
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write transit/decrypt/orders \
|
|
|
|
ciphertext="vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U=" \
|
|
|
|
|
|
|
|
Key Value
|
|
|
|
--- -----
|
|
|
|
plaintext Y3JlZGl0LWNhcmQtbnVtYmVyCg==
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
The resulting data is base64-encoded. To reveal the original plaintext, run the
|
2018-07-27 23:08:52 +00:00
|
|
|
following command:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ base64 --decode <<< "Y3JlZGl0LWNhcmQtbnVtYmVyCg=="
|
|
|
|
credit-card-number
|
|
|
|
```
|
|
|
|
|
|
|
|
#### API call using cURL
|
|
|
|
|
|
|
|
Use the `transit/decrypt` endpoint to decrypt the ciphertext resulted in [Step
|
|
|
|
2](#step2):
|
|
|
|
|
|
|
|
**Example:**
|
|
|
|
|
|
|
|
```shell
|
|
|
|
# Pass the ciphertext in the request payload to decode
|
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
2019-08-01 14:41:52 +00:00
|
|
|
--data '{"ciphertext": "vault:v1:/9hdQutaWpZR72s3+VSCLK1JNhV1wKM49hYVjh7RjmuxIy/OvshtgV4L4uVB+aQ="}' \
|
2018-07-27 23:08:52 +00:00
|
|
|
https://127.0.0.1:8200/v1/transit/decrypt/orders | jq
|
|
|
|
{
|
|
|
|
"request_id": "062d7998-8932-76f2-f96c-5938a55ff005",
|
|
|
|
"lease_id": "",
|
|
|
|
"renewable": false,
|
|
|
|
"lease_duration": 0,
|
|
|
|
"data": {
|
|
|
|
"plaintext": "Y3JlZGl0LWNhcmQtbnVtYmVyCg=="
|
|
|
|
},
|
|
|
|
...
|
|
|
|
}
|
|
|
|
|
|
|
|
# The resulting data is base64-encoded that it must be decoded to reveal the plaintext
|
|
|
|
$ base64 --decode <<< "Y3JlZGl0LWNhcmQtbnVtYmVyCg=="
|
|
|
|
credit-card-number
|
|
|
|
```
|
|
|
|
|
|
|
|
#### Web UI
|
|
|
|
|
|
|
|
1. Select the **orders** encryption key.
|
|
|
|
|
|
|
|
1. Select **Key actions**.
|
|
|
|
|
|
|
|
1. Make sure that **Decrypt** is selected under **TRANSIT ACTIONS**, and then
|
2020-01-18 00:18:09 +00:00
|
|
|
enter the ciphertext you wish to decrypt.
|
|
|
|
![Decrypt ciphertext](/img/vault-transit-5.png)
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
1. Click **Decrypt**.
|
|
|
|
|
|
|
|
1. The resulting data is base64-encoded. Click **Decode from base64** to reveal
|
2020-01-18 00:18:09 +00:00
|
|
|
the plaintext.
|
2018-07-27 23:08:52 +00:00
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
### Step 4: Rotate the Encryption Key ((#step4))
|
2020-01-18 00:18:09 +00:00
|
|
|
|
2018-07-27 23:08:52 +00:00
|
|
|
(**Persona:** operator)
|
|
|
|
|
|
|
|
One of the benefits of using the Vault `transit` secrets engine is its ability
|
|
|
|
to easily rotate the encryption keys. Keys can be rotated manually by a human,
|
|
|
|
or an automated process which invokes the key rotation API endpoint through
|
|
|
|
cron, a CI pipeline, a periodic Nomad batch job, Kubernetes Job, etc.
|
|
|
|
|
|
|
|
Vault maintains the versioned keyring and the operator can decide the minimum
|
|
|
|
version allowed for decryption operations. When data is encrypted using Vault,
|
|
|
|
the resulting ciphertext is prepended with the version of the key used to
|
|
|
|
encrypt it.
|
|
|
|
|
|
|
|
#### CLI command
|
|
|
|
|
|
|
|
To rotate the encryption key, invoke the `transit/keys/<key_ring_name>/rotate`
|
|
|
|
endpoint.
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write -f transit/keys/orders/rotate
|
|
|
|
```
|
|
|
|
|
|
|
|
Let's encrypt another data:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write transit/encrypt/orders plaintext=$(base64 <<< "visa-card-number")
|
|
|
|
Key Value
|
|
|
|
--- -----
|
|
|
|
ciphertext vault:v2:45f9zW6cglbrzCjI0yCyC6DBYtSBSxnMgUn9B5aHcGEit71xefPEmmjMbrk3
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
Compare the ciphertexts from [Step 2](#step2).
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
ciphertext vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U=
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
Notice that the first ciphertext starts with "**`vault:v1:`**". After rotating
|
|
|
|
the encryption key, the ciphertext starts with "**`vault:v2:`**". This indicates
|
2018-07-27 23:08:52 +00:00
|
|
|
that the data gets encrypted using the latest version of the key after the
|
|
|
|
rotation.
|
|
|
|
|
2019-08-26 23:40:00 +00:00
|
|
|
Execute the following command to rewrap your ciphertext from [Step 2](#step2)
|
2018-07-27 23:08:52 +00:00
|
|
|
with the latest version of the encryption key:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write transit/rewrap/orders \
|
|
|
|
ciphertext="vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U="
|
|
|
|
Key Value
|
|
|
|
--- -----
|
|
|
|
ciphertext vault:v2:kChHZ9w4ILRfw+DzO53IZ8m5PyB2yp2/tKbub34uB+iDqtDRB+NLCPrpzTtJHJ4=
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
Notice that the resulting ciphertext now starts with "`vault:v2:`".
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
This operation does not reveal the plaintext data. But Vault will decrypt the
|
|
|
|
value using the appropriate key in the keyring and then encrypted the resulting
|
|
|
|
plaintext with the newest key in the keyring.
|
|
|
|
|
|
|
|
#### API call using cURL
|
|
|
|
|
|
|
|
To rotate the encryption key, invoke the `transit/keys/<key_ring_name>/rotate`
|
|
|
|
endpoint.
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST
|
|
|
|
https://127.0.0.1:8200/v1/transit/keys/orders/rotate
|
|
|
|
```
|
|
|
|
|
|
|
|
Let's encrypt another data:
|
|
|
|
|
|
|
|
```shell
|
|
|
|
# Generate base64-encoded plaintext
|
|
|
|
$ base64 <<< "visa-card-number"
|
|
|
|
dmlzYS1jYXJkLW51bWJlcgo=
|
|
|
|
|
|
|
|
# Pass the base64-encoded plaintext in the request payload
|
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
|
|
|
--data '{"plaintext": "dmlzYS1jYXJkLW51bWJlcgo="}' \
|
|
|
|
https://127.0.0.1:8200/v1/transit/encrypt/orders | jq
|
|
|
|
{
|
|
|
|
...
|
|
|
|
"data": {
|
|
|
|
"ciphertext": "vault:v2:et873RqkfLlS268LqYspVUnqhqZm0flNwhthe4ZzfcuZQab1TnirQ8/hMNYA"
|
|
|
|
},
|
|
|
|
...
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
Compare the ciphertexts from [Step 2](#step2).
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
ciphertext vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U=
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
Notice that the first ciphertext starts with "**`vault:v1:`**". After rotating
|
|
|
|
the encryption key, the ciphertext starts with "**`vault:v2:`**". This indicates
|
2018-07-27 23:08:52 +00:00
|
|
|
that the data gets encrypted using the latest version of the key after the
|
|
|
|
rotation.
|
|
|
|
|
2019-08-26 23:40:00 +00:00
|
|
|
Execute the `transit/rewrap` endpoint to rewrap your ciphertext from [Step 2](#step2)
|
2018-07-27 23:08:52 +00:00
|
|
|
with the latest version of the encryption key:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST \
|
|
|
|
--data '{"ciphertext": "vault:v1:/9hdQutaWpZR72s3+VSCLK1JNhV1wKM49hYVjh7RjmuxIy/OvshtgV4L4uVB+aQ="}' \
|
|
|
|
https://127.0.0.1:8200/v1/transit/rewrap/orders | jq
|
|
|
|
{
|
|
|
|
...
|
|
|
|
"data": {
|
|
|
|
"ciphertext": "vault:v2:ykqXDP65tLVSrqxoNZh51gIobYQSwNGT+SbiD/2nl8rrhF2md+wplBGdXlhDzd4="
|
|
|
|
},
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
2020-01-18 00:18:09 +00:00
|
|
|
Notice that the resulting ciphertext now starts with "`vault:v2:`".
|
2018-07-27 23:08:52 +00:00
|
|
|
|
|
|
|
This operation does not reveal the plaintext data. But Vault will decrypt the
|
|
|
|
value using the appropriate key in the keyring and then encrypted the resulting
|
|
|
|
plaintext with the newest key in the keyring.
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
## Step 5: Update Key Configuration ((#step5))
|
2020-01-18 00:18:09 +00:00
|
|
|
|
2018-07-27 23:08:52 +00:00
|
|
|
(**Persona:** operator)
|
|
|
|
|
|
|
|
The operators can [update the encryption key
|
2020-01-22 20:05:41 +00:00
|
|
|
configuration](/api/secret/transit#update-key-configuration) to
|
2018-07-27 23:08:52 +00:00
|
|
|
specify the minimum version of ciphertext allowed to be decrypted, the minimum
|
|
|
|
version of the key that can be used to encrypt the plaintext, the key is allowed
|
|
|
|
to be deleted, etc.
|
|
|
|
|
|
|
|
This helps further tightening the data encryption rule.
|
|
|
|
|
|
|
|
#### CLI Command
|
|
|
|
|
|
|
|
Execute the key rotation command a few times to generate multiple versions of
|
|
|
|
the key:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write -f transit/keys/orders/rotate
|
|
|
|
```
|
|
|
|
|
|
|
|
Now, read the `orders` key information:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault read transit/keys/orders
|
|
|
|
|
|
|
|
Key Value
|
|
|
|
--- -----
|
|
|
|
...
|
|
|
|
keys map[6:1531439714 1:1531439594 2:1531439667 3:1531439714 4:1531439714 5:1531439714]
|
|
|
|
latest_version 6
|
|
|
|
min_decryption_version 1
|
|
|
|
min_encryption_version 0
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
|
|
|
In the example, the current version of the key is **6**. However, there is no
|
|
|
|
restriction about the minimum encryption key version, and any of the key
|
|
|
|
versions can decrypt the data (`min_decryption_version`).
|
|
|
|
|
|
|
|
Run the following command to enforce the use of the encryption key at version
|
|
|
|
**5** or later to decrypt the data.
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault write transit/keys/orders/config min_decryption_version=5
|
|
|
|
```
|
|
|
|
|
|
|
|
Now, verify the `orders` key configuration:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ vault read transit/keys/orders
|
|
|
|
|
|
|
|
Key Value
|
|
|
|
--- -----
|
|
|
|
allow_plaintext_backup false
|
|
|
|
deletion_allowed false
|
|
|
|
derived false
|
|
|
|
exportable false
|
|
|
|
keys map[5:1531811719 6:1531811721]
|
|
|
|
latest_version 6
|
|
|
|
min_decryption_version 5
|
|
|
|
min_encryption_version 0
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
|
|
|
#### API call using cURL
|
|
|
|
|
|
|
|
Execute the `transit/keys/<key_ring_name>/rotate` endpoint a few times key
|
|
|
|
rotation command a few times to generate multiple versions of the key:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST
|
|
|
|
https://127.0.0.1:8200/v1/transit/keys/orders/rotate
|
|
|
|
```
|
|
|
|
|
|
|
|
Read the `transit/keys/orders` endpoint to review the `orders` key
|
|
|
|
detail:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
https://127.0.0.1:8200/v1/transit/keys/orders | jq
|
|
|
|
{
|
|
|
|
...
|
|
|
|
"keys": {
|
|
|
|
"1": 1531804669,
|
|
|
|
"2": 1531810236,
|
|
|
|
"3": 1531811712,
|
|
|
|
"4": 1531811715,
|
|
|
|
"5": 1531811719,
|
|
|
|
"6": 1531811721
|
|
|
|
},
|
|
|
|
"latest_version": 6,
|
|
|
|
"min_decryption_version": 1,
|
|
|
|
"min_encryption_version": 0,
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
|
|
|
In the example, the current version of the key is **6**. However, there is no
|
|
|
|
restriction about the minimum encryption key version, and any of the key
|
|
|
|
versions can decrypt the data (`min_decryption_version`).
|
|
|
|
|
|
|
|
Run the following command to enforce the use of the encryption key at version
|
|
|
|
**5** or later to decrypt the data.
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
--request POST
|
|
|
|
--data '{"min_decryption_version": 5}'
|
|
|
|
https://127.0.0.1:8200/v1/transit/keys/orders/config
|
|
|
|
```
|
|
|
|
|
|
|
|
Now, verify the `orders` key configuration:
|
|
|
|
|
2020-05-21 17:18:17 +00:00
|
|
|
```shell-session
|
2018-07-27 23:08:52 +00:00
|
|
|
$ curl --header "X-Vault-Token: ..." \
|
|
|
|
https://127.0.0.1:8200/v1/transit/keys/orders | jq
|
|
|
|
{
|
|
|
|
...
|
|
|
|
"keys": {
|
|
|
|
"5": 1531811719,
|
|
|
|
"6": 1531811721
|
|
|
|
},
|
|
|
|
"latest_version": 6,
|
|
|
|
"min_decryption_version": 5,
|
|
|
|
"min_encryption_version": 0,
|
|
|
|
...
|
|
|
|
```
|
|
|
|
|
|
|
|
-> **NOTE:** Notice that the output only displays two valid encryption key
|
|
|
|
versions (`5` and `6`).
|
|
|
|
|
|
|
|
## Next steps
|
|
|
|
|
2020-01-22 20:05:41 +00:00
|
|
|
[Transit Secrets Re-wrapping](/guides/encryption/transit-rewrap) guide
|
2018-07-27 23:08:52 +00:00
|
|
|
introduces a sample application which re-wraps data after rotating an encryption
|
|
|
|
key in the transit engine in Vault.
|