Wrapped Secrets

Wrapping and Unwrapping with Vault: A Step-by-Step Guide

Introduction to Wrapping and Unwrapping in Vault

Wrapping and unwrapping are features in Vault that enable secure sharing of secrets. In essence, wrapping allows you to encrypt a secret in a way that can be safely shared with others, while unwrapping enables the recipient to decrypt and access the original secret.

The main benefit of wrapping and unwrapping is that it eliminates the need to manage complex encryption tools, such as email certificates or GPG keys, making it easier to share sensitive information securely. Wrapped secrets are also protected by additional security measures, including a limited lifespan (TTL) and a one-time use policy, ensuring that they can only be accessed once within a specified timeframe. This guide will walk you through the process of wrapping secrets to share them securely, and unwrapping them to access the underlying information, providing a convenient and secure way to share secrets with others.

How-To Send a Wrapping Token

When sending wrapping tokens to others, provide clear instructions, the wrapping token, and its TTL. You can use the following template:

You have been sent a secret in a wrapping token. To access the secret, you’ll need to unwrap the token using Vault. For step-by-step instructions, please visit our documentation at: https://cloud.uni-muenster.de/docs/vault/wrapped_secrets/#how-to-unwrap-a-token

Before unwrapping the token, please read the ‘Important Security Notice’ on the documentation page, as it contains critical information about handling wrapping tokens securely.

How-To Wrap Secrets

CLI

Before you begin, ensure that you have Vault installed and are logged in to Vault. For instructions on installing Vault and logging in, please refer to the docs.

To wrap a secret using Vault, you can provide the secret data as a JSON string or reference a file containing the data. You can wrap a secret using one of the following commands:

vault write -wrap-ttl=10m sys/wrapping/wrap data='<json-data>'

or

vault write -wrap-ttl=10m sys/wrapping/wrap data=@data.json

The output looks like this:

Key                              Value
---                              -----
wrapping_token:                  <wrapping-token>
wrapping_accessor:               x
wrapping_token_ttl:              10m
wrapping_token_creation_time:    x
wrapping_token_creation_path:    sys/wrapping/wrap

Replace <json-data> with the actual JSON data you want to wrap, or @data.json with the path to a file containing the secret data. The -wrap-ttl option specifies the time to live (TTL) of the wrapping token. The TTL determines how long the token remains valid.

The command will output a result containing a wrapping_token, which must be shared with the intended recipient to allow them to unwrap the secret.

GUI

Navigate to https://vault.uni-muenster.de/ui/vault/tools/wrap in your web browser. If you are not already logged in, you will be prompted to do so before proceeding. Enter the secret you wish to share as JSON data in the provided field. Adjust the TTL (Time to Live) setting according to your needs. Click the “Wrap data” button to initiate the wrapping process. Once complete, you will receive a wrapping token, that you can share.

How-To Unwrap a Token

Important Security Notice

If you have received a wrapping token, it is crucial to handle it promptly and securely. Please note the following:

  • You have a limited time to unwrap the token and retrieve the enclosed data. This window of opportunity is short-lived and can only be utilized once.
  • After unwrapping the token, it is essential to store the contents in a secure location, as you will not be able to unwrap the token again.
  • If you attempt to unwrap the token and encounter an error indicating that the token is invalid, inform the sender immediately. This may indicate that someone else has already unwrapped the token and gained access to the sensitive information inside.
  • In such cases, treat the contents as compromised and take immediate action to revoke or rotate any secrets that were enclosed.

Now that you’re aware of the importance of secure token handling, let’s explore the various methods for unwrapping a token:

CLI with Vault

If you have Vault installed and configured, you can unwrap a token by running the following command:

VAULT_TOKEN="<wrapping-token>" vault unwrap

Replace <wrapping-token> with the actual wrapping token you received.

The command will output the unwrapped data in a simple format:

Key     Value
---     -----
data    <json-data>

CLI with Curl

Alternatively, you can use the Vault HTTP API with curl to unwrap the token without having Vault installed locally. Use the following curl command:

curl --header "X-Vault-Token: <wrapping-token>" --request POST https://vault.uni-muenster.de/v1/sys/wrapping/unwrap

Replace <wrapping-token> with the actual wrapping token you received.

The API will respond with a JSON object containing the unwrapped data:

{
  "request_id": "x",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "data": "<json-data>"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null,
  "mount_type": "system"
}

GUI

Open a web browser and navigate to https://vault.uni-muenster.de/ui/vault/tools/unwrap. If you’re not already logged in, you’ll be prompted to authenticate before proceeding. Please log in using the OIDC option - do not enter a token at this stage.

OIDC Login

Once you’ve successfully logged in, you can then enter the wrapping token and click the ‘Unwrap data’ button:

Unwrap Data