Securosys Secrets Engine Installation

This guide describes how to install the Securosys Secrets Engine. The engine is deployed as an OpenBao plugin and communicates with Primus HSM through the 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 should be a fully initialized and unsealed installation.
- See the OpenBao installation guide for instructions.

info

This guide requires OpenBao 2.5.0 (or later) because it uses declarative plugin registration. Older versions should work, too. However, you will need to register the plugin via the API.

Step 1: Get the plugin

Clone the GitHub repository of the plugin:

git clone https://github.com/securosys-com/openbao-plugin-secrets-engine.git

Compile the plugin. This requires Go to be installed.

# replace with the current plugin version
export VERSION=1.3.0

cd openbao-plugin-secrets-engine

go build -o secret-securosys-${VERSION} cmd/securosys-hsm/main.go

Calculate the SHA-256 digest of the plugin binary:

sha256sum secret-securosys-${VERSION}

Create the plugin directory and move the binary there. Lock down the filesystem permissions. When using containers, mount the plugin directory as a volume.

mkdir -p /opt/openbao/plugins
install -m 0755 secret-securosys-${VERSION} /opt/openbao/plugins/secret-securosys-${VERSION}
chown -R openbao:openbao /opt/openbao/plugins

Step 2: Configure the plugin

Declare the plugin in your openbao.hcl to let OpenBao know about it.

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

plugin "secret" "securosys" {
  command     = "secret-securosys-1.3.0"
  version     = "v1.3.0"
  sha256sum   = "96cd8e008d266a91b5fc78a61ec2a5edee4ad68e59df6c2b8b9b08495f53a843"
}

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

Restart OpenBao or send a SIGHUP so that it reloads the configuration file. Upon reload, OpenBao will auto-register the plugin.

Check that the plugin is available:

$ bao plugin list

Name                            Type        Version
----                            ----        -------
securosys                       secret      v1.3.0

If the list is empty, you may need to authenticate first:

bao login

Step 3: Enable the secrets engine

Enable the secrets engine at a path of your choice.

The example below uses path securosys-prod for the following reasons:

Distinguishes the path (securosys-prod) from the engine name (securosys) in subsequent examples.
Future-proof, in case you want to mount multiple plugin instances at different paths for multi-tenancy.

$ bao secrets enable -description "keystore backed by Primus HSM" -path=securosys-prod securosys

Success! Enabled the securosys secrets engine at: securosys-prod/

The engine should now appear in the list of enabled engine:

$ bao secrets list

Path             Type         Accessor              Description
----             ----         --------              -----------
cubbyhole/       cubbyhole    cubbyhole_9443c13f    per-token private secret storage
identity/        identity     identity_2ca5bc52     identity store
securosys-prod/  securosys    securosys_5c6bd7fa    keystore backed by Primus HSM
sys/             system       system_d60493b4       system endpoints used for control, policy and debugging

Step 4: Configure the secrets engine

Configuring the plugin is done through API requests to a running OpenBao server and writing to the plugin storage at <mount_path>/config.

Option 1: Use the bao binary:

bao write securosys-prod/config {config_attributes}

Option 2: Use a tool like curl to make HTTP requests:

curl --location --request PUT 'https://bao.example.com/v1/securosys-prod/config' \
  --header 'X-Vault-Token: <access_token>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode '<config_attribute_key>=<config_attribute_value>'

The Securosys Secrets Engine exposes the following configuration options:

Key	Value example	Value description
`auth`	`TOKEN`	Authorization type for the TSB. One of: `TOKEN`, `CERT`, `NONE`.
`restapi`	`https://sbx-rest-api.cloudshsm.com/`	REST API URL of the TSB.
`bearertoken`	`abcdef`	JWT string. Use together with `auth=TOKEN`.
`certpath`	`/path/to/client.crt`	Absolute path on the OpenBao host to the mTLS client certificate. Use together with `auth=CERT`.
`keypath`	`/path/to/client.key`	Absolute path on the OpenBao host to the mTLS client key. Use together with `auth=CERT`.
`applicationKeyPair`	`{\"privateKey\":\"MIIEvgIBADANBg...\",\"publicKey\":\"MIIBIjANBgkqh...\"}`	Optional application key pair for request signatures. Provide `private_key` and `public_key` without PEM headers.
`apiKeys`	`{\"KeyManagementToken\":[\"token_key_management1\",\"token_key_management2\",\"token_key_management3\" ...],\"KeyOperationToken\":[\token_key_operation\"],\"ServiceToken\":[\"token_service\"]}`	API keys to access the TSB. `KeyManagementToken` is needed for key create/list/destroy. `KeyOperationToken` is needed for encrypt/decrypt/sign/etc. `ServiceToken` is needed for health checks.

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

info

Always provide a full set of configuration options (not just a subset).

On every configuration change, the plugin tries to connect to the TSB using the updated configuration. If the connection was successful, the plugin will (over)write the configuration with the new values. Otherwise, the previous configuration remains unchanged.

Examples

Below are some examples showing how to configure the plugin with the different authentication options.

JWT
mTLS
No Auth

bao write securosys-prod/config auth="TOKEN" bearertoken="jwt_string" restapi="https://sbx-rest-api.cloudshsm.com"

bao write securosys-prod/config auth="CERT" certpath="local_absolute_path_to_certificate.pem" keypath="local_absolute_path_to_private.key" restapi="https://sbx-rest-api.cloudshsm.com"

You need to place/mount the client certificate and client key and the configured paths, so that the plugin can read these files.

bao write securosys-prod/config auth="NONE" restapi="https://sbx-rest-api.cloudshsm.com"

Confirm Working

Run the health check, to verify that the plugin can log in to the Partition:

$ bao read securosys-prod/health

Key       Value
---       -----
result    Connection successful: {"keyStoreStatistics":"user PARTITION_NAME, private keys 39, public keys 39, secret keys 17, certificates 11, data objects 14, invalidated keys 882, used size 3820544 bytes, max size 3359637504 bytes"}

List the current config:

$ bao read securosys-prod/config

Key         Value
---         -----
auth        TOKEN
certpath    n/a
restapi     https://sbx-rest-api.cloudshsm.com
username    n/a

info

This only returns public values. Sensitive values (such as the JWT are not returned).

To test that you can manage keys, "register" a key that already exists on the Partition in the secrets engine:

bao write securosys-prod/keys/timestamp-key/register keyLabel=timestamp-key

Once registered, you should see the key:

$ bao read securosys-prod/keys/timestamp-key

Key                   Value
---                   -----
algorithm             EC
algorithmOid          1.2.840.10045.2.1
attestationKeyName    attestation-key
attributes            map[alwaysSensitive:false copyable:true decrypt:true derive:true destroyable:true ekaSign:true extractable:false modifiable:true neverExtractable:true rollover:false sensitive:false sign:true unwrap:true]
baseLabel             timestamp-key
created               map[aliases:<nil> date:0001-01-01T00:00:00Z id:root name:root]
curveOid              1.3.132.0.10
keyLabel              timestamp-key
policy                map[ruleUse:map[tokens:<nil>]]
publicKey             MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE6P7NF/YhBLojCfw+AQJWUE0V0fQiD7N/VZwQSiKqzUPAvwUF857AvokPkwU/ldU5ezfqurzF/g31DQ5cZTjNVQ==
updated               map[aliases:<nil> date:0001-01-01T00:00:00Z id:root name:root]
version               v1

$ bao list -detailed securosys-prod/keys

Keys             Algorithm    Blocked    Created    KeyLabel         KeySize/CurveOid    Updated    Version    WithPolicy
----             ---------    -------    -------    --------         ----------------    -------    -------    ----------
aes-128          AES          no         root       aes-128          128                 root       v1         no
timestamp-key    EC           no         root       timestamp-key    1.3.132.0.10        root       v1         no

tip

The secrets engine plugin does not automatically discover the keys on the HSM Partition. You need to manually register these keys. Keys created or imported by the plugin are automatically registered.

Multi-tenancy

A single secrets engine plugin instance can only connect to a single HSM Partition. To achieve multi-tenancy and connect to multiple HSM Partitions, mount the engine multiple times at different paths.

Enable the secrets engine, mounting it at a custom path:

bao secrets enable -path=securosys-dev securosys

Afterwards, access the secrets engine at this path. This engine has its own storage space, and can be configured with different settings.

bao write securosys-dev/config auth="NONE" restapi="https://primusdev.cloudshsm.com"

Upgrading

See the OpenBao plugin upgrade guide for how to upgrade secrets engine plugins.

View Help

To view the help and a list of all available paths, run:

bao path-help securosys-prod

Tutorial

See the README on GitHub for a full list of available features and how to use them.

Get started withCloudHSM for free.

Need help?Contact Support.

Other questions?Ask Sales.

Prerequisites​

Step 1: Get the plugin​

Step 2: Configure the plugin​

Step 3: Enable the secrets engine​

Step 4: Configure the secrets engine​

Examples​

Confirm Working​

Multi-tenancy​

Upgrading​

View Help​

Tutorial​

Prerequisites

Step 1: Get the plugin

Step 2: Configure the plugin

Step 3: Enable the secrets engine

Step 4: Configure the secrets engine

Examples

Confirm Working

Multi-tenancy

Upgrading

View Help

Tutorial