Getting Started with JCE/JCA API Provider
The initial partition setup password is used to obtain or update a permanent secret as shown in the samples below. Once the permanent secret has been fetched it should be used from then on. The permanent secret is used to establish the secure connection between the JCE Provider and the user's HSM partition.
Download
Head to the Downloads page to get instructions on how to get the software.
Install
Extract the Securosys JCE-Provider and import the JAR into your IDE.
mkdir ${JCE_PROV_VERSION}
unzip -j ${JCE_PROV_VERSION}.zip -d ${JCE_PROV_VERSION}
First Steps
On initial setup and configuration of a Primus HSM partition, the installation process (Security Officer of the HSMs) generates a partition setup password for a given user. The setup password is a 29-alphanumeric dash separated string in the form of FXAJX-XWVQ3-DC0O5-3SLQF-LJ9L3 with limited time validity starting after first usage (HSM default: 3 days; CloudHSM default: 1 week; developer account: 1 year).
Note: In case of Service Proxy (CloudHSM) the Service Proxy password must be configured, before fetching the HSM permanent secret.
- CloudHSM
- On Premise
If you are using CloudHSM or your own reverse proxy, you will need to learn how to configure a proxy connection first. The sample shows how to establish a connection and extract Permanent User Secret using a temporary secret and how to set up redundant connection.
Change the following properties in the CloudsHSMSample.java based on the information provided in your support ticket.
When utilizing CloudHSM service, refer to CloudHSM Connectivity Details for API-Endpoint URI proxyhost and proxy-port.
final String proxyhost = "<cloudsHSM.hostname>";
final String proxyport = "2300";
final String proxyuser = "<proxyuser>";
final char[] proxypassword = "<proxypassword>".toCharArray();
final String hsmuser = "<USERNAME>";
final char[] hsmpassword = "<setup-password>".toCharArray();
If you're connecting to the Dev program or to your on-prem HSM directly (without reverse proxy), this sample shows how to establish the connection to retrieve permanent secret by using a temporary secret provided by your HSM operator (for your own Primus HSM) or by us (for Dev Program).
For on-premise deployments, verify API-Endpoint URI with your administrator. Contact your service administrator for authentication credentials.
Change the following properties in the UserSecretSample.java based on the information provided in your support ticket.
final String host = "grimsel.securosys.ch"; // externally reachable test/development HSM
final String port = "2400"; // Default HSM's JCE port is 2300. Dev program partition is accessible at 2400
final String user = "TESTUSER";
final char[] password = "FDgKb-zxsPR-ud6EN-GK6Jz-adrvB".toCharArray();
The API login is protected against brute force attacks (setup password and permanent secret). After too many wrong trials the API login is locked for some time. Wrong trials are reset after a defined time. Restart of the device resets lockout and attempts.
Further Samples
Learn more about the Securosys JCE-Provider by following the samples, Log in to the HSM using the secret key retrieved in the previous step: