Token-Scoped Temporary Storage with Vault Cubbyhole

Cubbyhole is a built-in Vault secrets engine that gives every token its own private namespace. When the token is revoked, the contents disappear, making it a great fit for short-lived secret storage and handoff.

This article covers how Cubbyhole works, its lifecycle, how it pairs with response wrapping, hands-on workflows, operational constraints, and the gotchas commonly tested on the exam.

Cubbyhole Basics: A Private Vault Per Token

Cubbyhole is a secrets engine that ships with Vault by default. It gives each access token its own dedicated storage area. Values written by one token can only be read by that same token. There is no way to grant access from another token or via policy delegation.

The API is simple, with no versioning or metadata management. TTL is not attached to the secret itself; it follows the lifecycle of the associated token. When the token expires or is revoked, the Cubbyhole data is automatically purged.

• Default mount path: cubbyhole/
• Access boundary: per-token (no access from other tokens)
• Use cases: startup bootstrapping, short-lived token staging, and a scaffold for one-way secure handoff

Basic CLI operations

vault write cubbyhole/bootstrap token=child-abc note="startup"
vault read cubbyhole/bootstrap
vault delete cubbyhole/bootstrap

Security Properties and Lifecycle: TTL, Revocation, and Inheritance

The availability of Cubbyhole data tracks the associated token, not the stored entry. Renewing the token preserves the data, while revoking it wipes the data immediately. This prevents secrets from being left behind.

Pay attention to the parent-child token relationship. Child tokens have their own Cubbyhole, isolated from the parent. When parent revocation cascades to children, the child tokens are invalidated too, and their Cubbyhole contents become inaccessible.

• Token renewal preserves Cubbyhole contents
• Token revocation or expiry destroys the contents
• Policy cannot grant access to another token's Cubbyhole
• Behavior is consistent regardless of HA setup or storage backend (per Vault's design)

Token renewal/revocation and Cubbyhole behavior (CLI example)

# トークン発行 (例)
vault token create -ttl=1h -policy=default -format=json | jq -r .auth.client_token > parent.token

# 子トークン発行 (親の権限範囲内)
VAULT_TOKEN=$(cat parent.token) vault token create -ttl=15m -format=json | jq -r .auth.client_token > child.token

# 子でCubbyholeへ保存
VAULT_TOKEN=$(cat child.token) vault write cubbyhole/boot key=value

# 親を取り消すと、親由来の子も無効化されアクセス不能に
vault token revoke $(cat parent.token)

# 以降の child.token での read は失敗する想定
VAULT_TOKEN=$(cat child.token) vault read cubbyhole/boot

Hands-On: Token-Scoped Temporary Storage Flow

Cubbyhole shines for bootstrapping: a freshly started process uses a least-privilege child token to receive temporary config or a follow-on retrieval token. The distributor writes to a location only the target process's token can see, and the process retrieves and discards it right after startup. That pattern is safe.

Direct Cubbyhole reads and writes are NOT one-time. If you need to guarantee single-use behavior, use response wrapping (covered below).

• Issue a child token per process
• Keep child token TTLs short and renew as needed
• After retrieval, clean up via explicit delete or token revocation

Temporary storage via CLI / HTTP API

# CLI: 子トークンで書き込み/読み出し
VAULT_TOKEN=$CHILD_TOKEN vault write cubbyhole/config db_user=app db_pass=s3cr3t
VAULT_TOKEN=$CHILD_TOKEN vault read cubbyhole/config

# HTTP API: 書き込み
curl \
  -H "X-Vault-Token: $CHILD_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"db_user":"app","db_pass":"s3cr3t"}' \
  $VAULT_ADDR/v1/cubbyhole/config

# HTTP API: 読み出し
curl -H "X-Vault-Token: $CHILD_TOKEN" $VAULT_ADDR/v1/cubbyhole/config

Response Wrapping and Cubbyhole: Secure One-Time Handoff

Response wrapping seals a Vault response inside a wrapping token so it can be retrieved exactly once. Internally, Cubbyhole is used, and if the token is not unwrapped within wrap-ttl, the contents are automatically destroyed. This lets you ship only a token instead of the secret itself.

The producer attaches -wrap-ttl to any read operation, and the consumer calls vault unwrap or POSTs to /sys/wrapping/unwrap with the wrapping token. On a successful unwrap, the contents are returned and the token is invalidated.

• Keep wrap-ttl short (e.g., 60s to 5m)
• Wrapping tokens are single-use. Enable audit logging to watch for leaks
• Decide your retry strategy in advance (re-wrap on failure)

Response wrapping handoff

Response wrapping example

# 秘密データを読む際にラップ (例: kv v2 上のシークレット)
# ここでは対象エンジンが何であれ、応答をラップトークン化する点がポイント
vault kv get -wrap-ttl=60s kv/app/api
# 出力: wrapping_token=... (一度だけ使用可能)

# 受け取り側: unwrap して中身を取得 (トークンは失効)
VAULT_TOKEN=$WRAPPING_TOKEN vault unwrap

# HTTP APIでも同様
curl -s -H "X-Vault-Token: $VAULT_TOKEN" \
  "$VAULT_ADDR/v1/kv/data/app/api?wrap_ttl=60s"
# レスポンスJSONの auth.client_token がラップトークン

# unwrap
curl -s -H "X-Vault-Token: $WRAPPING_TOKEN" \
  -X POST "$VAULT_ADDR/v1/sys/wrapping/unwrap"

Operations and Constraints: What to Store and What Not To

Cubbyhole is ideal for lightweight temporary storage but unsuitable for large binaries or long-lived config files. Size limits depend on the underlying storage and operational policy, so as a rule, target small secrets and tokens only.

If audit logging is enabled, access under cubbyhole/ is also recorded (the data itself is masked). This is useful for leak detection and monitoring how wrapping tokens are handled.

• Default policy: small values, short-lived, disposable
• Clean up via explicit delete or token revocation when no longer needed
• Use other engines like KV v2 for long-term storage or sharing

Make cleanup explicit

# 取り出し後に削除
VAULT_TOKEN=$CHILD_TOKEN vault delete cubbyhole/config

# 役目が終わった子トークンを取り消す
vault token revoke $CHILD_TOKEN

Exam Prep: Common Misconceptions and Terminology

Cubbyhole is private storage attached to a token. It is not designed to be shared with others via policy. Do not confuse it with the sharing and versioning model of KV v2.

Response wrapping is the mechanism that delivers one-time retrieval, and you should remember that it uses Cubbyhole internally. Contents are destroyed on wrap-ttl expiry or on a successful unwrap.

• Keywords: per-token isolation, deleted on revoke, wrap-ttl, unwrap = single-use
• Design choices: KV for sharing/long-term, wrapping for single-use delivery, Cubbyhole for short-lived same-token handoff
• Gotcha: putting data in Cubbyhole alone does not make it single-use (only wrapping does)

One-liner sanity check

# Cubbyholeはこのトークンでしか読めるべきでない
VAULT_TOKEN=$OTHER_TOKEN vault read cubbyhole/boot  # -> 権限外エラーになる想定

Check Your Understanding

Frequently Asked Questions