Skip to main content

setup

OpenBao Setup & Configuration

Step-by-step guide to configure OpenBao auto-unseal with DuoKey PKCS#11 library

Applies to:
OpenBaoPKCS#11 Auto-UnsealDuoKey CockpitCockpit-managed vault (AES-256)

Prerequisites​

Prerequisites

  • OpenBao installed and ready to configure
  • DuoKey Cockpit account with an OpenBao auto-unseal app created (this generates the pkcs11.toml, seal stanza, and a one-time access token)
  • DuoKey PKCS#11 library (libdke_pkcs11.so, provided by DuoKey) installed
  • An Active AES-256 key pre-created in any DuoKey Cockpit-managed vault (RSA keys are not currently supported for auto-unseal — CKM_AES_GCM only)
  • Network connectivity from OpenBao server to the DuoKey Cockpit (HTTPS/443)
Important
The encryption key used for auto-unseal must be created before configuring OpenBao. As stated in the OpenBao documentation, the key has to exist prior to initialization.
OpenBao 2.7+
Since OpenBao v2.6.0 the built-in openbao-hsm PKCS#11 distribution is deprecated, and it is removed entirely in v2.7.0 in favor of external KMS plugins. For new deployments on OpenBao 2.7+, ask DuoKey for the native OpenBao KMS plugin instead of the .so library — it talks to the same Cockpit endpoint and uses the same linked key, only the transport differs.

Setup Steps​

Create the Encryption Key

Create (or select) an Active AES-256 key in any DuoKey Cockpit-managed vault — this is the key OpenBao will use for sealing/unsealing

Deploy the Auto-Unseal App

In the DuoKey Cockpit, deploy an OpenBao auto-unseal app linked to that key. This generates the pkcs11.toml, the seal stanza, and a one-time access token

Install the PKCS#11 Library

Copy libdke_pkcs11.so (provided by DuoKey) to a known path, e.g., /usr/local/lib/pkcs11/

Place the Provider Configuration

Save the generated pkcs11.toml on the OpenBao server and point DKE_PKCS11_CONF at it

Configure OpenBao Seal Stanza

Add the generated PKCS#11 seal configuration to your OpenBao configuration file

Initialize or Restart OpenBao

Initialize OpenBao (first time) or restart it to use auto-unseal

Provider Configuration​

The DuoKey PKCS#11 library is configured with a pkcs11.toml file — generated when you deploy the auto-unseal app in the Cockpit — and a single environment variable pointing at it. Authentication uses a bearer access token presented in the request's Authorization header; the GUID embedded in the proxy URL is only a non-secret routing selector, not the credential itself. The access token is shown once at deployment time — re-deploy the app to rotate it. There is no OAuth2 client, no username/password, and no tenant or vault fields on the client side.

/etc/dke/pkcs11.toml
[http_config]
server_url   = "https://<cockpit-host>/api/apps/<app_id>/pkcs11/<endpoint_guid>"
access_token = "<access_token>"
timeout_secs = 30
verify_tls   = true

[pkcs11]
slot_id        = 0
logging_level  = "info"
logging_folder = "/var/log/dke-pkcs11"
# Point the library at its configuration before starting OpenBao
export DKE_PKCS11_CONF=/etc/dke/pkcs11.toml
Tip
For systemd-based deployments, add DKE_PKCS11_CONF to the OpenBao service environment file (e.g., /etc/openbao.d/openbao.env). Individual fields can also be overridden per host with DKE_PKCS11_* environment variables.

OpenBao Seal Configuration​

Add a seal "pkcs11" stanza to your OpenBao configuration file (e.g., /etc/openbao.d/openbao.hcl).

AES Key Configuration​

seal "pkcs11" {
  lib = "/usr/local/lib/pkcs11/libdke_pkcs11.so"
  slot = "0"
  pin = "1234"
  key_label = "bao-root-key-aes-256"
  mechanism = "0x1087"
}
ParameterDescription
libPath to the DuoKey PKCS#11 shared library
slotSlot ID — set to "0"
pinCan be any value (not currently validated by the library; the app is authenticated by the access token, not the PIN)
key_labelLabel of the AES-256 key created in DuoKey Cockpit
mechanism0x1087 = CKM_AES_GCM
Note
The slot value is the slot ID and can be set to "0". The pin can be any value as it is not currently validated by the library.
Important
Auto-unseal currently supports CKM_AES_GCM only, against an Active AES-256 key held in any DuoKey Cockpit-managed vault. RSA-OAEP is not yet supported by this integration (regardless of vault backend).

Verification​

After configuring OpenBao, verify the auto-unseal is working:

# Start or restart OpenBao
sudo systemctl restart openbao

# Check the seal status
bao status

If auto-unseal is configured correctly, the vault should report as unsealed automatically after startup.

# Expected output (key fields)
# Seal Type: pkcs11
# Initialized: true
# Sealed: false

Troubleshooting​

Tip
Enable debug logging (logging_level = "debug" in pkcs11.toml, or DKE_PKCS11_LOGGING_LEVEL=debug) during initial setup to help diagnose any issues, and check /var/log/dke-pkcs11/. Set it back to info for production use.

See Also