seal stanza

The seal stanza configures an Auto Unseal mechanism, replacing the default Shamir seal. It allows the use of external solutions - such as an HSM or Cloud KMS - to encrypt and decrypt the root key. This stanza is optional, and if omitted, OpenBao will default to a Shamir seal, requiring manual unsealing of nodes.

info

Read more about seals in OpenBao on the concept page.

Configuration

Seal configuration can be done through the OpenBao configuration file using the seal stanza:

seal [NAME] {
  # ...
}

For example:

seal "pkcs11" {
  # ...
}

For configuration options which also read an environment variable, the environment variable will take precedence over values in the configuration file.

Plugins

Starting with OpenBao v2.6.0, Auto Unseal mechanisms not built into OpenBao may be installed as external KMS plugins via the plugin system.

warning

In OpenBao v2.7.0, many mechanisms that were previously built-in will not be included in the standalone binary anymore and remain available only as plugins. See the deprecation notice for details.

To get started, register a plugin of type kms via declarative plugin configuration along with the seal stanza:

plugin "kms" [NAME] {
  # ...
}

seal [NAME] {
  # ...
}

For example, to use the pkcs11 seal, you must install the pkcs11 KMS plugin:

plugin "kms" "pkcs11" {
  command = "openbao-plugin-kms-pkcs11"
  sha256sum = "..."
}

seal "pkcs11" {
  # ...
}

When using a plugin, the name to use in the seal stanza must match the name used in the plugin stanza, which is an arbitrary name. If a KMS provider is both built into OpenBao and installed as a plugin, the plugin will shadow the builtin and take priority.