Connecting to the HSM

For each Primus Tools command, the following connectivity details have to be provided:

• Connection details (FQDN hostname or IP address, TCP/JCE port number of the HSM)
• User (partition) and credentials (setup password or permanent secret)
• For CloudHSM: service user (proxy) and credentials (service password)

Providing Secrets

When working with Primus Tools, you will need to provide secrets, such as the Setup Password. You can provide the passwords/secrets to the tool using one of the following mechanisms:

• on command line (caution: history traces have to be cleared manually) password <password|permanent-secret>
• interactive via keyboard: -password consoleinput:
• from file (e.g. from USB drive): -password file:<path/name> containing either:
  • the setup password in plain or blinded format,
  • the permanent secret in blinded format.

HSM Connection Parameters

The Primus Tools need to know how to reach the HSM and how to authenticate. For that, all commands have the following common parameters:

-host <HSM hostname/IP-address> [-port <HSM TCP port number>] /
-user <user> -password [<password>|consoleinput:|file:<path/name>]] /
[-primusproxyuser <proxy_username>] /
[-primusproxypassword [<proxy_password>|consoleinput:|file:<path/name>]]

Ask your HSM administrator for these values. It's recommended to note down these parameters ahead of time for easier reference. The default parameters are published on the Connectivity Details page.

The primusproxyuser and primusproxypassword are only needed for Securosys CloudHSM. For on-premise Primus HSMs, don't provide these arguments.

To keep the documentation concise, these parameters are abbreviated as <HSM connection and credentials> across the rest of the Primus Tools documentation.

Fetching the Permanent Secret

Before you use any other Primus Tools command, you need to fetch the Permanent Secret using the GetUserSecret command (as shown below). This exchanges the temporary Setup Password for the Permanent Secret. Afterwards, you should use the Partition Name as the -user and the Permanent Secret as the -password for all subsequent Primus Tools invocations.

Check that you have received the Setup Password for your HSM partition. For on-premise Primus HSMs, your Security Officer (SO) can issue a new Setup Password. In CloudHSM, Securosys provides the Setup Password to you during onboarding. To issue a new Setup Password for CloudHSM at a later point, please open a ticket on the Support Portal.

danger

The Setup Password serves as a temporary credential to retrieve the Permanent Secret. It expires some time after its first use (in CloudHSM: 7 days). Access to the HSM will be lost if the Permanent Secret is not retrieved before that!

In CloudHSM, requesting a new setup password is subject to a charge.

Step-by-Step Guide:

1. Note down your setup password in the below format, e.g.:

g3z7Y-5knqc-hkQAs-9A4kE-Ppr6v 

2. Blind and store the temporary setup password to a file with BlindPassword command. When prompted by the console input, insert the setup password. Example command:

java -jar primus-tools.jar BlindPassword consoleinput: -outputfile d:\pwsetup

warning

Secret blinding might impact operation in case of tool migration. For more blinding options, see Credential Management.

Results in having a file D:\pwsetup:

blinded-aes:c775dbe31d545d38dcb342ccadee236e3ec……6005d6766808e7fc522ef60d5a670b6e9c111837fe451041

3. Set and blind the CloudHSM proxy password:

java -jar primus-tools.jar BlindPassword consoleinput: -outputfile d:\pwproxy

info

The proxy user and password are only applicable when working with CloudHSM. Skip this step for on-premise Primus HSMs.

4. Use the newly generated blinded setup password file pwsetup and proxy password file pwproxy with the GetUserSecret command to fetch the permanent secret to a blinded file:

java -jar primus-tools.jar GetUserSecret /
-host ch01-api.cloudshsm.com -port 2300 /
-user DEMO-TEST -password file:d:\pwsetup /
-primusproxyuser DEMO-TESTP -primusproxypassword file:d:\pwproxy /
-blinded -outputfile d:\pwsecret

Replace the connectivity details (host, port, user, etc.) with the values for your setup. Ensure that there are no firewall rules blocking communication between your system and the HSM.

5. Test the connection to the HSM using the Login command. Use the permanent secret file pwsecret as the password:

java -jar primus-tools.jar Login 
-host ch01-api.cloudshsm.com -port 2300 /
-user DEMO-TEST -password file:d:\pwsecret /
-primusproxyuser DEMO-TESTP -primusproxypassword file:d:\pwproxy

If this works, the command exits without any output. Otherwise, it prints an exception.

Next Steps

The Primus Tools are now ready to use. Continue with the tutorials for the various commands that the Primus Tools offer.