Company

Enabling Cloud-based Auto Unseal in Vault Open Source

Feb 06 2019Christie Koehler

In December we announced Vault 1.0 and the availability of cloud auto unseal in Vault open source. This feature was previously available only to Vault Enterprise customers.

In this blog post we give a brief overview of how to enable cloud-based auto unseal in Vault open source. If you're already using Vault, you'll need to migrate to auto unseal, but don't worry, you can migrate back to manual unseal whenever you like. If you've been waiting to give open source Vault a try because of the hassle of unsealing, now's a good time!

»Why does Vault need to be unsealed?

When a Vault server is started, it begins in a sealed state. When sealed, Vault knows where and how to access the physical storage, but doesn't know how to decrypt any of it.

Unsealing is the process of constructing the master key necessary to read the decryption key to decrypt the data, allowing access to data in Vault. Prior to unsealing, the only possible Vault operations, aside from terminating the Vault server process, are unsealing the Vault and checking on the status of the unseal.

»Manual unseal

Vault is configured by default to use Shamir's Secret Sharing to split the master encryption key into shards. A certain threshold of shards is required to reconstruct the master key and unseal Vault data. The shards are added one at a time (in any order) until enough are present to reconstruct the master key and decrypt the data.

Diagram of manual unseal with shared keys

Once a Vault is unsealed, it remains so until one of two things happens:

It is resealed via the API or command line, or
The server is restarted.

This unseal process is done by running vault operator unseal or via the API. Typically, multiple operators are required to unseal Vault, each providing their part of the shared secret, as part of a manual process. Some organizations build tooling to automate or semi-automate this process using the Vault API or command line, but doing so in a secure and operationally sound manner is not trivial.

»Auto unseal

Auto unseal was developed to aid in reducing the operational complexity of unsealing Vault while keeping the master key secure. This feature delegates the responsibility of securing the master key from operators to a trusted device or service. Instead of only constructing the key in memory, the master key is encrypted with a cloud-based Key Management System (KMS) or an on-premises Hardware Security Module (HSM) and then stored in the storage backend allowing Vault to decrypt the master key at startup and unseal automatically. This eliminates the need for multiple operators or agents to provide parts of the shared key in either a manual or custom-built automated process.

Diagram of cloud-based auto unseal

Auto unseal using a cloud-based KMS is available in the open source version as of Vault 1.0. Auto unseal with a HSM remains a Vault Enterprise feature.

When using auto unseal, there are certain operations in Vault that still require a quorum of users to perform, such as generating a root token. During the initialization process a set of Shamir keys are generated that are called Recovery Keys and are used for these operations.

To enable cloud-based auto unseal, you'll need set up a KMS on one of the supported cloud providers and generate access tokens for it.

Next, you'll configure Vault using the seal stanza or by providing certain environmental variables such as VAULT_SEAL_TYPE.

Here's a sample configuration for AWS KMS:

seal "awskms" {
  region     = "us-east-1"
  access_key = "AKIAIOSFODNN7EXAMPLE"
  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
  endpoint   = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com"
}

Note: We don’t recommend storing credentials such as access_key and secret_key in Vault configuration files. These can also be supplied environment variables or as part of the AWS profile from the AWS CLI or instance profile.

See the documentation for each supported provider for details:

AWS KMS (documentation, tutorial)
Azure Key Vault (documentation, tutorial)
Google Cloud KMS (documentation, tutorial)
AliCloud KMS (documentation)

»Migration to auto unseal

If you're already running Vault open source and it's configured for manual unseal, you'll need to migrate to auto unseal.

An overview of the migration process is:

take Vault cluster offline
update seal configuration
bring cluster back up
run unseal process with -migrate flag

When the unseal process is complete, unseal keys will be migrated to recovery keys and auto unseal will be enabled. You can migrate back at any time by repeating the process above after adding disabled = true to the seal stanza in Vault's configuration.

See our migration documentation for complete details.

Note for Enterprise Vault users: Migration from auto unseal back to manual unseal is not yet supported for installations where seal wrap is enabled.