Configure OpenBao with the Futurex PKCS #11 library

This page configures the OpenBao service that the openbao-hsm package installed to use the Futurex PKCS #11 library for HSM auto-unseal. OpenBao seals its root key with an RSA key pair on the Excrypt HSM by using the CKM_RSA_PKCS_OAEP mechanism. The OpenBao configuration on this page is an example to help you get started. Adjust it for your environment, security requirements, and operational preferences, such as TLS and audit logging. Always review and align settings with your organization’s security policies.

Use an RSA seal key with this integration. The AES-GCM seal mechanism (CKM_AES_GCM) doesn’t work with the Futurex PKCS #11 library, because OpenBao and the library handle the GCM initialization vector differently.

Create the seal key

Create an RSA key pair on the HSM. OpenBao uses the public key to encrypt its root key and the private key to decrypt it at startup. Use the OpenSC pkcs11-tool, or the Futurex PKCS11Manager program.

If pkcs11-tool isn’t installed, install the OpenSC package, for example on Debian or Ubuntu:

Shell

sudo apt install opensc

Generate a 2048-bit RSA key pair. Enter the identity password when prompted. Choose any label; you use it again in the OpenBao configuration:

Shell

pkcs11-tool --module /usr/local/lib/fxpkcs11/libfxpkcs11.so --login --keypairgen --key-type RSA:2048 --label bao_seal_rsa --usage-decrypt

HSM key labels can contain only letters, digits, and underscores.

Verify that the key pair exists:

Shell

pkcs11-tool --module /usr/local/lib/fxpkcs11/libfxpkcs11.so --login --list-objects --type privkey

The output lists a private key object with the label that you chose.

Give the openbao user access

The OpenBao service runs as the openbao user, which must be able to read the library and its configuration file.

Verify that the openbao user can read libfxpkcs11.so and fxpkcs11.cfg:

Shell

sudo -u openbao ls -la /usr/local/lib/fxpkcs11/libfxpkcs11.so
sudo -u openbao cat /etc/fxpkcs11.cfg

Each command returns the file details or contents without a permission-denied error.

If you use mutual authentication, make the TLS client key readable by the openbao user, for example:

Shell

sudo chown root:openbao /etc/fxpkcs11/tls/PKI.p12
sudo chmod 640 /etc/fxpkcs11/tls/PKI.p12

If fxpkcs11.cfg sets a <LOG-FILE>, create the file and give it to the openbao user. Adjust the path to match your configuration:

Shell

sudo touch /var/log/openbao_fxpkcs11.log
sudo chown openbao:openbao /var/log/openbao_fxpkcs11.log
sudo chmod 640 /var/log/openbao_fxpkcs11.log

Set the HSM PIN

OpenBao reads the identity password from the BAO_HSM_PIN environment variable. The service loads it from /etc/openbao/openbao.env.

Add the PIN to the environment file. Replace [identity_password] with the password of the identity that you created for OpenBao:

Shell

echo 'BAO_HSM_PIN=[identity_password]' | sudo tee /etc/openbao/openbao.env > /dev/null

If fxpkcs11.cfg isn’t at /etc/fxpkcs11.cfg, also add FXPKCS11_CFG=[path_to_cfg] to this file.

Restrict the file so that only root and the openbao group can read it:

Shell

sudo chown root:openbao /etc/openbao/openbao.env
sudo chmod 640 /etc/openbao/openbao.env

Configure OpenBao settings

Replace the contents of /etc/openbao/openbao.hcl with the following configuration. Replace [server_address] with the address of the OpenBao server and bao_seal_rsa with the label of your seal key.

This example disables TLS on the listener for simplicity, so api_addr uses HTTP. Before you deploy to production, enable TLS in the listener stanza (the package generated a self-signed certificate in /opt/openbao/tls) and update api_addr to use https://. For multi-node Raft deployments, add node_id to the storage stanza.

/etc/openbao/openbao.hcl

storage "raft" {
  path = "/opt/openbao/data"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

seal "pkcs11" {
  lib       = "/usr/local/lib/fxpkcs11/libfxpkcs11.so"
  slot      = "0"
  key_label = "bao_seal_rsa"
  mechanism = "CKM_RSA_PKCS_OAEP"
}

api_addr     = "http://[server_address]:8200"
cluster_addr = "http://[server_address]:8201"
ui           = true

The seal stanza defines the following parameters:

Parameter	Description
lib	Path to the Futurex PKCS #11 library. The `openbao` user must be able to read it.
slot	The slot number. Set it to `0`, the slot that `fxpkcs11.cfg` defines.
key_label	The label of the RSA key pair that you created.
mechanism	Set it to `CKM_RSA_PKCS_OAEP`.

The configuration file doesn’t contain the PIN. OpenBao reads it from the BAO_HSM_PIN environment variable.

Make the configuration file readable by the openbao user:

Shell

sudo chown openbao:openbao /etc/openbao/openbao.hcl
sudo chmod 640 /etc/openbao/openbao.hcl

Start the OpenBao server

Delay the OpenBao service at system startup. With the Futurex PKCS #11 library, OpenBao can fail to auto-unseal when it starts in the first minute after the computer boots: it stays sealed and logs CKR_OBJECT_HANDLE_INVALID. Starting it later avoids the problem.Create a systemd drop-in file:

Shell

sudo mkdir -p /etc/systemd/system/openbao.service.d
sudo tee /etc/systemd/system/openbao.service.d/10-hsm-start-delay.conf > /dev/null <<'EOF'
[Service]
ExecStartPre=/bin/sh -c 'u=$$(cut -d. -f1 /proc/uptime); [ $$u -ge 90 ] || sleep $$((90 - u))'
TimeoutStartSec=180
EOF
sudo systemctl daemon-reload

The drop-in waits until the computer has been up for 90 seconds. It doesn’t delay a restart of the service after that.

Enable and start the OpenBao service:

Shell

sudo systemctl enable --now openbao

Check the service status:

Shell

sudo systemctl status openbao

The service is active (running). Until you initialize OpenBao, the log repeats stored unseal keys are supported, but none were found: is the server initialized? every few seconds. That’s expected.

Initialize OpenBao

Set the OpenBao address. Replace [server_address] with the address of the OpenBao server:

Shell

export BAO_ADDR="http://[server_address]:8200"

Check the OpenBao status:

Shell

bao status

The output shows Seal Type pkcs11, Initialized false, and Sealed true.

Initialize OpenBao:

Shell

bao operator init

The output lists five recovery keys and an initial root token, and ends with the following lines. OpenBao 2.6 still prints “Vault” in this message:

Success! Vault is initialized

Recovery key initialized with 5 key shares and a key threshold of 3. Please
securely distribute the key shares printed above.

Save the recovery keys and the root token immediately. You can’t retrieve them again. Because the HSM unseals OpenBao automatically, you need the recovery keys only for privileged operations, such as generating a new root token. They can’t unseal OpenBao if the HSM is unavailable.

Verify that OpenBao is unsealed:

Shell

bao status

The output shows Initialized true and Sealed false.

Troubleshooting

The service doesn’t start or OpenBao stays sealed

Check the service log first:

Shell

sudo journalctl -u openbao -b

Then use the following table:

Log message	Cause and fix
`CKR_PIN_INCORRECT`	`BAO_HSM_PIN` in `/etc/openbao/openbao.env` doesn’t match the identity password. Correct it and restart the service.
`CKR_OBJECT_HANDLE_INVALID`, and OpenBao stays sealed after the computer boots	OpenBao started too soon after boot. Check that the start delay drop-in from Start the OpenBao server exists, then run `sudo systemctl restart openbao`.
`Permission denied` when OpenBao loads the library	The `openbao` user can’t read `libfxpkcs11.so`, `fxpkcs11.cfg`, or the TLS client key. Check the permissions as described in Give the openbao user access.
`stored unseal keys are supported, but none were found`	OpenBao isn’t initialized yet. Run `bao operator init`.

For any other library error, enable traffic logging in fxpkcs11.cfg, restart the service, and check the log file for ERROR lines. See Edit the Futurex PKCS #11 configuration file.

The seal key was replaced

If you delete or replace the seal key on the HSM after initialization, OpenBao can no longer decrypt its root key and stays sealed. Restore the original key from an HSM backup. To change the seal key without losing data, follow the key rotation procedure in Test OpenBao with a Futurex HSM.

Overview

Certificate Authority

Certificate management

Certificate validation

Code signing

Credential management

Data protection

Database

Digital signing

DNS

Firewall

Generic

IT automation and orchestration

Key management

Privileged access management

Secrets management

TLS offloading

VPN

Configure OpenBao with the Futurex PKCS #11 library

Create the seal key

Give the openbao user access

Set the HSM PIN

Configure OpenBao settings

Start the OpenBao server

Initialize OpenBao

Troubleshooting

The service doesn’t start or OpenBao stays sealed

The seal key was replaced

​Create the seal key

​Give the openbao user access

​Set the HSM PIN

​Configure OpenBao settings

​Start the OpenBao server

​Initialize OpenBao

​Troubleshooting

​The service doesn’t start or OpenBao stays sealed

​The seal key was replaced

Create the seal key

Give the openbao user access

Set the HSM PIN

Configure OpenBao settings

Start the OpenBao server

Initialize OpenBao

Troubleshooting

The service doesn’t start or OpenBao stays sealed

The seal key was replaced