Skip to main content

HSM Connection and Access Credentials

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)

Required passwords or secrets can be provided either:

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

The code box below shows the <HSM connection and credentials> parameters in detail:

-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>]]
warning

To decrease clutter in this document the <HSM connection and credentials> parameters are used in most described Primus Tools commands. Therefore we suggest noting down these parameters beforehand.

Fetching the Permanent Secret​

The setup password has a limited lifespan and serves as a temporary credential to retrieve the permanent secret. It is essential to fetch the permanent secret, which does not expire, within the lifespan of the setup password.

warning

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 more details on parameters and options for commands used, see Credential Management.

See Prerequisites on how to issue a new setup password for on-premises Primus HSM.For more information about setup passwords and permanent secrets, see Primus HSM User Guide.

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.

  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