Set up API provider and access your CloudHSM

You can access the CloudHSM via different APIs:

• REST
• JCE
• PKCS#11
• MSCNG

These API allow you to make calls to the HSM, for example, to generate keys, to decrypt data, or to sign data. To use an API, you need to install an API provider. The API provider is a library or piece of software that exposes a well-defined and publicly documented API. Internally, the API provider communicates with the HSM over a proprietary protocol. Think of the API provider as a device driver, but over the network.

Choose the provider that is most suitable for your use case. For example, if you are writing a Java application, you might choose JCE.

Set up the provider

info

If you are using CloudHSM with the REST API provider, no setup is required and you can skip this step. Securosys manages the TSB (which provides the REST API) for you.

For all other API providers, follow these steps:

1. Install the provider.
2. Configure it with the network settings pointing to your CloudHSM.
3. Configure it with the setup password. This establishes a permanent shared secret that is used to authenticate and secure the connection between the API provider on your machine and the CloudHSM.

For detailed setup instructions, follow the provider's installation guide.

Setup password lifetime

The setup password has a limited lifetime. In CloudHSM, the setup password expires 7 days after Securosys has issued it.

If you use the setup password, you must exchange the setup password for a permanent secret within that time frame. See the respective API provider documentation for how to do that. The REST API does this automatically.

If you want to onboard an API provider at a later point in time you need to request a new setup password from Securosys Support. This can be subject to a cost, as generating a new password involves manual interaction with the HSM.

Please note: This means that if you want to use multiple different API providers (e.g., for evaluation purposes), or if you want to set up an API provider on multiple different hosts, you need to install and exchange the setup password for all providers on all hosts within this time frame.

Access the HSM

Follow the tutorial of your API provider for how to access the HSM and how to perform cryptographic operations using the API provider.