Primus HSM Setup

This page explains the configuration that is needed on the HSM in order for the HSM to work with the TSB.

info

This page is only relevant if you want to use an on-premise Primus HSM. If you use a CloudHSM, you can skip this page.

Run the Initial Wizard

If you have not already run the initial wizard of the Primus HSM, please follow Chapter 3 of the Primus HSM User Guide. This does the basic initialization of the device.

Check the License

Ensure that your license includes the REST_API and ROOT_KEY_STORE to use the REST API.

If you plan to use Smart Key Attributes and its multi-authorization workflows, the TSB_ENGINE, KEY_AUTH, and EXTENDED_KEY_ATTRIBUTES licenses are also required.

You can check the installed license as follows:

UI

System ➜ Diagnostics Device ➜ License

Console

hsm_diagnostics lic

Device Configuration

Next, make the necessary device-wide configurations on the Primus HSM.

Before you start, log in to the HSM via one of its administrative interfaces (console, device front panel, Decanus Terminal). Then activate the Security Officer (SO) role:

UI

SO Activate

Console

so

Initialize the Root Key Store

The Root Key Store (RKS) needs to be installed and set up. To find out whether this has already been done on a device, check that the Root Key Store is shown as "active":

UI

System ➜ Diagnostics Device ➜ Firmware

Console

hsm_diagnostics fw

If the Root Key Store is not yet set up, run the following commands. The HSM may prompt you to insert an USB stick with your license file.

UI

System ➜ Root Key Element ➜ Install Root Key Element

System ➜ Root Key Element ➜ Setup Root Key Store

Console

hsm_sec_install_rke
hsm_sec_setup_rks

For details, see Section 6.1 "Initialize Root Key Store, Device Intermediate Key and Audit Key" of the Primus HSM User Guide.

warning

This will delete any previously installed Root Key Store! This step only needs to be done once per HSM. Skip this step if you have already set up the Root Key Store before.

Enable the JCE API

Make sure that the JCE API is enabled device-wide. The TSB uses the JCE API to communicate with the HSM.

UI

Setup ➜ Configuration ➜ Security ➜ Device Security ➜ Crypto Policy ➜ JCE

Console

hsm_sec_list_config jce
hsm_sec_set_config jce=true

Also set up your network configurations to enable the JCE port.

Create a User/Partition

A "Partition" (from the HSM's perspective also called a "User") is a dedicated space on the HSM, with a separate key store and separate security settings. This allows isolating environments on the HSM, as a form of multi-tenancy.

The TSB requires a Partition that it will access.

Create a new Partition:

UI

Roles ➜ User ➜ Create

Console

hsm_sec_create_user

Note down the Setup Password, as you will need it later. If you missed that or if the password expired, you can generate a new one:

UI

Roles ➜ User ➜ New Setup Password

Console

hsm_user_new_setup_pass

User Configuration

In addition to the device-wide security configuration, there are also User-specific security configurations. See also Section 3.9 "Individual Configuration" in the Primus HSM User Guide.

Enable the following settings:

UI

Setup ➜ Configuration ➜ Security ➜ User Security ➜ (User) ➜ (setting)

For the following settings:

• User Configuration
• JCE
• Key Authorization
• REST API access
• TSB Workflow Engine

Console

hsm_user_enter_config

hsm_user_set_config use_usr_cnf=true

hsm_user_set_config jce=true
hsm_user_set_config key_auth=true
hsm_user_set_config rest_api=true
hsm_user_set_config tsb_engine=true

hsm_user_exit_config

To view a parameter value:

hsm_user_list_config <param>

info

"Key Authorization" and "TSB" are optional and only needed if you want to use Smart Key Attributes (SKA) and leverage the TSB's workflow engine to orchestrate SKA flows. If you want to use the TSB as a simple REST-to-JCE translation layer, they are not needed.

Optional Settings

Optionally, you may want to enable the following settings in the User Security Configuration:

• Key Import
• Key Export
• Key Extraction
• Key Invalidation
• Session Objects

Optionally, you may want to disable:

• Object destruction

For details on these settings, see Section 4.6 "Setup – Configuration – Security" of the Primus HSM User Guide.

Next Steps

You have now configured the Primus HSM and set the required Security Configuration. You also have a User/Partition and an accompanying Setup Password.

Next, proceed to deploying the TSB Docker container.