Encryption as a Service: Transit Secrets Engine

33min
Vault
Video
Interactive

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 can also be viewed as encryption as a service.

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 admins of Vault.

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-GCM with a 256-bit AES key or other supported key types. 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.

This tutorial demonstrates the basics of the transit secrets engine.

Launch Terminal

This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.

Personas

The end-to-end scenario described in this tutorial involves two personas:

admin with privileged permissions to manage the encryption keys
apps with un-privileged permissions encrypt/decrypt secrets via APIs

Prerequisites

To perform the tasks described in this tutorial, you need to have a Vault environment. Refer to the Getting Started tutorial to install Vault.

Policy requirements

Note

For the purpose of this tutorial, 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 tutorial, your policy must include the following permissions.

# 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 policies tutorial.

Lab setup

Open a terminal and start a Vault dev server with root as the root token.

$ vault server -dev -dev-root-token-id root

The Vault dev server defaults to running at 127.0.0.1:8200. The server is also initialized and unsealed.

Insecure operation

Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.

Export an environment variable for the vault CLI to address the Vault server.

$ export VAULT_ADDR=$VAULT_ADDR

Export an environment variable for the vault CLI to authenticate with the Vault server.

$ export VAULT_TOKEN=root

The Vault server is ready.

Note

If you do not have access to an HCP Vault cluster, visit the Create a Vault Cluster on HCP tutorial.

Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the VAULT_ADDR environment variable to the copied address.
```
$ export VAULT_ADDR=<Public_Cluster_URL>
```
Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.

Type vault status to verify your connectivity to the Vault cluster.

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.9.2+ent
Storage Type             raft
...snipped...

The HCP Vault server is ready.

Configure Transit secrets engine

(Persona: admin)

The transit secrets engine must be configured before it can perform its operations. This step is usually done by an admin or configuration management tool.

Enable the transit secrets engine by executing the following command.
```
$ vault secrets enable transit
```
NOTE: 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.
Example: The following command enables the transit secrets engine at encryption/ instead of transit/.
```
$ vault secrets enable -path=encryption transit
```
Create an encryption key ring named orders by executing the following command.
```
$ vault write -f transit/keys/orders
```

Enable transit secrets engine using the /sys/mounts endpoint at sys/mounts/transit path, and passed the secrets engine type (transit) in the request payload.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"type":"transit"}' \
    $VAULT_ADDR/v1/sys/mounts/transit

Create an encryption key ring named orders using the transit/keys endpoint.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    $VAULT_ADDR/v1/transit/keys/orders

Enable transit secrets engine using the /sys/mounts endpoint at sys/mounts/transit path, and passed the secrets engine type (transit) in the request payload.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data '{"type":"transit"}' \
    $VAULT_ADDR/v1/sys/mounts/transit

Create an encryption key ring named orders using the transit/keys endpoint.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    $VAULT_ADDR/v1/transit/keys/orders

Create a token for Vault clients

(Persona: admin)

Vault clients must authenticate with Vault and acquire a valid token with appropriate policies allowing to request data encryption and decryption using the specific key.

When the transit secrets engine is enabled at transit, the policy must include the following.

path "transit/encrypt/<key_name>" {
   capabilities = [ "update" ]
}

path "transit/decrypt/<key_name>" {
   capabilities = [ "update" ]
}

This tutorial uses the vault token create command to generate a client token and skips the authentication step.

In practice, you can leverage the Vault Agent Auto-Auth method to authenticate with Vault and manage the lifecycle of the client token. To learn more about Vault Agent, visit the App Integration in Learn.

Create a policy named app-orders.

$ vault policy write app-orders -<<EOF
path "transit/encrypt/orders" {
   capabilities = [ "update" ]
}
path "transit/decrypt/orders" {
   capabilities = [ "update" ]
}
EOF

The policy is created or updated; if it already exists.

Create a token with app-orders policy attached.

$ vault token create -policy=app-orders

Example output:

Key                  Value
---                  -----
token                hvs.CAESIOVYYt5Cq5E0zZX3QVHEv5EYj94pGkGipUX48rI_f2wFGh4KHGh2cy5kdlhPSEhyR2pLa0hlODQwRDVkMzVuMWE
token_accessor       juBC32Z7lRpqoAvxO9turjIh
token_duration       768h
token_renewable      true
token_policies       ["app-orders" "default"]
identity_policies    []
policies             ["app-orders" "default"]

Create a APP_ORDER_TOKEN environment variable to store the generated client token value.

Example:

$ export APP_ORDER_TOKEN="hvs.CAESIOVYYt5Cq5E0zZX3QVHEv5EYj94pGkGipUX48rI_f2wFGh4KHGh2cy5kdlhPSEhyR2pLa0hlODQwRDVkMzVuMWE"

Create a request payload containing the stringified app-orders policy.

$ tee payload.json <<EOF
{
  "policy": "path \"transit/encrypt/orders\" {\n   capabilities = [ \"update\" ]\n}\n\npath \"transit/decrypt/orders\" {\n   capabilities = [ \"update\" ]\n}\n"
}
EOF

Create a policy named app-orders

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request PUT \
    --data @payload.json \
    $VAULT_ADDR/v1/sys/policies/acl/app-orders

The policy is created or updated; if it already exists.

Create a token with app-orders policy attached.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST  \
    --data '{ "policies": ["app-orders"] }' \
    $VAULT_ADDR/v1/auth/token/create | jq -r ".auth"

Example output:

{
  "client_token": "s.zQcCmAJnp2C5fzRybpeyw0sB",
  "accessor": "obBZm43hqwhZySMA1uJ2gl8M",
  "policies": [
    "app-orders",
    "default"
  ],
  "token_policies": [
    "app-orders",
    "default"
  ],
  "metadata": null,
  "lease_duration": 2764800,
  "renewable": true,
  "entity_id": "",
  "token_type": "service",
  "orphan": false
}

Create a APP_ORDER_TOKEN environment variable to store the generated client token value.
Example:
```
$ export APP_ORDER_TOKEN="s.zQcCmAJnp2C5fzRybpeyw0sB"
```

Create a request payload containing the stringified app-orders policy.

$ tee payload.json <<EOF
{
  "policy": "path \"transit/encrypt/orders\" {\n   capabilities = [ \"update\" ]\n}\n\npath \"transit/decrypt/orders\" {\n   capabilities = [ \"update\" ]\n}\n"
}
EOF

Create a policy named app-orders

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request PUT \
    --data @payload.json \
    $VAULT_ADDR/v1/sys/policies/acl/app-orders

The policy is created or updated; if it already exists.

Create a token with app-orders policy attached.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST  \
    --data '{ "policies": ["app-orders"] }' \
    $VAULT_ADDR/v1/auth/token/create | jq -r ".auth"

Example output:

{
  "client_token": "s.U4I87snzLMNOPybPIpyozdHC.QttaO",
  "accessor": "83rbmrkUzBGDzFKnanHIJKk.QttaO",
  "policies": [
    "app-orders",
    "default"
  ],
  "token_policies": [
    "app-orders",
    "default"
  ],
  "metadata": null,
  "lease_duration": 3600,
  "renewable": true,
  "entity_id": "9bbc2475-1488-7725-6a67-9a6e3bbdfeee",
  "token_type": "service",
  "orphan": false
}

Create a APP_ORDER_TOKEN environment variable to store the generated client token value.
Example:
```
$ export APP_ORDER_TOKEN="s.U4I87snzLMNOPybPIpyozdHC.QttaO"
```

Click the Policies tab, and then select Create ACL policy.
Enter app-orders in the Name field.

Copy and past in the following in the Policy text field.

path "transit/encrypt/orders" {
   capabilities = [ "update" ]
}

path "transit/decrypt/orders" {
   capabilities = [ "update" ]
}

# List existing keys in UI
path "transit/keys" {
   capabilities = [ "list" ]
}

# Enable to select the orders key in UI
path "transit/keys/orders" {
   capabilities = [ "read" ]
}

Click Create policy.
Click the Vault CLI shell icon (>_) to open a command shell. Execute vault write auth/token/create policies=app-orders in the CLI shell.

Copy the generated token value (e.g. s.U4I87snzLMNOPybPIpyozdHC.QttaO). You are going to use it to request data encryption and decryption.

Encrypt secrets

(Persona: apps)

Once the transit secrets engine has been configured, any Vault client holding a valid token with the proper permissions can send data to encrypt.

Here, you are going to encrypt a plaintext credit card number (4111 1111 1111 1111).

Note

Vault can encrypt a binary file such as an image. When you send data to Vault for encryption, it must be in the form of base64-encoded plaintext for a safe transport.

Encrypt plaintext (using the shell to do the base64 encoding) using the orders encryption key. Be sure to replace <client_token> with the token value you copied in the previous step.

$ VAULT_TOKEN=$APP_ORDER_TOKEN vault write transit/encrypt/orders \
    plaintext=$(base64 <<< "4111 1111 1111 1111")

Example output:

Key           Value
---           -----
ciphertext    vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U=

To encrypt your secret, use the transit/encrypt endpoint.

Use base64 encoding to encode your secret.

$ base64 <<< "4111 1111 1111 1111"
NDExMSAxMTExIDExMTEgMTExMQo=

Pass the base64-encoded plaintext in the request payload. Be sure to replace <client_token> with the token value you copied in the previous step.

$ curl --header "X-Vault-Token: $APP_ORDER_TOKEN" \
    --request POST \
    --data '{"plaintext": "NDExMSAxMTExIDExMTEgMTExMQo="}' \
    $VAULT_ADDR/v1/transit/encrypt/orders | jq -r ".data"

It will return a JSON string similar to this.

{
  "ciphertext": "vault:v1:icoWIWuJ1Oa/Hdgbbmcsvn9Gz035zQtYy1uVu2aPZlqjfSML5bbuVTt4LmnRbMlr",
  "key_version": 1
}

To encrypt your secret, use the transit/encrypt endpoint.

Use base64 encoding to encode your secret.

$ base64 <<< "4111 1111 1111 1111"
NDExMSAxMTExIDExMTEgMTExMQo=

Pass the base64-encoded plaintext in the request payload. Be sure to replace <client_token> with the token value you copied in the previous step.

$ curl --header "X-Vault-Token: $APP_ORDER_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data '{"plaintext": "NDExMSAxMTExIDExMTEgMTExMQo="}' \
    $VAULT_ADDR/v1/transit/encrypt/orders | jq -r ".data"

It will return a JSON string similar to this.

{
  "ciphertext": "vault:v1:icoWIWuJ1Oa/Hdgbbmcsvn9Gz035zQtYy1uVu2aPZlqjfSML5bbuVTt4LmnRbMlr",
  "key_version": 1
}

Sign out of the UI.
In the Token text field, enter the <client_token> value you copied in the previous step.
Click Sign in.
Under Secrets Engines, select transit/.
In the Key Actions tab, select Encrypt.
Enter 4111 1111 1111 1111 in the Plaintext field.
Click Encrypt.
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.

Notice that the ciphertext starts with vault:v1:. This prefix indicates that this value is wrapped by vault and the version of the orders encryption key used was v1. Therefore, when you decrypt this ciphertext, Vault knows to use v1 of the key. Later, you are going to rotate the encryption key and learn how to re-wrap the ciphertext with the latest version of the encryption key.

Warning

Vault does NOT store any data encrypted via the transit/encrypt endpoint. The output you received is the ciphertext. You can store this ciphertext at the desired location (e.g. MySQL database) or pass it to another application.

Decrypt ciphertext

(Persona: apps)

Any client holding a valid token with proper permissions can decrypt ciphertext generated by Vault. To decrypt the ciphertext, invoke the transit/decrypt endpoint.

Execute the following command to decrypt the ciphertext emitted in the encrypt secrets step. Be sure to set the <ciphertext> value to the value returned in the previous step.

$ VAULT_TOKEN=$APP_ORDER_TOKEN vault write transit/decrypt/orders ciphertext=<ciphertext>

Example:

$ VAULT_TOKEN=$APP_ORDER_TOKEN vault write transit/decrypt/orders \
    ciphertext="vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U="

Key          Value
---          -----
plaintext    NDExMSAxMTExIDExMTEgMTExMQo=

Use the transit/decrypt endpoint to decrypt the ciphertext emitted in the encrypt secrets step.

Execute the following command to decrypt the ciphertext emitted in the encrypt secrets step. Be sure to set the <ciphertext> value to the value returned in the previous step.

$ curl --header "X-Vault-Token: $APP_ORDER_TOKEN" \
   --request POST \
   --data '{"ciphertext": "<ciphertext>"}' \
   $VAULT_ADDR/v1/transit/decrypt/orders | jq -r ".data"

Example:

$ curl --header "X-Vault-Token: $APP_ORDER_TOKEN" \
   --request POST \
   --data '{"ciphertext": "vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U="}' \
   $VAULT_ADDR/v1/transit/decrypt/orders | jq -r ".data"

{
  "plaintext": "NDExMSAxMTExIDExMTEgMTExMQo="
}

Use the transit/decrypt endpoint to decrypt the ciphertext emitted in the encrypt secrets step.

Execute the following command to decrypt the ciphertext emitted in the encrypt secrets step. Be sure to set the <ciphertext> value to the value returned in the previous step.

$ curl --header "X-Vault-Token: $APP_ORDER_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"ciphertext": "<ciphertext>"}' \
   $VAULT_ADDR/v1/transit/decrypt/orders | jq -r ".data"

Example:

$ curl --header "X-Vault-Token: $APP_ORDER_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"ciphertext": "vault:v1:/9hdQutaWpZR72s3+VSCLK1JNhV1wKM49hYVjh7R...snip..."}' \
   $VAULT_ADDR/v1/transit/decrypt/orders | jq -r ".data"

{
  "plaintext": "NDExMSAxMTExIDExMTEgMTExMQo="
}

The resulting data is base64-encoded and must be decoded to reveal the plaintext.

$ base64 --decode <<< "NDExMSAxMTExIDExMTEgMTExMQo="
4111 1111 1111 1111

Rotate the encryption key

(Persona: admin)

One of the benefits of using the Vault transit secrets engine is its ability to easily rotate encryption keys. Keys can be rotated manually by a human or by 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 admin can decide the minimum version allowed for decryption operations. When data is encrypted using Vault, the resulting ciphertext is prepended by the version of the key used to encrypt it.

To rotate the encryption key, invoke the transit/keys/<key_ring_name>/rotate endpoint. In this tutorial, the key ring name is orders.
```
$ vault write -f transit/keys/orders/rotate
```
Encrypt another data.
```
$ vault write transit/encrypt/orders plaintext=$(base64 <<< "4111 1111 1111 1111")

Key           Value
---           -----
ciphertext    vault:v2:45f9zW6cglbrzCjI0yCyC6DBYtSBSxnMgUn9B5aHcGEit71xefPEmmjMbrk3
```
Compare the ciphertexts from the encrypt secrets step as generated on your machine.
```
ciphertext    vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U=
```
Notice that the first ciphertext starts with "vault:v1:". After rotating the encryption key, the ciphertext starts with "vault:v2:". This indicates that the data is encrypted using the latest version of the key after the rotation.
Rewrap your ciphertext from the encrypt secrets step with the latest version of the encryption key.
```
$ vault write transit/rewrap/orders \
    ciphertext="vault:v1:cZNHVx+sxdMErXRSuDa1q/pz49fXTn1PScKfhf+PIZPvy8xKfkytpwKcbC0fF2U="
```
Example output:
```
Key           Value
---           -----
ciphertext    vault:v2:kChHZ9w4ILRfw+DzO53IZ8m5PyB2yp2/tKbub34uB+iDqtDRB+NLCPrpzTtJHJ4=
```
Notice that the resulting ciphertext now starts with "vault:v2:".
This operation does not reveal the plaintext data. But Vault will decrypt the value using the appropriate key in the keyring and then encrypt the resulting plaintext with the newest key in the keyring.

To rotate the encryption key, invoke the transit/keys/<key_ring_name>/rotate endpoint. In this tutorial, the key ring name is orders.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --request POST \
     $VAULT_ADDR/v1/transit/keys/orders/rotate

Encrypt another piece of data.
First, generate base64-encoded plaintext.
```
$ base64 <<< "4111 1111 1111 1111"
NDExMSAxMTExIDExMTEgMTExMQo=
```
Pass the base64-encoded plaintext in the request payload.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --request POST \
     --data '{"plaintext": "NDExMSAxMTExIDExMTEgMTExMQo="}' \
     $VAULT_ADDR/v1/transit/encrypt/orders | jq -r ".data"
```
Example output:
```
{
  "ciphertext": "vault:v2:+Hsmlr7Da4lcTo1H+e7TCMkAWy/bHqU89wOj4nTP+BBp2XW7rTgpyuFt025JW7L4",
  "key_version": 2
}
```
Compare the ciphertexts from the encrypt secrets step as generated on your machine (e.g. vault:v1:/9hdQutaWpZR72s3+VSCLK1JNhV1wKM49hYVjh7RjmuxIy/OvshtgV4L4uVB+aQ=).
Notice that the first ciphertext starts with "vault:v1:". After rotating the encryption key, the ciphertext starts with "vault:v2:". This indicates that the data is encrypted using the latest version of the key after the rotation.
Rewrap your ciphertext from the encrypt secrets step with the latest version of the encryption key.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --request POST \
   --data '{"ciphertext": "vault:v1:/9hdQutaWpZR72s3+VSCLK1JNhV1wKM49hYVjh7RjmuxIy/OvshtgV4L4uVB+aQ="}' \
   $VAULT_ADDR/v1/transit/rewrap/orders | jq -r ".data"
```
Example output:
```
{
  "ciphertext": "vault:v2:zZySQDuy+CSHOH4wbPKGHRm5J+jTMajyoD3DFReP41K3qQBl0kStboCb966T9U2t",
  "key_version": 2
}
```
Notice that the resulting ciphertext now starts with "vault:v2:".
This operation does not reveal the plaintext data. But Vault will decrypt the value using the appropriate key in the keyring and then encrypt the resulting plaintext with the newest key in the keyring.

To rotate the encryption key, invoke the transit/keys/<key_ring_name>/rotate endpoint. In this tutorial, the key ring name is orders.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     $VAULT_ADDR/v1/transit/keys/orders/rotate

Encrypt another piece of data.
First, generate base64-encoded plaintext.
```
$ base64 <<< "4111 1111 1111 1111"
NDExMSAxMTExIDExMTEgMTExMQo=
```
Pass the base64-encoded plaintext in the request payload.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
     --request POST \
     --data '{"plaintext": "NDExMSAxMTExIDExMTEgMTExMQo="}' \
     $VAULT_ADDR/v1/transit/encrypt/orders | jq -r ".data"
```
Example output:
```
{
  "ciphertext": "vault:v2:+Hsmlr7Da4lcTo1H+e7TCMkAWy/bHqU89wOj4nTP+BBp2XW7rTgpyuFt025JW7L4",
  "key_version": 2
}
```
Compare the ciphertexts from the encrypt secrets step as generated on your machine (e.g. vault:v1:/9hdQutaWpZR72s3+VSCLK1JNhV1wKM49hYVjh7RjmuxIy/OvshtgV4L4uVB+aQ=).
Notice that the first ciphertext starts with "vault:v1:". After rotating the encryption key, the ciphertext starts with "vault:v2:". This indicates that the data is encrypted using the latest version of the key after the rotation.

Rewrap your ciphertext from the encrypt secrets step with the latest version of the encryption key.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"ciphertext": "vault:v1:/9hdQutaWpZR72s3+VSCLK1JNhV1wKM49hYVjh7RjmuxIy/OvshtgV4L4uVB+aQ="}' \
   $VAULT_ADDR/v1/transit/rewrap/orders | jq -r ".data"

Example output:

{
  "ciphertext": "vault:v2:zZySQDuy+CSHOH4wbPKGHRm5J+jTMajyoD3DFReP41K3qQBl0kStboCb966T9U2t",
  "key_version": 2
}

Notice that the resulting ciphertext now starts with "vault:v2:".

This operation does not reveal the plaintext data. But Vault will decrypt the value using the appropriate key in the keyring and then encrypt the resulting plaintext with the newest key in the keyring.

Select the orders encryption key.
Select the Versions tab, and then select Rotate encryption key to rotate the encryption key.
Select Rotate at the confirmation dialog to proceed.
Select Key actions.
Select Encrypt. Notice that it gives you an option to select the desired key version to encrypt your secret with.
With 2 (latest) selected as key version, enter "5111 1111 1111 1111" in the Plaintext field.
Click Encrypt. Notice that the first ciphertext started with "vault:v1:". After rotating the encryption key, the ciphertext starts with "vault:v2:". This indicates that the data is encrypted using the latest version of the key after the rotation.

Vault will decrypt the value using the appropriate key in the keyring and then encrypt the resulting plaintext with the newest key in the keyring.

Automatic key rotation

Vault version

This feature requires Vault 1.10 or later.

Instead of rotating the key manually, you can configure Vault to automatically rotate the encryption key at a user-defined time interval.

Read the orders key information.

$ vault read transit/keys/orders

Output:

Key                       Value
---                       -----
allow_plaintext_backup    false
auto_rotate_period        0s
deletion_allowed          false
derived                   false
exportable                false
keys                      map[1:1647405195]
latest_version            1
...snip...

The auto_rotate_period parameter configures the amount of time the key should live before being automatically rotated. A value of 0 (default) disables automatic rotation for the key.

Configure to automatically rotate the orders key every 24 hours.

$ vault write transit/keys/orders/config auto_rotate_period=24h
Success! Data written to: transit/keys/orders/config

Read the orders key information again.

$ vault read transit/keys/orders

Output:

Key                       Value
---                       -----
allow_plaintext_backup    false
auto_rotate_period        24h
deletion_allowed          false
derived                   false
exportable                false
keys                      map[1:1647405195]
latest_version            1
...snip...

Read the transit/keys/orders endpoint to review the orders key details and retrieve its auto_rotate_period parameter value.
```
$ curl --header "X-Vault-Token: $VAULT_TOKEN" --silent \
    $VAULT_ADDR/v1/transit/keys/orders | jq -r ".data.auto_rotate_period"
```
Output:
```
0
```
The auto_rotate_period parameter configures the amount of time the key should live before being automatically rotated. A value of 0 (default) disables automatic rotation for the key.

Configure to automatically rotate the orders key every 24 hours (86400 seconds).

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"auto_rotate_period": 86400}' \
    $VAULT_ADDR/v1/transit/keys/orders/config

Verify the orders key configuration.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    $VAULT_ADDR/v1/transit/keys/orders | jq -r ".data"

Output:

{
  "allow_plaintext_backup": false,
  "auto_rotate_period": 86400,
  "deletion_allowed": false,
  "derived": false,
  "exportable": false,
  "keys": {
    "1": 1647405195
  },
  ...snip...
}

Vault will automatically rotate the orders key every 24 hours.

Update key configuration

(Persona: admin)

Vault admin can update the encryption key configuration to 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 to further tighten the data encryption rule.

Execute the key rotation command a few times to generate multiple versions of the key.
```
$ vault write -f transit/keys/orders/rotate
```

Read the orders key information.

$ vault read transit/keys/orders

Example output:

Key                       Value
---                       -----
allow_plaintext_backup    false
deletion_allowed          false
derived                   false
exportable                false
keys                      map[1:1639541621 2:1639543423 3:1639543860 4:1639543863 5:1639543866 6:1639543868]
latest_version            6
min_available_version     0
min_decryption_version    1
min_encryption_version    0
name                      orders
supports_decryption       true
supports_derivation       true
supports_encryption       true
supports_signing          false
type                      aes256-gcm96

In this 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).

Enforce the use of the encryption key at version 5 or later to decrypt the data.
```
$ vault write transit/keys/orders/config min_decryption_version=5
```

Verify the orders key configuration.

$ vault read transit/keys/orders

Key                       Value
---                       -----
allow_plaintext_backup    false
auto_rotate_period        24h
deletion_allowed          false
derived                   false
exportable                false
keys                      map[5:1647409105 6:1647409106]
latest_version            6
min_available_version     0
min_decryption_version    5
min_encryption_version    0
name                      orders
supports_decryption       true
supports_derivation       true
supports_encryption       true
supports_signing          false
type                      aes256-gcm96

Execute the transit/keys/<key_ring_name>/rotate endpoint four times to generate multiple versions of the key.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    $VAULT_ADDR/v1/transit/keys/orders/rotate

Read the transit/keys/orders endpoint to review the orders key details.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    $VAULT_ADDR/v1/transit/keys/orders | jq -r ".data"

Example output:

{
  "allow_plaintext_backup": false,
  "auto_rotate_period": 86400,
  "deletion_allowed": false,
  "derived": false,
  "exportable": false,
  "keys": {
    "1": 1647405195,
    "2": 1647409101,
    "3": 1647409102,
    "4": 1647409104,
    "5": 1647409105,
    "6": 1647409106
  },
  "latest_version": 6,
  "min_available_version": 0,
  "min_decryption_version": 1,
  "min_encryption_version": 0,
  "name": "orders",
  "supports_decryption": true,
  "supports_derivation": true,
  "supports_encryption": true,
  "supports_signing": false,
  "type": "aes256-gcm96"
}

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).

Enforce the use of the encryption key at version 5 or later to decrypt the data.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data '{"min_decryption_version": 5}' \
    $VAULT_ADDR/v1/transit/keys/orders/config

Verify the orders key configuration.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    $VAULT_ADDR/v1/transit/keys/orders | jq -r ".data"

Example output:

{
  "allow_plaintext_backup": false,
  "auto_rotate_period": 86400,
  "deletion_allowed": false,
  "derived": false,
  "exportable": false,
  "keys": {
    "5": 1647409105,
    "6": 1647409106
  },
  "latest_version": 6,
  "min_available_version": 0,
  "min_decryption_version": 5,
  "min_encryption_version": 0,
  "name": "orders",
  "supports_decryption": true,
  "supports_derivation": true,
  "supports_encryption": true,
  "supports_signing": false,
  "type": "aes256-gcm96"
}

Note

The output only displays two valid encryption key versions (5 and -6).

Execute the transit/keys/<key_ring_name>/rotate endpoint four times to generate multiple versions of the key.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    $VAULT_ADDR/v1/transit/keys/orders/rotate

Read the transit/keys/orders endpoint to review the orders key details.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    $VAULT_ADDR/v1/transit/keys/orders | jq -r ".data"

Example output:

{
  "allow_plaintext_backup": false,
  "deletion_allowed": false,
  "derived": false,
  "exportable": false,
  "keys": {
    "1": 1639541621,
    "2": 1639543423,
    "3": 1639543860,
    "4": 1639543863,
    "5": 1639543866,
    "6": 1639543868
  },
  "latest_version": 6,
  "min_available_version": 0,
  "min_decryption_version": 1,
  "min_encryption_version": 0,
  "name": "orders",
  "supports_decryption": true,
  "supports_derivation": true,
  "supports_encryption": true,
  "supports_signing": false,
  "type": "aes256-gcm96"
}

Enforce the use of the encryption key at version 5 or later to decrypt the data.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    --data '{"min_decryption_version": 5}' \
    $VAULT_ADDR/v1/transit/keys/orders/config

Verify the orders key configuration.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    $VAULT_ADDR/v1/transit/keys/orders | jq -r ".data"

Example output:

{
  "allow_plaintext_backup": false,
  "deletion_allowed": false,
  "derived": false,
  "exportable": false,
  "keys": {
    "5": 1639543866,
    "6": 1639543868
  },
  "latest_version": 6,
  "min_available_version": 0,
  "min_decryption_version": 5,
  "min_encryption_version": 0,
  "name": "orders",
  "supports_decryption": true,
  "supports_derivation": true,
  "supports_encryption": true,
  "supports_signing": false,
  "type": "aes256-gcm96"
}

Note

The output only displays two valid encryption key versions (5 and -6).

Select the orders encryption key.
Select the Versions tab and then select Rotate encryption key to rotate the encryption key. (Select Rotate to confirm and proceed.)
Repeat the steps a few times to generate multiple versions of the key. 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.
Select the Details tab.
Select Edit encryption key.
From the Minimum decryption version drop-down list, select 5.
Click the Update transit key button. If you select the Versions tab again, the list only shows version 5 and 6.

Generate data key

(Persona: admin)

When you encrypt your data, the encryption key used to encrypt the plaintext is referred to as a data key. This data key needs to be protected so that your encrypted data cannot be decrypted easily by an unauthorized party. In encrypt secrets step, you encrypted your data by specifying the key ring name (orders) and the actual data key used to encrypt the data was never presented to you.

In this step, you are going to use the transit/datakey endpoint which returns the plaintext of a named data key.

Why would I need the data key?

Think of a scenario where you have a 2GB base64 binary large object (blob) that needs to be encrypted. You probably don't want to send the 2GB over the network to Vault and receive the 2GB back. Instead, you can generate a data key and encrypt it locally and use the same data key to decrypt it locally when needed.

The idea with data keys is to allow applications to encrypt and decrypt data without round-tripping through Vault.

The data key is its own full key; you can't decrypt it with the transit key that it is wrapped with. However, because the data key is wrapped by a transit key, and thus protected, you can store it with the data. This way, you can control which Vault clients can decrypt the data through policies.

$ vault write -f transit/datakey/plaintext/orders

Key            Value
---            -----
ciphertext     vault:v6:muu3qQr8beEnEpCoi3225rCe60V2abzjWy7MC7+1XE5pl7JX4RM+7o65+sly0wwG1HEJaUstEhwVhBro
key_version    6
plaintext      JGrAH+uy+iuYfqIf0DtMBCYc/x7PYQ3NFKkF8+hsFqo=

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    $VAULT_ADDR/v1/transit/datakey/plaintext/orders | jq -r ".data"

Example output:

{
  "ciphertext": "vault:v6:eTQ3GSHWBUP7E49BBbzy0XeiAKinuTQdLE3bIew6LYMupDT8b/+/sRB4MU6izHWSuyiG3QuOubwhJqA9",
  "key_version": 6,
  "plaintext": "JntU/jAiyrgHfUsOlSYjiEoxzI6zhrZ56YtdCqrp9fM="
}

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request POST \
    $VAULT_ADDR/v1/transit/datakey/plaintext/orders | jq -r ".data"

Example output:

{
  "ciphertext": "vault:v6:eTQ3GSHWBUP7E49BBbzy0XeiAKinuTQdLE3bIew6LYMupDT8b/+/sRB4MU6izHWSuyiG3QuOubwhJqA9",
  "key_version": 6,
  "plaintext": "JntU/jAiyrgHfUsOlSYjiEoxzI6zhrZ56YtdCqrp9fM="
}

The response contains the plaintext of the data key as well as its ciphertext. Use the plaintext to encrypt your blob. Store the ciphertext of your data key wherever you want. You can even store it in the key/value secrets engine.

When you need to decrypt the blob, request Vault to decrypt the ciphertext of your data key (decrypt ciphertext) so that you can get the plaintext back to decrypt the blob locally. In other words, once your blob is encrypted, you don't have to persist the data key. You only need to keep the ciphertext version of the data key.

Bring your own key (BYOK)

When your use case requires an external key, users of Vault version 1.11.0 or greater can use BYOK functionality to import an existing encryption key that was generated outside Vault.

The target key for import can originate from an HSM or other external source, and must be prepared according to its origin before you can import it.

The example shown here will use a 256-bit AES key, referred to as the target key. To successfully import the target key, you must perform the following operations to prepare it.

Generate an ephemeral 256-bit AES key.
Wrap the target key using the ephemeral AES key with AES-KWP.
Wrap the AES key under the Vault wrapping key using RSAES-OAEP with MGF1 and either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.
Delete the ephemeral AES key.
Append the wrapped target key to the wrapped AES key.
Base64 encode the result.

A specific code example for preparing and wrapping the key for import is beyond the scope of this tutorial. For more details about wrapping the key for import including instructions for wrapping key from an HSM, refer to the key wrapping guide.

Before you can wrap the key for import, you must read the wrapping key from Vault so that it can be used to prepare your key.

$ vault read -field=public_key transit/wrapping_key
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAuO1Gf6nIiD6fem4vOo96
syUFOY7aUt85QlqaJrXoxtYQ3mxiAI4MTm4Wxd3uCmFa4CHtVRaPD+VuJRvOwVlZ
qRK3R6HMsJglElVZjpFovBBjwvThUSoTqqBGK/2cTR15PxeluhwcHIUjo9gT1SKm
WSzSpfGXyNqwGLyZLGpip5FcB7p3CS9Yf77Bzxjnz66kUAqCCm0Q09lGkXyhuXWb
qNAPHPCOVaKlY4b4SpJu921stZGmIC1Ik3r78fLs6ZNthfNt7yvVQGcRKdzrjlRL
z9vv2XBllKsXJf88OWu2iMrU1ybmxPp0Is1pqaNCgGsNzkrWPDKmZIWuyCOHzleb
Tsp0AdjNU9K36AD5x+jztoEGYMumPDZwhzF9WzcyfGNroy2LonXUdza305BhBCKE
Cw+rwchXLxDk9mqz8mJ4cmTvVA+c30dF1a89YReb4NLXVKNbG7VcoO2tgmnioBOj
CUQhmpxLnvKZJ38QKpQzhqHnzOK72K5v3paOyqicPWQDBHhup6UL4+mB+0vfFESH
rhkA0OGqYWEDf9QQ41toafNyuHZtGmzuD1MDBbKTemvhGYL7Gvv6H2UadFBr8Mcz
BLi5V8j/QEjdt+jZ6ZGtIlFZSjLkaKTeqyq2pTLldyuRzm4vBDZ46+dS4whfrFMm
/yg0pLHOE8ItLIqwq4vojscCAwEAAQ==
-----END PUBLIC KEY-----

The output is the (4096-bit RSA) wrapping key.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" --request GET --silent \
    $VAULT_ADDR/v1/transit/wrapping_key | jq

Example output:

{
  "request_id": "45a354b0-2f5f-6fe6-e404-24f28350cc4d",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "public_key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAuO1Gf6nIiD6fem4vOo96\nsyUFOY7aUt85QlqaJrXoxtYQ3mxiAI4MTm4Wxd3uCmFa4CHtVRaPD+VuJRvOwVlZ\nqRK3R6HMsJglElVZjpFovBBjwvThUSoTqqBGK/2cTR15PxeluhwcHIUjo9gT1SKm\nWSzSpfGXyNqwGLyZLGpip5FcB7p3CS9Yf77Bzxjnz66kUAqCCm0Q09lGkXyhuXWb\nqNAPHPCOVaKlY4b4SpJu921stZGmIC1Ik3r78fLs6ZNthfNt7yvVQGcRKdzrjlRL\nz9vv2XBllKsXJf88OWu2iMrU1ybmxPp0Is1pqaNCgGsNzkrWPDKmZIWuyCOHzleb\nTsp0AdjNU9K36AD5x+jztoEGYMumPDZwhzF9WzcyfGNroy2LonXUdza305BhBCKE\nCw+rwchXLxDk9mqz8mJ4cmTvVA+c30dF1a89YReb4NLXVKNbG7VcoO2tgmnioBOj\nCUQhmpxLnvKZJ38QKpQzhqHnzOK72K5v3paOyqicPWQDBHhup6UL4+mB+0vfFESH\nrhkA0OGqYWEDf9QQ41toafNyuHZtGmzuD1MDBbKTemvhGYL7Gvv6H2UadFBr8Mcz\nBLi5V8j/QEjdt+jZ6ZGtIlFZSjLkaKTeqyq2pTLldyuRzm4vBDZ46+dS4whfrFMm\n/yg0pLHOE8ItLIqwq4vojscCAwEAAQ==\n-----END PUBLIC KEY-----\n"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

The output is a JSON object with a data.public_key field containing the (4096-bit RSA) wrapping key.

Use the wrapping key value at step 3 in the previously detailed preparation steps. Once you have prepared and base64 encoded the ciphertext, export the value to the environment variable IMPORT_CIPHERTEXT.

Example:

$ export IMPORT_CIPHERTEXT=Q3Pf4qcMzWrq1BS4OKUfAIpZ4b3IXta68Rc4AuodE+S9JiCr2+OqemaU3OFPleeDTfY8jF1VykqE3DLwzrlD0qlvqg+AiVjOLnBRCf6hFtDM3DrncXZalSlKEyAxWQAt1ZtgccXK6Sje+j4+OchAM+FRNojhMgxTbYYY2zbJZpVH7Qqr9Sd6ypsD0k+RsGUncW3tvjUlea1u0Yvaj4buRlrEKs5W4bLzo8VSsfwporVyC764Xrk9D0sR3PFp0BcIzVEfklhYugUIXHtwdOVLRbtdKGzSeUSY6epS5br6BkLQLsoMEUToSZKo6RhgzS+6uoa6OjO0WsR2KoEjfzuW2VAZSZTDlbCCe+87TDgPBQO/tUm+BdXPh0JOSjJ/DuIbIH6iwkVhKwS/EJrEna88FbwGg8rLVmiVGicrHWTNyoGSnfTyzLza8zkTINlX23k++SMcFnhakFjSJq/jJp8jTjqZyqXzZIL4Bz9GFfhCL2cGBhIAAwvYrUEqEJeaYPtXkoyC8O/86qEvHnEpW1SpC/juWKMAxjQ2cYY2JPMIuote3Ihz+JEFItQSwi0dpoECRKTNdnoPVw3rbHcoffd5xO7vvUB9nObNA/nZ+s+iTcxZmRlbBda4fNRLzzKyrqMxWkb7HBQ7a0L8S0Nmmqah0993Qrbym8E7vz0QgS9TUqZDFtA6meUKy0I+f9+z+907TsS5U9XHhlJRPL6nvv7PDX+X6doPrjYS

Import the key into a key named biometric-reader. Imported keys do not support rotation by default, so include the allow_rotation parameter and set its value to true so that you can also try rotating the imported key.

$ vault write transit/keys/biometric-reader/import \
    ciphertext=$IMPORT_CIPHERTEXT allow_rotation=true

Output:

Success! Data written to: transit/keys/biometric-reader/import

Create a JSON payload containing ciphertext value and any additional parameters.

$ cat > payload.json << EOF
{
  "ciphertext": "Q3Pf4qcMzWrq1BS4OKUfAIpZ4b3IXta68Rc4AuodE+S9JiCr2+OqemaU3OFPleeDTfY8jF1VykqE3DLwzrlD0qlvqg+AiVjOLnBRCf6hFtDM3DrncXZalSlKEyAxWQAt1ZtgccXK6Sje+j4+OchAM+FRNojhMgxTbYYY2zbJZpVH7Qqr9Sd6ypsD0k+RsGUncW3tvjUlea1u0Yvaj4buRlrEKs5W4bLzo8VSsfwporVyC764Xrk9D0sR3PFp0BcIzVEfklhYugUIXHtwdOVLRbtdKGzSeUSY6epS5br6BkLQLsoMEUToSZKo6RhgzS+6uoa6OjO0WsR2KoEjfzuW2VAZSZTDlbCCe+87TDgPBQO/tUm+BdXPh0JOSjJ/DuIbIH6iwkVhKwS/EJrEna88FbwGg8rLVmiVGicrHWTNyoGSnfTyzLza8zkTINlX23k++SMcFnhakFjSJq/jJp8jTjqZyqXzZIL4Bz9GFfhCL2cGBhIAAwvYrUEqEJeaYPtXkoyC8O/86qEvHnEpW1SpC/juWKMAxjQ2cYY2JPMIuote3Ihz+JEFItQSwi0dpoECRKTNdnoPVw3rbHcoffd5xO7vvUB9nObNA/nZ+s+iTcxZmRlbBda4fNRLzzKyrqMxWkb7HBQ7a0L8S0Nmmqah0993Qrbym8E7vz0QgS9TUqZDFtA6meUKy0I+f9+z+907TsS5U9XHhlJRPL6nvv7PDX+X6doPrjYS", "allow_rotation": true
}
EOF

Import the key.

$ curl \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data @payload.json \
    $VAULT_ADDR/v1/transit/keys/biometric-reader/import

Note

This command is expected to produce no output.

Try using the newly imported key to encrypt some data.

$ vault write transit/encrypt/biometric-reader plaintext=$(base64 <<< "secret biometric data")
Key            Value
---            -----
ciphertext     vault:v1:G0G2+vFOE5RLLmXtVAmk2Xdl9y8Wti/iYe1mwBieHzCIpI03M5MyWX6JbE9JPiJyGF0=
key_version    1

Create a JSON payload.

$ cat > payload.json << EOF
{
  "plaintext": "$(base64 <<< "secret biometric data")"
}
EOF

Encrypt the data.

$ curl \
    --silent \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    --data @payload.json \
    $VAULT_ADDR/v1/transit/encrypt/biometric-reader | jq

Example output:

{
  "request_id": "14b2c81c-2a90-cfcc-eeb3-0f69ce022308",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "ciphertext": "vault:v1:06OmrqB6EBSX+mMersFK4s4l705fpM+vEcnvo+e9B/CHHluq1awjciZ2fdtXFSdwNVc=",
    "key_version": 1
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

The imported key is working, and the plaintext value was encrypted and returned as the value of the ciphertext field.

Note

To import subsequent versions of the key, you must use the import_version API endpoint.

Let's take a look a the key information.

$ vault read transit/keys/biometric-reader
Key                            Value
---                            -----
allow_plaintext_backup         false
auto_rotate_period             0s
deletion_allowed               false
derived                        false
exportable                     false
imported_key                   true
imported_key_allow_rotation    true
keys                           map[1:1665164440]
latest_version                 1
min_available_version          0
min_decryption_version         1
min_encryption_version         0
name                           biometric-reader
supports_decryption            true
supports_derivation            true
supports_encryption            true
supports_signing               false
type                           aes256-gcm96

$ curl \
    --silent \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    $VAULT_ADDR/v1/transit/keys/biometric-reader | jq

Example output:

{
  "request_id": "3cd853ff-48a6-9936-f8de-806157a262f3",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "allow_plaintext_backup": false,
    "auto_rotate_period": 0,
    "deletion_allowed": false,
    "derived": false,
    "exportable": false,
    "imported_key": true,
    "imported_key_allow_rotation": true,
    "keys": {
      "1": 1665164440
    },
    "latest_version": 1,
    "min_available_version": 0,
    "min_decryption_version": 1,
    "min_encryption_version": 0,
    "name": "biometric-reader",
    "supports_decryption": true,
    "supports_derivation": true,
    "supports_encryption": true,
    "supports_signing": false,
    "type": "aes256-gcm96"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

The key's latest_version is currently 1.

Rotate the key.

Note

Once an imported key is rotated within Vault, it will no longer support importing key material with the import_version endpoint.

$ vault write -force transit/keys/biometric-reader/rotate
Success! Data written to: transit/keys/biometric-reader/rotate

$ curl \
    --silent \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    --request POST \
    $VAULT_ADDR/v1/transit/keys/biometric-reader/rotate

Note

This command is expected to produce no output.

Check the key information once more.

$ vault read transit/keys/biometric-reader
Key                       Value
---                       -----
allow_plaintext_backup    false
auto_rotate_period        0s
deletion_allowed          false
derived                   false
exportable                false
imported_key              false
keys                      map[1:1665164440 2:1665165083]
latest_version            2
min_available_version     0
min_decryption_version    1
min_encryption_version    0
name                      biometric-reader
supports_decryption       true
supports_derivation       true
supports_encryption       true
supports_signing          false
type                      aes256-gcm96

$ curl \
    --silent \
    --header "X-Vault-Token: $VAULT_TOKEN" \
    $VAULT_ADDR/v1/transit/keys/biometric-reader | jq

Example output:

{
  "request_id": "d34f3208-3e4e-0ec0-1e84-dcb4be2e9f6b",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "allow_plaintext_backup": false,
    "auto_rotate_period": 0,
    "deletion_allowed": false,
    "derived": false,
    "exportable": false,
    "imported_key": false,
    "keys": {
      "1": 1665164440,
      "2": 1665165083
    },
    "latest_version": 2,
    "min_available_version": 0,
    "min_decryption_version": 1,
    "min_encryption_version": 0,
    "name": "biometric-reader",
    "supports_decryption": true,
    "supports_derivation": true,
    "supports_encryption": true,
    "supports_signing": false,
    "type": "aes256-gcm96"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

The key's latest_version is currently 2, and you can no longer import external versions of the key as it is now internally maintained by Vault.

Clean up

Unset the VAULT_TOKEN environment variable.
```
$ unset VAULT_TOKEN
```
Unset the VAULT_ADDR environment variable.
```
$ unset VAULT_ADDR
```
Unset the VAULT_NAMESPACE environment variable.
```
$ unset VAULT_NAMESPACE
```
Unset the APP_ORDER_TOKEN environment variable.
```
$ unset APP_ORDER_TOKEN
```
Unset the IMPORT_CIPHERTEXT environment variable.
```
$ unset IMPORT_CIPHERTEXT
```
You can stop the Vault dev server by pressing Ctrl+C where the server is running. Or, execute the following command.
```
$ pgrep -f vault | xargs kill
```

Help and Reference

Back to Collection