Connecting to the HSM

For each Primus Tools command, you need to provide the following details:

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

You should have received these values from your HSM operator. The default network parameters are published on the Connectivity Details page.

Specifying the 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>]]

Argument	Description
-host	URL or IP address where the HSM is reachable.
-port	Port where the JCE API is listening. Optional, defaults to 2300.
-user	User/Partition name
-password	Secret to authenticate to the Partition. See below for how to specify the value.
-primusproxyuser	Proxy username. Only for CloudHSM, leave out otherwise.
-primusproxypassword	Proxy password. Only for CloudHSM, leave out otherwise.

info

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

Providing Secrets

When working with Primus Tools, you will need to provide secrets, such as the Setup Password. These secrets are provided to the -password argument (always) and the -primusproxypassword argument (CloudHSM only). You can specify values using three different options:

• On the command line (caution: history traces have to be cleared manually) -password <password|permanent-secret>
• Interactively via a keyboard: -password consoleinput:
• From a file: -password file:<path/name>

For all of these, the password/secret can either be provided in plain or in blinded format (see below).

Blinding Secrets

For all secrets, it is recommended to "blind" them once, and afterwards only use the blinded versions. Blinding makes it harder to misuse the secret if it is stolen and copied to a different machine.

Blind the Setup Password and store the result to a file. You will be prompted to enter the password interactively.

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

This results in having a file D:\pwsetup that looks as follows:

blinded-aes:c775dbe31d545d38dcb342ccadee236e3ec...6005d6766808e7fc522ef60d5a670b6e9c111837fe451041

When using CloudHSM, also blind the CloudHSM proxy password:

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

For more blinding options, see Credential Management.

warning

Blinding impacts operation in case of migration, because the blinded password won't work on a different machine. When reinstalling the Primus Tools on a new machine, use a new Setup Password and blind it.

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.

Use the GetUserSecret command to fetch the permanent secret and write it 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.

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.