Auto Unseal OpenBao/Vault with the Transit Secrets Engine

In this tutorial, you'll learn how to unseal OpenBao and Vault automatically using the Transit secrets engine.

You'll walk through how to:

• Set up the Transit secrets engine
• Enable automatic unsealing using the Transit seal

Preparations

First, choose whether to use OpenBao or Vault. The included playground has both pre-installed.

Enter one of the following values:

• openbao
• vault

How it works

Automatic unsealing isn't fundamentally different from the manual unsealing process.

In the manual process, a set of unseal keys is required to reconstruct the root key (or master key). The root key is then used to decrypt the encryption key, which the service uses to access the underlying data.

With automatic unsealing, an external service manages the encryption of the root key, eliminating the need for unseal keys.

The service is configured for automatic unsealing via the seal stanza.

Both OpenBao and Vault support several unsealing mechanisms, including:

• Cloud KMS (AWS, GCP, Azure, etc.)
• PKCS#11 (HSM)
• Transit secrets engine (built-in "KMS")

In this tutorial, you'll use the Transit secrets engine for simplicity, though the setup is similar to other supported unsealing mechanisms.

You'll configure two instances of OpenBao/Vault:

• An unsealer (with the Transit secrets engine enabled) running in dev mode
• A standard installation of the service, configured for automatic unsealing

Configuring the unsealer

Since the unsealer runs in dev mode, you don't need to configure a storage backend or initialize it.

However, you'll still need to enable the Transit secrets engine so it can be used to unseal other instances.

To enable the secrets engine, switch to the unsealer and run the following command:

bao secrets enable transit

vault secrets enable transit

You'll also need to create a key in the new secrets engine for the unsealer to use when encrypting and decrypting the root key:

bao write -f transit/keys/unseal-key

vault write -f transit/keys/unseal-key

Configuring the service

The service that will be automatically unsealed is already configured to use the in-memory storage backend.

Switch to the playground and configure the unsealing process:

seal "transit" {
  address = "http://unsealer:8200"
  token   = "iximiuz"

  key_name   = "unseal-key"
  mount_path = "transit/"
}

sudo -u openbao $EDITOR /etc/openbao/config.d/seal.hcl

sudo systemctl restart openbao

seal "transit" {
  address = "http://unsealer:8200"
  token   = "iximiuz"

  key_name   = "unseal-key"
  mount_path = "transit/"
}

sudo -u vault $EDITOR /etc/vault.d/config.d/seal.hcl

sudo systemctl restart vault

As with any new instance, you'll need to initialize the service, but this time, the process will be slightly different.

In a typical initialization, a set of unseal keys is generated and used to reconstruct the root key during the unsealing process.

With auto unsealing enabled, unseal keys are no longer needed, since an external service manages the encryption of the root key. Instead, a set of recovery keys is created.

This is because the service can still be manually sealed, even with auto unsealing enabled (for example, as a protective measure to restrict access). In such cases, recovery keys are used to manually unseal the service.

To initialize the service, use the following command:

bao operator init -recovery-shares=1 -recovery-threshold=1

vault operator init -recovery-shares=1 -recovery-threshold=1

Once the initialization is complete, the service should be unsealed automatically.

Manual sealing

Let's test the manual sealing process.

Log in to the service using the root token received during initialization:

bao login

vault login

Seal the service:

bao operator seal

vault operator seal

You can verify the seal status by looking at the result of the status command:

bao status

vault status

Now, unseal the service using the recovery token received during initialization:

bao operator unseal

vault operator unseal

Summary

🎉 Congratulations!

You’ve learned how automatic unsealing works in OpenBao/Vault.

While this tutorial used the Transit secrets engine, the same concepts apply to other supported unsealing mechanisms. For more details, check out the References section below.

What's next?

There's still plenty more to explore:

• See the References section below to dive deeper into the topics covered
• Check out additional tutorials and challenges to expand your knowledge

If you want to test your knowledge or experiment further, check out these playgrounds:

• OpenBao
• Vault
• OpenBao vs Vault

References