Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท Secrets Engines

Cubbyhole and Response Wrapping

Learn Vault's cubbyhole engine and response wrapping: single-use wrapping tokens, the unwrap flow, TTLs, lookup and rewrap, with a runnable single-use token model.

How do you hand a secret to a machine without the courier seeing it? Response wrapping is Vault's answer. Instead of returning a secret directly, Vault stores it in a cubbyhole belonging to a new single-use token and returns only that token, the wrapping token. The recipient exchanges it once to unwrap the secret. If anyone else used it first, the recipient's unwrap fails, which exposes the interception.

This lesson explains the cubbyhole engine, the wrapping flow, and how it solves the "secret zero" delivery problem. You will run a model that behaves like a single-use token.

Vault is not runnable here, so the CLI and API examples are read-only. The Python models are simplified stand-ins for the behaviour.

The cubbyhole secrets engine

The cubbyhole/ mount is enabled by default and cannot be disabled. Its special property: each token has its own private cubbyhole, and nothing outside that token can read it, not even root and not other tokens. When the token expires or is revoked, its cubbyhole is destroyed.

Terminal
vault write cubbyhole/notes message="only I can see this"
vault read cubbyhole/notes

A different token reading cubbyhole/notes sees its own, empty cubbyhole. You rarely use cubbyhole directly; its job is to support response wrapping.

Response wrapping

You can ask Vault to wrap the response of nearly any request by setting a wrap TTL. On the CLI:

Terminal
vault kv get -wrap-ttl=5m -mount=secret app/db
# returns a wrapping token and its TTL instead of the secret

Or send the header X-Vault-Wrap-TTL: 5m on an API request. Behind the scenes Vault:

  1. performs the request and gets the response;
  2. creates a new single-use token with the wrap TTL;
  3. puts the response into that token's cubbyhole;
  4. returns the wrapping token (and its TTL, creation path, and accessor).

The recipient unwraps once:

Terminal
vault unwrap <wrapping_token>

After one successful unwrap the token is used up, and the cubbyhole content is gone.

sequenceDiagram
    participant Admin as Trusted broker
    participant V as Vault
    participant App as Application
    Admin->>V: request secret, wrap-ttl 5m
    V-->>Admin: wrapping token (single use)
    Admin->>App: deliver wrapping token
    App->>V: unwrap
    V-->>App: the secret (token destroyed)

Only the wrapping token travels; the secret itself goes straight from Vault to the application.

Why wrapping helps

  • Limited exposure: the wrapping token is valid for minutes, so an old log entry is harmless.
  • Tamper evidence: if an attacker unwraps first, the real recipient's unwrap fails. That failure is a security alert, and you should investigate and revoke the secret.
  • No plaintext in transit systems: the CI system, config management tool or chat only ever sees an opaque, short-lived token.
  • Provenance: vault token lookup on the wrapping token (or sys/wrapping/lookup, which needs no authentication) reveals who created it and what path, which lets the recipient verify the token came from the expected source before unwrapping.

Typical uses are AppRole secret IDs, initial tokens for new servers, and responses for human handover.

Terminal
vault read sys/wrapping/lookup token=<wrapping_token>   # inspect without unwrapping
vault write sys/wrapping/rewrap token=<wrapping_token>  # new wrapping token, same content
vault write sys/wrapping/wrap foo=bar                    # wrap arbitrary data

lookup does not consume the token. rewrap is useful when a wrap token is about to expire. Using the HTTP API, the unwrapping call is POST /v1/sys/wrapping/unwrap with the wrapping token as the X-Vault-Token or in the body.

A single-use token you can run

Python Model of a single-use wrapping token

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice what the failing second unwrap tells the application: someone else got there first. In a real system that failure should page a human.

A recipient's safe procedure

Python Verify before you unwrap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The recipient should compare creation_path with what it expects before unwrapping, because lookups are free and unwrapping is final.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is stored in a wrapping token's cubbyhole?

    Vault saves the original response in the cubbyhole of the single-use wrapping token.
  2. 2. Who can read another token's cubbyhole?

    Cubbyholes are private per token, even from root.
  3. 3. The application's unwrap fails with "not valid". What should you assume?

    A single-use token that was already consumed signals possible interception.
  4. 4. Which operation inspects a wrapping token without consuming it?

    Lookup returns metadata such as creation path and TTL, and does not unwrap.

Summary

  • Each token has a private cubbyhole; it is destroyed with the token.
  • Response wrapping stores a response in a single-use token's cubbyhole and returns only that token.
  • Wrap tokens expire quickly and unwrap once, making interception detectable.
  • Verify the token's creation path with lookup before unwrapping.
  • It is the standard way to deliver AppRole secret IDs and bootstrap tokens.

Next: The PKI Secrets Engine