open-vault/website/source/docs/concepts/response-wrapping.html.md

layout	page_title	sidebar_current	description
docs	Response Wrapping	docs-concepts-response-wrapping	Wrapping responses in cubbyholes for secure distribution.

Response Wrapping

In many Vault deployments, clients can access Vault directly and consume returned secrets. In other situations, it may make sense to or be desired to separate privileges such that one trusted entity is responsible for interacting with most of the Vault API and passing secrets to the end consumer.

However, the more relays a secret travels through, the more possibilities for accidental disclosure, especially if the secret is being transmitted in plaintext.

In Vault 0.3 the cubbyhole backend was introduced, providing storage scoped to a single token. The Cubbyhole Principles blog post described how this, along with the limited-use and time-to-live features of Vault tokens, could be used to securely authenticate a Vault client in such a way that the final Vault token was only readable by the end consumer, and malfeasance could be detected. The major downside to this operation was the need to write programs to perform this wrapping (and by extension, those programs need to be trusted).

Starting in 0.6, this concept is taken to its logical conclusion: almost every response that Vault generates can be automatically wrapped inside a single-use, limited-time-to-live token's cubbyhole. Details can be found in the cubbyhole backend documentation.

This capability should be carefully considered when planning your security architecture. For instance, many Vault deployments use the pki backend to generate TLS certificates and private keys for services. If you do not wish these services to have access to the generation API, a trusted third party could generate the certificates and private keys and pass the resulting wrapping tokens directly to the services in need. A simple API call will return the original PKI information; if the call fails, a security alert can be raised.

To look at the above example another way, response wrapping also frees end services from needing to generate a CSR and pass it to Vault through the trusted third party simply to ensure that the private key corresponding to the eventual certificate remains private. The end service can be assured that only it will see the generated private key and that any malfeasance is detected. This can significantly reduce the complexity of any relaying third party.

One final note: if the wrapped response is an authentication response containing a Vault token, the token's accessor will be made available in the returned wrap information. This allows privileged callers to generate tokens for clients and revoke these tokens (and their created leases) at an appropriate time, while never being exposed to the actual generated token IDs.