External Keys Tutorial
In this tutorial you will learn how to use keys stored inside a Primus HSM as external keys in an OpenBao instance.
References
- For full details on the OpenBao API endpoints, please see the API documentation.
- For all available config options of the Securosys plugin, please see the plugin reference.
Manage external keys config
Add a config to OpenBao for your specific TSB instance and HSM Partition. All external keys registered under this config will be backed by the same Primus HSM Partition.
Create a new config entry:
# JWT
bao write sys/external-keys/configs/securosys-PARTITION \
plugin=securosys rest_api=https://sbx-rest-api.cloudshsm.com auth=TOKEN bearer_token="$JWT"
# mTLS
bao write sys/external-keys/configs/securosys-PARTITION \
plugin=securosys rest_api=https://sbx-rest-api.cloudshsm.com auth=CERT cert_pem=@/path/to/client.crt key_pem=@/path/to/client.key
Create one config per HSM Partition. This enables multi-tenancy, because you can add keys from multiple Partitions to OpenBao under their respective config. Later, you can easily see from the path name which Partition a key belongs to.
List the available configs:
bao list sys/external-keys/configs
Keys
----
securosys-PARTITION
Read the content of a config:
bao read sys/external-keys/configs/securosys-PARTITION
Key Value
--- -----
auth TOKEN
bearer_token (redacted)
plugin securosys
rest_api https://sbx-rest-api.cloudshsm.com
Manage external keys
External keys are registered as objects in OpenBao. They are merely a placeholder reference that points to an object inside the HSM.
OpenBao does not create keys on the HSM. Any key that you register must already exist on the HSM. You can create a key for example via the web interface of CyberVault KMS or via the TSB REST API.
List the registered external keys:
bao list sys/external-keys/configs/securosys-PARTITION/keys
Register a key with OpenBao:
bao write sys/external-keys/configs/securosys-PARTITION/keys/my-key-label name=my-key-label
Read the details of a key:
bao read sys/external-keys/configs/securosys-PARTITION/keys/my-key-label
Manage grants
Grants are used to selectively allow secrets engines and auth engines access to an external key.
List the current grants for a key:
bao list sys/external-keys/configs/securosys-PARTITION/keys/my-key-label/grants
Create a new grant, allowing the PKI engine access:
bao write -force sys/external-keys/configs/securosys-PARTITION/keys/my-key-label/grants/pki
Use external keys in the PKI engine
Once you have registered an external key, you can use it in any secrets engine that support external keys, such as the PKI engine.
Make sure the PKI engine is enabled:
bao secrets enable pki
Generate a self-signed root certificate in the PKI engine using the external key:
bao write pki/root/generate/kms external_key_ref=securosys-PARTITION:my-key-label common_name="My Root CA" ttl=3650d
For more details about using the PKI engine, see the OpenBao documentation. As of OpenBao 2.7.0, the following PKI engine endpoints support external keys: