Primus HSM - User Authentication

When working with Primus HSM, both as an administrator and as an application developer, you will often encounter two terms: Setup Password and User Secret. The User Secret is sometimes also called the Permanent Secret.

Both of them are used to authenticate Users (applications) that want to access a Partition on the HSM. This page explains how this user authentication works, what these passwords are, and how they work.

Architecture

Recall the basic application architecture. At minimum, you need a Primus HSM (possibly a cluster of them) and a business application. The application connects to the Primus HSM using one of the native Primus API Providers: PKCS#11, JCE, or MSCNG. (A REST API is also available, but there the Transaction Security Broker acts as a REST-to-JCE rewrite proxy. The Primus HSM does not natively speak REST.)

Secure Channel

The Primus HSM is a network appliance, meaning that applications connect to it over the network. Therefore, there is a need to establish a secure channel (that is confidential and authenticated) between the application and the HSM.

On the client-side, the Primus API Provider implements the channel establishment, session management, and tear-down. Business applications locally communicate with the Primus API Provider.

To establish this channel, both ends of the channel (the Primus API Provider and the Primus HSM) need to have the same, pre-shared symmetric secret. This is where the Setup Password and User Secret come in. They are the secrets that are used to establish the secure channel.

Workflow

In practical terms, the workflow looks as follows:

1. The HSM administrator (Security Officer, SO) creates a new Setup Password and gives it to the business application administrator.
2. The application administrator configures the application deployment with the Setup Password.
3. The application deployment connects to the Primus HSM with the Setup Password.
4. During this initial session, the Primus HSM shares the User Secret with the business application.
5. The application securely stores the User Secret in its local configuration.
6. From now on, the application connects to the Primus HSM with the User Secret.
7. After some time, the Setup Password expires.

Comparison

	Setup Password	User Secret
Usage	Limited use, for temporary setup	Long-term secret
Expires	Yes (default: 72 hours after first use)	No
Creating a new one will	Invalidate the previous Setup Password	Invalidate the previous User Secret and Setup Password
Can be revoked/rotated	Yes (by creating a new Setup Password or new User Secret)	Yes (by creating a new User Secret)
Handled by administrators	Yes	Should not
Stored by applications	Should not	Yes

What to do as an HSM Administrator (Security Officer, SO)

1. Whenever you want to onboard an application and grant it access to a Partition, generate a new Setup Password.

   UI

   Roles ➜ User ➜ Credentials ➜ New Setup Pwd

   Console

   hsm_user_new_setup_pass

   Generating a new Setup Password is usually done for the initial onboarding or re-onboarding of an application.

   Creating a new Setup Password invalidates the previous Setup Password. However, it does not invalidate the User Secret. Therefore, it should not lock out any existing application.

   tip

   To properly separate different applications, it is recommended to create one User/Partition per application. For example, your CA application should have a different Partition than your database encryption application. If they use the same Partition, they are able to list and use each others' keys!

2. Configure the Setup Password expiry time (lifetime). The factory default is 72 hours. If you want it to be single-use, set the lifetime to 0. If you want longer expiry times (for example, for testing environments), simply increase the value.

   UI

   Setup ➜ Configuration ➜ Security ➜ Device Security ➜ Crypto Policy ➜ Lifetime Setup Pwd

   Console

   hsm_sec_set_config lifespan_setup_pwd

   tip

   The expiry time is after first use. For example, you can generate a Setup Password today, and then let it sit unused for 2 weeks. The expiry countdown only starts once the first successful connection is made with the specific Setup Password.

3. In the rare case that you want to rotate the User Secret, create a new one.

   UI

   Roles ➜ User ➜ Credentials ➜ New User Secret

   Console

   hsm_sec_new_user_secret

   danger

   There is only one User Secret for each User/Partition. By creating a new User Secret, you are locking out all applications that are already onboarded. They will all need to be configured again with new Setup Passwords.

What to do as a Business Application Administrator

1. Configure you application with the User name/Partition name and the Setup Password that you received from your HSM administrator.
2. Exchange the Setup Password for the User Secret. If not, your application will lose access once the password expires! For details, see the installation guides for the Primus API Providers: PKCS#11, JCE, MSCNG.
3. If you need a new Setup Password, contact your HSM administrator.

References

• Section 5.5 "User (Partition)" of the Primus HSM User Guide