Skip to main content

Auto-Unseal with REST

This guide describes how to set up auto-unsealing of an OpenBao instances with Primus HSM through REST.

Architecture diagram of REST auto-unsealing architecture

Prerequisites​

  • A Securosys Primus HSM or CloudHSM.
  • A Securosys TSB installation.
    • In CloudHSM, Securosys hosts the TSB for you.
    • For on-premise HSMs, follow the TSB installation guide.
    • You need: TSB URL/IP, access credentials (depending on the TSB configuration: JWT, API keys, mTLS key/cert)
  • An OpenBao installation.
    • This can be an existing installation (to be migrated to auto-unsealing) or a fresh, uninitialized installation.
    • See the OpenBao installation guide for instructions.
info

This guide requires OpenBao 2.6.0 (or later) because it uses the new kms plugin type.

Step 1: Create a key in the HSM​

Create the unseal key on the HSM using the POST /v1/key endpoint.

You have to choose:

  1. Which encryption algorithm?
  2. SKA key or normal key?
    • You cannot "upgrade" a normal key to SKA later. You will need to generate a new key and migrate the seal to the new key.
    • You can generate an SKA key with an empty policy (that allows everything). This allows you to start with the behaviour of a normal key and add a meaningful policy later.

The following algorithms are supported:

  • AES-GCM
  • RSA-OAEP-SHA-256
  • ML-KEM-512, ML-KEM-768, ML-KEM-1024

For more details, please see:

export JWT="changeme"
curl -L "https://sbx-rest-api.cloudshsm.com/v1/key" \
-H "Authorization: Bearer $JWT" \
--json '{
"label": "bao-root-key-aes",
"algorithm": "AES",
"keySize": 256,
"attributes": {
"encrypt": true,
"decrypt": true,
"verify": true,
"sign": true,
"wrap": true,
"unwrap": true,
"extractable": false,
"modifiable": true,
"destroyable": false,
"sensitive": true,
"copyable": false,
"rollover": false
},
"policy": null
}'
danger

If you lose this key, you will not be able to unseal your OpenBao instance, and will thus lose your OpenBao data. Make sure that you have a backup of your HSM Partition.

The command above sets destroyable=false, which prevents the key from being deleted via the API. When set, the only way to delete this key is to delete the entire Partition.

If you don't set destroyable=false, you should enable Key Invalidation in your Partition.

Step 2: Configure the kms-securosys plugin​

Make sure that the plugin_directory exists on your machine. When using containers, make sure this directory is persisted as a volume mount.

mkdir -p /opt/openbao/plugins

Next, install the kms-securosys plugin. This plugin is maintained by Securosys and upstreamed to the OpenBao community.

The simplest installation option is to declare the following in your openbao.hcl. This causes OpenBao to automatically download the plugin when OpenBao (re)starts. The releases and their SHA-256 digests can be found in the openbao-plugin repository.

plugin_directory = "/opt/openbao/plugins"
plugin_auto_download = true

plugin "kms" "securosys" {
image = "ghcr.io/openbao/openbao-plugin-kms-securosys:v0.0.2@sha256:abac0a8a5c51fc45271f8ff9fb4950154aefe99edc913e4ebb6725418280a15f"
}

See the OpenBao plugin system and the plugin stanza documentation for more information about plugin installation.

Alternatively, you can compile the plugin from source.

info

This is the same plugin as for external keys.

Step 3: Configure the securosys seal​

Define the securosys seal in the OpenBao configuration.

Here is a minimal example:

seal "securosys" {
key_label = "bao-root-key-mlkem-ska"
tsb_api_endpoint = "https://sbx-rest-api.cloudshsm.com/"
auth = "TOKEN"
bearer_token = "changeme_jwt_value"

# Disable health check to avoid recurring SKA approval requests
health_check_enabled = false
}

For all available options, please see the plugin reference.

For more information on mTLS, API keys, and request signatures, see the TSB authorization documentation.

Step 4: Initialize OpenBao​

Finally, (re-)start OpenBao so that it picks up the configuration changes.

Then initialize OpenBao to create the seal:

bao operator init

This returns:

Recovery Key 1: mQA3ASf8P/9S...
Recovery Key 2: Q9pYb3Ge+9a6...
Recovery Key 3: vRt0uHy1ms0e...
Recovery Key 4: IBL3zUtDe+kj...
Recovery Key 5: UK9GSdqpzXEy...

Initial Root Token: s.dCmfe4zmwxmsEE...

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.
warning

Securely note down the recovery keys and the root token!

tip

If your instance is already initialized with another seal, follow the seal migration guide to migrate to the REST seal.

Confirm Working Auto-Unsealing​

To test that auto-unseal is working, restart OpenBao.

If you used an SKA key with a policy that contains some approvers, the TSB will collect the approvals and eventually forwards the request to the HSM. The securosys plugin polls the TSB, waiting for the result.

Once the unseal succeeds, you should see the following in the OpenBao logs ("stored unseal key"):

systemd[1]: Started openbao.service - "OpenBao - A tool for managing secrets".
bao[154960]: 2026-07-31T10:59:30.458+0200 [INFO] core: stored unseal keys supported, attempting fetch
bao[154960]: 2026-07-31T10:59:30.597+0200 [INFO] core.cluster-listener.tcp: starting listener: listener_address=0.0.0.0:8201
bao[154960]: 2026-07-31T10:59:30.599+0200 [INFO] core.cluster-listener: serving cluster requests: cluster_listen_address=[::]:8201
bao[154960]: 2026-07-31T10:59:30.600+0200 [INFO] core: post-unseal setup starting
bao[154960]: 2026-07-31T10:59:30.606+0200 [INFO] core: loaded wrapping token key
bao[154960]: 2026-07-31T10:59:30.606+0200 [INFO] core: upgrading plugin information: plugins=[]
bao[154960]: 2026-07-31T10:59:30.606+0200 [INFO] core: successfully setup plugin catalog: plugin-directory=/opt/openbao/plugins
bao[154960]: 2026-07-31T10:59:30.606+0200 [INFO] core.plugins: starting declarative plugin registration
bao[154960]: 2026-07-31T10:59:30.610+0200 [INFO] core.plugins: declarative plugin registration completed
bao[154960]: 2026-07-31T10:59:30.816+0200 [INFO] core: post-unseal setup complete
bao[154960]: 2026-07-31T10:59:30.816+0200 [INFO] core: vault is unsealed
bao[154960]: 2026-07-31T10:59:30.816+0200 [INFO] core: unsealed with stored key

Additionally, bao status should show:

$ bao status
Key Value
--- -----
Seal Type securosys-hsm
Recovery Seal Type shamir
Initialized true
Sealed false
Total Recovery Shares 5
Threshold 3
Version 2.6.1
Commit Date 2026-07-22T14:22:20Z
Storage Type file
Cluster Name vault-cluster-38522aac
Cluster ID cee4e2e1-c4ba-616b-88f7-4d12ac69e6a8
HA Enabled false

References​

Get startedwith CloudHSM.
Other questions?Ask Sales.
Feedback
Need help?