Skip to main content

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)

You can retrieve the required passwords or secrets with:

  • 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.

Preview of the <HSM connection and credentials> parameters:

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

To keep the documentation consice, the <HSM connection and credentials> parameters are used across most Primus Tools commands.

It's recommended to note down these parameters ahead of time for easier reference.

Fetching the Permanent Secret​

Retrieve Permanent Secret

The setup password has a limited lifespan and serves as a temporary credential to retrieve the permanent secret. The access to Primus HSM or CloudHSM will be lost if the permanent secret is not retrieved before the setup password expires.

In this example, we will fetch the permanent secret for a connection to a CloudHSM partition.

For on-premises Primus HSM, go back to the Prerequisites to see how to issue a new setup password.

CloudHSM credentials are provided during the onboarding procedure. To issue a new valid setup password for CloudHSM, please open a ticket in the Securosys Support Portal, make sure to provide your CloudHSM partition name (user).

warning

Requests for issuing a new setup password for CloudHSM are subject to service charges.

Step-by-Step Guide:

  1. Note down your setup password in the below format, e.g.:
g3z7Y-5knqc-hkQAs-9A4kE-Ppr6v
  1. 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
  1. Set and blind the CloudHSM proxy password.
caution

The proxy user and password are only applicable when working with CloudHSM. For on-premises Primus HSM you can skip this step.

Example command:

java -jar primus-tools.jar BlindPassword consoleinput: -outputfile d:\pwproxy
  1. 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 a-api.cloudshsm.com -port 2300 /
-user DEMO-TEST -password file:d:\pwsetup /
-primusproxyuser DEMO-TESTP -primusproxypassword file:d:\pwproxy /
-blinded -outputfile d:\pwsecret
info

Replace the host URL with the relevant connectivity details for general on-premises Primus HSM and CloudHSM connectivity, see HSM - Connectivity Details.

Please ensure that there are no firewall components blocking communication between your system and the Primus HSM or CloudHSM.

  1. Test the connection to the CloudHSM by using the Login command. Use the permanent secret file pwsecret:
java -jar primus-tools.jar Login 
-host a-api.cloudshsm.com -port 2300
-user DEMO-TEST -password file:d:\pwsecret

Continue with the various command tutorials.