Securosys External Keys Plugin Installation

This guide describes how to set up OpenBao instances to use "external keys" that are backed by a Primus HSM. Primus HSM is accessed through the REST API provided by the Transaction Security Broker (TSB).

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.7.0 (or later) because it uses the new external keys feature.

Step 1: 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 REST auto-unseal.

Next Steps

Continue with the tutorial to learn how to register partitions and keys with OpenBao.