These tests assume OpenBao is already installed, configured, and initialized as described in Configure OpenBao with the Futurex PKCS #11 library. Run all tests as a user with sudo privileges.
Prerequisites
Before you run any tests, set the following environment variables in your terminal. These assume a configuration similar to the one described in Configure OpenBao with the Futurex PKCS #11 library. You need these for every test on this page. Replace<NODE_IP> and <ROOT_TOKEN> with your values, and use https:// only if you enabled TLS on the listener.
Shell
Shell
The output shows
Initialized true and Sealed false before you run any tests.secret/ path. A new OpenBao installation doesn’t have one. If bao secrets list doesn’t show secret/, enable it:
Shell
Test 1: HSM auto-unseal on restart
This test confirms that the HSM performs the unseal operation automatically on startup, without manual intervention.1
Restart the OpenBao service.
Shell
2
Wait for OpenBao to start, then check its status.
Shell
The HSM unseals OpenBao automatically, with no manual intervention required.
Test 2: Auto-unseal after a reboot
This test confirms that OpenBao unseals automatically after the computer restarts. It depends on the start delay drop-in described in Configure OpenBao with the Futurex PKCS #11 library.1
Restart the computer:
Shell
2
After the computer has been up for at least two minutes, log in, set
BAO_ADDR again, and check the status:Shell
The output shows
Sealed false.Test 3: HSM network failure and recovery
This test blocks network access to the HSM and confirms that OpenBao cannot unseal without it, then restores connectivity and confirms recovery.Part A: Simulate an HSM network failure
1
Block network access to the HSM. Replace
<HSM_IP> with the HSM IP address.Shell
2
Verify that the HSM is unreachable.
Shell
An error similar to the following indicates that the HSM cannot be reached.
3
Restart OpenBao. It should fail to unseal without HSM access.
Even though access to the HSM is lost, OpenBao remains unsealed until it is restarted. OpenBao only needs to contact the HSM during the unseal process at startup. Once unsealed, it does not maintain a constant connection to the HSM.
Shell
OpenBao can’t start, because it can’t unseal without access to the HSM. The restart command reports that the job failed, and The service keeps retrying every few seconds, so
bao status can’t connect:systemctl status openbao shows it as activating.Part B: Restore HSM connectivity and recover
1
Restore network access to the HSM. Replace
<HSM_IP> with the HSM IP address.Shell
2
Verify that connectivity to the HSM is restored.
Shell
The program returns information about the HSM configuration, which confirms that connectivity is restored.
3
Restart OpenBao and confirm that it auto-unseals through the HSM.
Shell
Test 4: HSM seal key rotation
This test validates that OpenBao can rotate the HSM seal key by pointing to a new key label on the HSM. It confirms that new encryptions use the updated key while existing data remains accessible through the original key.This test is distinct from barrier encryption key rotation (
bao operator rotate). There are two separate key rotation operations in OpenBao:- HSM seal key rotation rotates the key on the HSM that wraps the root key. It is controlled by
key_labelinopenbao.hcl. - Barrier key rotation (
bao operator rotate) rotates the internal AES encryption key that OpenBao uses to encrypt data at rest.
1
Write a test secret under the current HSM key (Confirm that the secret is readable before you proceed.
bao_seal_rsa) to verify that it remains accessible after rotation.Shell
Shell
2
Check the current barrier key version before rotation. Note the
term value. You verify that it increments after barrier rotation.Shell
3
Generate a new RSA key pair on the Excrypt HSM with a new label.Verify that both key pairs are present on the HSM before you proceed.
Shell
Shell
Both the original and new key labels are listed.
4
Update the
key_label value in /etc/openbao/openbao.hcl to point to the new key. The file is readable only by the openbao user, so edit it with sudo, for example sudo nano /etc/openbao/openbao.hcl./etc/openbao/openbao.hcl
The PIN remains in the
BAO_HSM_PIN environment variable and is not added to the HCL file.5
Restart OpenBao to pick up the new key label.
Shell
OpenBao auto-unseals successfully.
6
Confirm the auto-rewrap in the OpenBao logs. This confirms that OpenBao detected the key label change and re-wrapped the stored keys under the new HSM key.
Shell
Both lines must be present to confirm a successful rewrap.
7
Write a new secret after rotation to confirm that new encryptions use the new key label.
Shell
8
Inspect the Raft storage again to confirm that entries for the new key label appear alongside the original.
Shell
Both key labels now appear in Raft. The original key label entries represent existing data that still requires the original key for decryption. The new key label entries represent the rewrapped root key and any new encryptions.
9
Rotate the barrier encryption key. This rotates the internal encryption key that OpenBao uses to encrypt data at rest and re-wraps it under the new HSM key.The
Shell
term value incremented, which confirms that the barrier key rotation completed successfully.10
Confirm that both pre-rotation and post-rotation data is still accessible after the full rotation cycle.
Shell
Both secrets return their original values, which confirms that data written under the original key remains accessible and data written under the new key is also readable.