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.

Health Checks

When using an Auto Seal, OpenBao periodically performs a seal health check, encrypting and decrypting a small, randomized payload via the seal mechanism. When the health check fails, OpenBao emits warnings to the server logs, notifying operators of a broken Auto Seal early before it is next required to unseal the instance again.

The following seal stanza options allow tweaking the health check. This is primarily useful when the chosen plugin does not play well with the defaults.

• health_check_enabled (bool: true) - Enable/disable the periodic health check.
• health_check_timeout (duration: "1m") - The timeout that a single health check operation is constrained to.
• health_check_interval (duration: "10m") - The interval that health checks run at under normal circumstances.
• health_check_interval_unhealthy (duration: "1m") - The interval that health checks start running at after a failed health check. On the next successful health check, the interval resets back to health_check_interval.

The above options use duration format strings to configure durations.