Cubbyhole Response Wrapping

The term cubbyhole comes from an Americanism where you get a "locker" or "safe place" to store your belongings or valuables. In Vault, the cubbyhole is your "locker". All secrets are namespaced under your token. If that token expires or is revoked, all the secrets in its cubbyhole are revoked as well.

It is not possible to reach into another token's cubbyhole even as the root user. This is an important difference between the cubbyhole and the key/value secrets engine. The secrets in the key/value secrets engine are accessible to any token for as long as its policy allows it.

»Personas

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

• admin with privileged permissions to create tokens
• apps trusted entity retrieving secrets from Vault

»Challenge

In order to tightly manage the secrets, you set the scope of who can do what using the Vault policy and attach that to tokens, roles, entities, etc.

Think of a case where you have a trusted entity (Chef, Jenkins, etc.) which reads secrets from Vault. This trusted entity must obtain a token. If the trusted entity or its host machine was rebooted, it must re-authenticate with Vault using a valid token.

How can you securely distribute the initial token to the trusted entity?

»Solution

Use Vault's cubbyhole response wrapping where the initial token is stored in the cubbyhole secrets engine. The wrapped secret can be unwrapped using the single-use wrapping token. Even the user or the system created the initial token won't see the original value. The wrapping token is short-lived and can be revoked just like any other tokens so that the risk of unauthorized access can be minimized.

What is cubbyhole response wrapping?

• When response wrapping is requested, Vault creates a temporary single-use token (wrapping token) and insert the response into the token's cubbyhole with a short TTL
• Only the expecting client who has the wrapping token can unwrap this secret
• Any Vault response can be distributed using the response wrapping

Benefits of using the response wrapping:

• It provides cover by ensuring that the value being transmitted across the wire is not the actual secret. It's a reference to the secret.
• It provides malfeasance detection by ensuring that only a single party can ever unwrap the token and see what's inside
• It limits the lifetime of the secret exposure
  • The TTL of the response-wrapping token is separate from the wrapped secret's lease TTL

»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. Make sure that your Vault server has been initialized and unsealed.

NOTE: An interactive tutorial is also available if you do not have a Vault environment to perform the steps described in this tutorial. Click the Show Terminal button to start.

»Policy requirements

To perform all tasks demonstrated in this tutorial, your policy must include the following permissions:

# Manage tokens
path "auth/token/*" {
  capabilities = [ "create", "read", "update", "delete", "sudo" ]
}

# Write ACL policies
path "sys/policies/acl/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Manage secret/dev secrets engine - for Verification test
path "secret/dev" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

If you are not familiar with policies, complete the policies tutorial.

»Scenario Introduction

Think of a scenario where apps read secrets from Vault. The apps need:

• Policy granting "read" permission on the specific path (secret/dev)
• Valid tokens to interact with Vault

Setting the appropriate policies and token generation are done by the admin persona. For the admin to distribute the initial token to the app securely, it uses cubbyhole response wrapping. In this tutorial, you perform the following:

1. Create and wrap a token
2. Unwrap the secret

»Step 1: Create and wrap a token

(Persona: admin)

When a newly created token is wrapped, Vault inserts the generated token into the cubbyhole of a single-use token, returning that single-use wrapping token. Retrieving the secret requires an unwrap operation against this wrapping token.

In this scenario, an admin user creates a token using response wrapping. To perform the steps in this tutorial, first create a policy for the app.

apps-policy.hcl:

# For testing, read-only on secret/dev path
path "secret/data/dev" {
  capabilities = [ "read" ]
}

»Step 2: Unwrap the secret

(Persona: apps)

The apps persona receives a wrapping token from the admin. In order for the apps to acquire a valid token to read secrets from secret/dev path, it must run the unwrap operation using this token.

The following tasks will be performed to demonstrate the client operations:

1. Create a token with default policy
2. Authenticate with Vault using this default token (less privileged token)
3. Unwrap the secret to obtain more privileged token (apps persona token)
4. Verify that you can read secret/dev using the appstoken

»Additional Discussion: Cubbyhole

The cubbyhole secrets engine provides your own private secret storage space where no one else can read (including root). This comes handy when you want to store a password tied to your username that should not be shared with anyone.

The cubbyhole secrets engine is mounted at the cubbyhole/ prefix by default. The secrets you store in the cubbyhole/ path are tied to your token and all tokens are permitted to read and write to the cubbyhole secrets engine by the default policy.

$ vault policy read default

...
# Allow a token to manage its own cubbyhole
path "cubbyhole/*" {
    capabilities = ["create", "read", "update", "delete", "list"]
}
...

To test the cubbyhole secrets engine, perform the following steps. (NOTE: Keep using the apps token from Step 2 to ensure that you are logged in with non-root token.)

$ vault write cubbyhole/<PATH> <KEY>=<VALUE>

$ vault read cubbyhole/<PATH>

$ vault write cubbyhole/private/access-token token="123456789abcdefg87654321"
Success! Data written to: cubbyhole/private/access-token

$ vault read cubbyhole/private/access-token
Key     Value
---     -----
token   123456789abcdefg87654321

$ VAULT_TOKEN=<ROOT_TOKEN> vault read cubbyhole/private/access-token

No value found at cubbyhole/private/access-token

»Help and Reference

• Cubbyhole
• Response Wrapping