Permanent Secret Fetching

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

This initial partition setup password is used to obtain or update a permanent secret stored in a ciphered form within the '.secrets.cfg' file using the 'ppin' command line utility. From then on, the permanent secret is used to establish the secure connection between the PKCS#11 Provider and the user's HSM partition.

Brute force protection

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.

The PKCS#11 password is also protected against brute force attacks similar to above secrets. After too many wrong trials PKCS#11 privileged access is locked (API login is still possible). The same HSM timer configurations are shared.

Ensure correct file permissions (Linux)

Group Concept

By default, the PKCS#11 provider files (libraries, executables, configuration) are assigned to the primus group. Any user or application account intending to use the provider must be added to this group to access the necessary files.

Check whether the user account is part of the PKCS#11 provider group, using the groups command. If the account is not a member of the required group, add it by executing sudo usermod -a -G providergroup username, e.g.

sudo usermod -a -G primus myuser

Adding a user to a new group requires logout/login to update the permissions. As temporary workaround you may use sudo login -f <user>.

Ensure write access

Managing connection secrets

Write access to the .secrets.cfg file is required when adding or modifying connection secrets using the ppin tool.

For example, verify the current set of permissions on Linux:

ls -l /etc/primus/.secrets.cfg

-rw-r----- 1 primus primus 236 Jun 17 16:38 /etc/primus/.secrets.cfg

In the above case, only the primus user has write access. Therefore, one option is to execute all secret modification commands on this page as the primus user:

sudo -u primus /usr/local/primus/bin/ppin <options>

CloudHSM-only: Add proxy credentials

CloudHSM uses an additional proxy in front of the HSM cluster. Before you can access the HSM to fetch the permanent secret, you need to configure the proxy credentials. You should have received a proxy username and a proxy password.

Configure the proxy username by adding the proxy_user field to your slot(s) in the primus.cfg configuration file:

primus:
{
    hsm0: {
      host = "PROXY_URL";
      port = "2310";
      slots: {
         slot0: {
            client_id = "CLIENT_ID";
            user_name = "HSM_USERNAME";
            proxy_user = "PROXY_USERNAME";
            id = 0;
         };
      }; /* end slots */
    }; /* end hsm0 */
}; /* end primus */

To obtain the host and port information, refer to the CloudHSM connectivity details.

Next, configure the proxy password:

ppin -p -e PROXY_USERNAME

********************
Primus Permanent PIN
********************
Provide proxy password for 'PROXY_USERNAME' : <enter Service Proxy Password, no echo>

********************
Primus Permanent PIN
********************
[01] slot-id 0:    user 'HSM_USERNAME' permanent secret: MISSING
[01] service/proxy user 'PROXY_USERNAME' permanent secret: Configured

Note that CloudHSM services can be configured to have IP allowlisting (whitelisting). If you set up your CloudHSM with an allowlist, make sure that the traffic originates from the correct IP addresses.

To remove the proxy password again (if you no longer use the proxy):

ppin -x -e PROXY_USERNAME

Add the Permanent Secret

Assume you have configured a partition for user 'HSM_USERNAME'. To fetch and add a permanent secret to your configuration, run:

ppin -a -e HSM_USERNAME

********************
Primus Permanent PIN
********************
Provide setup password for 'HSM_USERNAME': <enter User Setup Password, no echo>
Provide PKCS11 password for 'HSM_USERNAME': <enter PKCS#11 PIN, no echo>
********************
Primus Permanent PIN
********************
[01] slot-id 0: user 'HSM_USERNAME' permanent secret: Configured

tip

All setup passwords have a timeout that starts after first use. Now that you have used the setup password to retrieve the permanent secret, the HSM starts counting down the clock. The exact timeout is defined by the security officer (SO) of the HSM.

If you later want to retrieve the permanent secret again, for example to use the PKCS#11 provider on a different machine, you will likely need a new setup password.

Update the Permanent Secret

In case the permanent secret was changed, you can update it using a new setup password:

ppin -u -e HSM_USERNAME

********************
Primus Permanent PIN
********************
Provide setup password for 'HSM_USERNAME': <enter User Setup Password, no echo>
Provide PKCS11 password for 'HSM_USERNAME': <enter PKCS#11 PIN, no echo>
********************
Primus Permanent PIN
********************
[01] slot-id 0: user 'HSM_USERNAME' permanent secret: Configured

Note that update procedure failure removes the current permanent secret entry. That means the next trial has to be done with "add permanent secret" (ppin -a -e HSM_USERNAME).

Remove the Permanent Secret

If you no longer use the PKCS#11 partition, you can remove the permanent secret:

ppin -r -e HSM_USERNAME

********************
Primus Permanent PIN
********************
[01] slot-id 0: user 'HSM_USERNAME' permanent secret: MISSING