We are proud to announce the release of Vault 0.3. Vault is a tool for managing secrets. From storing credentials and API keys to encrypting sensitive data, Vault is meant to be a solution for all secret management needs.
Vault 0.3 brings many new features including an
ssh backend, a
backend, new features and improvements to the
transit backend, settable
global and per-mount default/max TTLs, PGP encryption for unseal keys, large
performance improvements for the
generic backend, Duo Multi-Factor
Authentication support, and much more. We cannot possibly list all of the
improvements here, so please see the full
Vault 0.3 CHANGELOG
for more details.
In addition, the entire 0.2 codebase underwent an audit by noted security experts iSEC Partners. Although we cannot share the results, their feedback was valuable, and we intend to continue with regular security audits to ensure that Vault can be trusted with the secrets of even the most cautious of organizations.
As always, a big thanks to our community for their ideas, bug reports, and pull requests.
You can download Vault 0.3 from the project website.
Read on to learn more about the major new features in Vault 0.3.
The new Vault
ssh secret backend
allows Vault to arbitrate SSH to machines through the use of One-Time Passwords
(OTPs) or dynamically-generated SSH keys.
In a typical organization, delegation of SSH access has been performed in a number of ways. The least secure has been manual sharing of access tokens (passwords or keys) to a specific user on the target host; once this is done, it can be difficult or impossible to know which actual person performed an action with that user account. A step up is creating separate user accounts on every machine for each user, which allows better tracking but is a logistical nightmare. A third approach is a bastion host that proxies SSH access, allowing central configuration but at a severe performance penalty.
ssh backend solves this problem by marrying the flexible policy/ACL
capabilities of Vault with flexible role definitions, allowing authenticated
Vault users to request credentials from Vault as a central configuration point
but then connect directly to end-hosts, without a performance penalty. Roles
match usernames and other parameters to CIDR inclusion and exclusion lists.
The following example uses the recommended One-Time Password type of the backend. Because every access has a different One-Time Password, Vault's audit logs can precisely marry which token was used to log in to a system, even when those logins are accessing the same user.
$ vault write ssh/roles/otp_key_role key_type=otp default_user=username cidr_list=x.x.x.x/y,m.m.m.m/n Success! Data written to: ssh/roles/otp_key_role
$ vault write ssh/creds/otp_key_role ip=x.x.x.x Key Value lease_id ssh/creds/otp_key_role/73bbf513-9606-4bec-816c-5a2f009765a5 lease_duration 600 lease_renewable false port 22 username username ip x.x.x.x key 2f7e25a2-24c9-4b7b-0d35-27d5e5203a5c key_type otp
The OTP can be used directly as the SSH password:
$ ssh username@localhost Password: <Enter OTP> username@ip:~$
Or, you can use the new
vault ssh command to automate it:
$ vault ssh -role otp_key_role email@example.com username@ip:~$
ssh backend is another example of how Vault can be used as a security
foundation, beyond just storing secret data. Using the
ssh backend makes
it simpler for organizations to migrate to a zero trust datacenter.
cubbyhole secret backend
is a variation on the
generic secret backend
with an important distinction: the entire space is tied to a particular token,
giving each token a "cubbyhole" for stashing data. When the token expires or
is revoked, its cubbyhole is removed and the data inside is no longer
This enables a number of useful workflows, including some previously difficult authentication scenarios. As an example, suppose you need to give a container a Vault token that it will use to fetch the rest of its secrets and credentials. One common way is to inject the token into the container's environment, with the drawback that this environment is readable by any process with visibility into the container runtime, and may well appear in logs from the container management system, host, or the container itself.
However, in many situations such logs may not be accessible immediately. As a
result, using the
cubbyhole backend, we can take advantage of several of
Vault's security primitives (limited use credentials, credential expiration) to
construct the following authentication workflow:
- A process responsible for creating Vault authentication tokens creates two tokens: a permanent (
perm) token and a temporary (
temp) token. The
permtoken contains the final set of policies desired for the application in the container. The
temptoken has a lease duration of 15 seconds and a maximum use count of 2.
temptoken is used to write the
permtoken into the cubbyhole storage specific to
temp. This requires a single write operation, reducing the remaining uses of
- The invoked process gives the
temptoken to the container management engine, which starts the container and injects the
temptoken value into the container environment.
- The application inside the container reads the
temptoken from the container environment and uses it to fetch the
permtoken from the cubbyhole. This read operation exhausts the
temptoken's use limit, the
temptoken is revoked, and its cubbyhole is destroyed.
- If the application is unable to use the
temptoken, it alerts; because accesses to the cubbyhole are logged in Vault's audit logs, an operator can then use the logs to discover whether the application took too long to start (and adjust the timeout of the temp token accordingly) or whether another process had used the token.
No solution to the chicken-and-egg problem of initial credential management is perfect. However, due to the short invalidity period and limited uses of the shared initial credential, we think that this will be an acceptable solution for many teams trying to manage security policy.
Vault now supports tunable system and per-mount TTLs for leases, for both default and maximum durations.
The system settings are configured in
Vault's configuration file.
The per-mount configuration is handled by a new command:
with additional output to the
$ vault mounts Path Type Default TTL Max TTL Description cubbyhole/ cubbyhole n/a n/a per-token private secret storage secret/ generic system system generic secret storage sys/ system n/a n/a system endpoints used for control, policy and debugging
$ vault mount-tune -default-lease-ttl=4h -max-lease-ttl=24h secret Successfully tuned mount 'secret'!
$ vault mounts Path Type Default TTL Max TTL Description cubbyhole/ cubbyhole n/a n/a per-token private secret storage secret/ generic 14400 86400 generic secret storage sys/ system n/a n/a system endpoints used for control, policy and debugging
An important part of this feature is that while the per-mount default TTL must
be less than the per-mount maximum TTL (or, if there is no per-mount maximum
TTL, the system maximum TTL), the per-mount maximum TTL overrides the system
value (as such,
root tokens or tokens with appropriate
sudo access) are
required). Combined with the fact that most backends can be mounted at multiple
paths, this allows for a very high degree of administrative flexibility.
See the mounts API documentation for full details.
Note: it is currently up to each backend as to whether it adheres to the set default. Some backends may ignore this, to (for instance) allow per-role defaults instead. However, the configured maximums are enforced by Vault's core, so will always be honored.
PGP Encryption for Unseal Keys
pgp_keys parameter can now be passed when initializing Vault or rotating its
master key, formatted as a string array with base64-encoded PGP keys. The length
must match the
secret_shares parameter. If provided, each output unseal key
will be encrypted with the given public keys; ordering is preserved.
See the init API documentation for more details.
Performance Improvements for Generic
supports the idea of a TTL, but does not actually destroy data when the TTL runs out.
The idea is for writers of data to tell consumers of the data how often they should
check for new values. However, each read on a value set with a TTL would generate
a lease, which became an incredibly costly operation when the number of reads scaled up.
generic no longer generates leases when values are read. A TTL will still be
returned; either the system/mount default, or the TTL set on a particular key, but
this operation does not register a lease in Vault's core. Benchmarks have shown about
a 10x increase in the number of reads per time period that Vault can support as a
Duo Multi-Factor Authentication Support
Vault 0.3 introduces some changes to how it stores data designed to further enhance Vault's capability to detect tampering within its physical store.
As a result, all data written by Vault 0.3 cannot be read by prior versions of Vault. If you think you may want to roll back, ensure you have a stored copy of your storage backend data.
There are a few other deprecations; note that deprecations and breaking changes are announced in advance on the Vault mailing list:
As noted in the Vault 0.3 CHANGELOG, cookie authentication is no longer supported. You must use the
X-Vault-Tokenheader for authentication.
In order to address confusion over the term "lease" being used to describe both a collection of metadata, including a duration, and the duration itself, we are migrating to the term Time-To-Live ("ttl") to describe the duration. At this time, there are no plans to replace the areas in the API using "lease_duration" -- such as in returned JSON responses -- as this is a more verbose but still accurate term; however, we will be deprecating the use of the term "lease" in backends going forward. For 0.3, "lease" is still accepted for the
pkibackends, but you should migrate to using "ttl" for these; in 0.4 only "ttl" will be supported. Other backends will migrate in future releases.
While the roadmap for 0.4 is still being determined, there are a few things that we know will be included:
- Increased capabilities for the
pkibackend, including in-Vault self-signed and intermediate CA certificate generation and the ability to issue certificates requested in CSRs. You will be able to use Vault to manage your entire X.509 PKI workflow from start to finish.
- A rewrite of the LDAP authentication backend, which will improve its flexibility and compatibility with more LDAP server configurations.
- The ability to push CRL lists into the
tlsauthentication backend for revocation checking, similar to Chrome's CRLSets.
Of course, other improvements and bug fixes will be included as well!
As always, we recommend upgrading and testing this release in an isolated environment. If you experience any issues, please report them on the Vault GitHub issue tracker or post to the Vault mailing list.