Set up API provider and access your CloudHSM
You can access the CloudHSM via different APIs:
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.
Step 1: Install the Provider
Install the desired API provider, either on the same machine as your business application (JCE, PKCS#11, MSCNG), or as a standalone service (REST API/TSB). For detailed setup instructions, follow the provider's installation guide.
If you are using CloudHSM with REST-as-a-Service, no installation is required. Securosys manages the TSB (which provides the REST API) for you.
Step 2: Configure the Connection Details
Configure the API provider or your business application with the connection details pointing to your CloudHSM or REST API instance.
Step 3: Fetch the Permanent Secret
Configure the API provider with the setup password or JWT and make an initial connection to the HSM. This fetches the permanent secret that is used to authenticate and secure the connection between the API provider and CloudHSM.
The steps to exchange the setup password for the permanent secret vary by API provider:
- PKCS#11
- JCE
- REST (self-hosted)
- RESTaaS/TSBaaS (Securosys-hosted): Make any request to the REST API with your JWT.
- The JWT includes an encrypted copy of the setup password. The REST API/TSB will exchange the setup password for you, and will store the permanent secret in its database.
The setup password has a limited lifetime. In CloudHSM, the setup password expires 7 days after its first use. You must fetch the permanent secret within that time frame.
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 is subject to a cost, because generating a new password requires manual Security Officer 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 fetch the permanent secret with all providers on all hosts within this time frame.
If later you request a new Setup Password or new JWT (to onboard another application), your existing applications that have already fetched the Permanent Secret will continue to work. This is because the new Setup Password is only used to fetch the same Permanent Secret.
If you want to lock out existing applications (for example, due to a suspected compromise), you can request the Permanent Secret to be rotated. This will be accompanied by a new Setup Password and JWT, to onboard your applications again.
For more details on the Setup Password and Permanent Secret, see the Primus HSM docs.
Step 4: 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.