HashiCorp Vault 0.3

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 cubbyhole 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.

READMORE

»SSH Backend

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.

Vault's 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 username@x.x.x.x
    username@ip:~$

The 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 Backend

The new Vault 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 accessible.

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:

1. A process responsible for creating Vault authentication tokens creates two tokens: a permanent (perm) token and a temporary (temp) token. The perm token contains the final set of policies desired for the application in the container. The temp token has a lease duration of 15 seconds and a maximum use count of 2.
2. The temp token is used to write the perm token into the cubbyhole storage specific to temp. This requires a single write operation, reducing the remaining uses of temp to one.
3. The invoked process gives the temp token to the container management engine, which starts the container and injects the temp token value into the container environment.
4. The application inside the container reads the temp token from the container environment and uses it to fetch the perm token from the cubbyhole. This read operation exhausts the temp token's use limit, the temp token is revoked, and its cubbyhole is destroyed.
5. If the application is unable to use the temp token, 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.

»Flexible TTLs

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: mount-tune, along with additional output to the mounts command:

    $ 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

A 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

The generic backend 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.

In 0.3, 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 result.

»Duo Multi-Factor Authentication Support

For supporting auth backends (currently ldap and userpass), Vault's mfa auth support can now use Duo. See the mfa documentation for details.

»Upgrade Details

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-Token header 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 generic, token, and pki backends, but you should migrate to using "ttl" for these; in 0.4 only "ttl" will be supported. Other backends will migrate in future releases.

»Roadmap

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 pki backend, 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 tls authentication 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.