Primus HSM Configuration

This section explains how to configure the PKCS#11-specific settings on the HSM, including how to allow connections via PKCS#11 and how to obtain the necessary passwords.

If you have a new HSM, please follow the steps in section 3 of the Primus HSM User Guide to complete the initial device setup. Then return to this guide.

info

The steps in this section are done by the HSM administrator (the SO or the PSO). Skip this section if you are using CloudHSM.

Overview

The Primus HSM configuration can be performed via different user interfaces: the device front panel, the console, or the Decanus Terminal. The settings can either be set manually one-by-one, or by loading a prepared XML configuration file.

Security configuration parameters can be applied either at the global device level or scoped to individual Users (Partitions). Changing them requires the (Device) Security Officer (SO) or Partition Security Officer (SO) role. The table below outlines the corresponding command differences. For comprehensive guidance, refer to the Primus HSM User Guide.

Device Security Configuration

Device Front Panel

• SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPTO POLICY ...

Console

• List parameters: hsm_sec_list_config
• Change parameters: hsm_sec_set_config

Decanus Terminal

• SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPTO POLICY ...

XML Configuration File

  ...
  <crypto_process>
    ...
    <import_keys>disabled</import_keys>
    <export_keys>disabled</export_keys>
    <extract_keys>disabled</extract_keys>
    ...

User Security Configuration

Device Front Panel

• SETUP CONFIGURATION SECURITY USER SECURITY ...

Console

For individual Partition/User configuration, first enter the specific User configuration:

hsm_user_enter_config

Then enter the User name followed by ENTER. After that the prompt will indicate the User name. E.g.

  hsm_user_enter_config

  Enter username:

  SO >>> PART001

  SO already activated!

  SO : PART001 >>> 

Then apply the user specific security configurations by replacing hsm_sec_... with hsm_user_.... For example:

• List parameters: hsm_user_list_config
• Change parameters: hsm_user_set_config

Decanus Terminal

• SETUP CONFIGURATION SECURITY USER SECURITY ...

XML Configuration File

Each Partition has a configuration section starting with <crypto_user state="enabled">:

  ...
  <crypto_user state="enabled">
    <user_name>PART001</user_name>
    ...
    <import_keys>disabled</import_keys>
    <export_keys>disabled</export_keys>
    <extract_keys>disabled</extract_keys>
    ...
  </crypto_user>

info

The security configuration parameters in the rest of this section refer to the global device security configuration and use the syntax for firmware v3.x. In case you have individual User/Partition settings, enter into Partition configuration and use the commands analogous on the specific Partition (as shown above).

Activate SO

Make sure you have SO privileges:

Device Front Panel

• SO ACTIVATE

(In some older releases: ROLE ACTIVATION SO ACTIVATE)

Console

hsm_so_activation

Decanus Terminal

• SO Activation

Verify network configuration

Assert that the HSM has a proper network configuration and can be reached from the computer having the PKCS#11 library installed. The API will be reachable under the default port unless configured differently. Note that the service may be assigned freely to a specific network interface.

Device Front Panel

• SETUP CONFIGURATION NETWORK SERVICES PKCS#11 INTERFACES: 1
• SETUP CONFIGURATION NETWORK SERVICES PKCS#11 TCP PORT: 2310

Console

hsm_net_list_config serv=2 serv_if
hsm_net_list_config serv=2 serv_port

Decanus Terminal

• SETUP CONFIGURATION NETWORK SERVICES

Verify the row PKCS#11 (default TCP Port:2310 and Interface:1)

XML Configuration File

<pkcs_process>
  <active>enabled</active>
  <port>2310</port>
  <interface>1</interface>
</pkcs_process>

Setup Password

The setup password will later be required to connect the PKCS#11 Provider to the HSM and to retrieve the permanent secret with the ppin command. Obtain a setup password for the User/Partition and note it down.

The setup password is displayed when a new User/Partition is created. Alternatively, you can generate a new setup password for an existing user:

Device Front Panel

• ROLES USER NEW SETUP PW

Console

hsm_sec_new_setup_pass

Decanus Terminal

• Roles User New Setup Password

Note that the setup password has a limited lifetime, and expires 72 hours (3 days) after the first usage. This lifetime is configurable.

Enable PKCS#11 API

In order to use the PKCS#11 Provider, the Client API and PKCS#11 access needs to be enabled on the HSM.

Device Front Panel

• SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPTO POLICY CLIENT API ACCESS
• SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPTO POLICY PKCS#11

Console

hsm_sec_set_config crypto_access=true
hsm_sec_set_config pkcs11=true

Decanus Terminal

• Setup Configuration Security Device Security Crypto Policy
  • Client API access
  • PKCS#11

XML Configuration File

<pkcs_process>
  <active>enabled</active>
  <port>2310</port>
  <interface>1</interface>
</pkcs_process>
...
<crypto_process>
  <client_api_access>enabled</client_api_access>
  ...

Preparing the PKCS#11 Password (PIN)

The PKCS#11 standard defines two modes: public object mode and logged-in mode, where private key operations can be performed. Therefore, many PCKS#11 API calls require the application to call C_Login(hSession, userType, pPin, ulPinLen) first, to log in to the token on the PKCS#11 API level.

Therefore, you need to obtain the PKCS#11 Password, also called the PKCS#11 PIN, and provide it to your application. To set the PKCS#11 password:

Device Front Panel

• SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPTO POLICY PKCS#11 PASSWORD

Console

hsm_sec_set_config pkcs_pwd=<password>

Decanus Terminal

• Setup Configuration Security Device Security Crypto Policy PKCS#11 password: *******

XML Configuration File

<crypto_process>
  <pkcs_password>MYPASSWORD</pkcs_password>
  ...

For restrictions on the PKCS#11 password, see this support article.

info

The PKCS#11 Password is different from the setup password/permanent secret. Both the PKCS#11 Password and the setup password are required.

Every Primus API Provider (including the Primus PKCS#11 Provider) uses the permanent secret to establish a secure channel to the Primus HSM. This is the same across all Primus API Providers. The PKCS#11 Password comes from the PKCS#11 standard, which uses this password to log into the PKCS#11 token.

Using HSM Session Objects

The use of session objects (CKA_TOKEN = false) requires HSM firmware v2.8.20/v2.9.2 or later and the "session objects" setting to be enabled. (Up to version 2.10 the parameter was called "External Storage").

Recommendation

Most applications require session objects enabled.

Device Front Panel

SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPO POLICY SESSION OBJECTS

Console

hsm_sec_set_config session_objects=true

Decanus Terminal

• Setup Configuration Security Device Security Crypto Policy
  • Session objects

XML Configuration File

<crypto_process>
  <session_objects>enabled</session_objects>
  ...

Importing/Exporting Keys

The following settings define whether key import/export is allowed. For details, see the HSM User Guide.

caution

For high security it is recommended to disable import, export, and extract.

Device Front Panel

• SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPO POLICY KEY IMPORT
• SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPO POLICY KEY EXPORT
• SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPO POLICY KEY EXTRACT

Console

hsm_sec_set_config key_import=false
hsm_sec_set_config key_export=false
hsm_sec_set_config key_extract=false

Decanus Terminal

• Setup Configuration Security Device Security Crypto Policy
  • Key import
  • Key export
  • Key extraction

XML Configuration File

<crypto_process>
  <import_keys>disabled</import_keys>
  <export_keys>disabled</export_keys>
  <extract_keys>disabled</extract_keys>
  ...

Key Invalidation

When Key Invalidation is enabled, a shadow copy of the key is created when a key is deleted. This prevents accidental deletion of keys by an application. The SO/PSO can reactivate keys or irrevocably delete them.

Note that when a key is invalidated but not yet deleted by the SO/PSO, the same key label or key id cannot be reused (until it is irrevocably deleted).

Device Front Panel

SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPO POLICY KEY INVALIDATION

Console

hsm_sec_list_config inval_keys

Decanus Terminal

• Setup Configuration Security Device Security Crypto Policy
  • Key invalidation

XML Configuration File

<crypto_process>
  <invalidate_keys>disabled</invalidate_keys>
  ...

User Log via PKCS#11 API

To fetch the user log from the HSM via PKCS#11 API or ppin tool, enable log fetching:

Device Front Panel

SETUP CONFIGURATION SECURITY DEVICE SECURITY MANAGEMENT POLICY CLIENT API USER LOG

Console

hsm_sec_set_config client_log=true

Decanus Terminal

• Setup Configuration Security Device Security Management policy
  • Client API User Log

XML Configuration File

<crypto_process>
  <crypto_log>enabled</crypto_log>
  ...

Device and User specific configuration

The configuration commands are shown for the device security config. If User/Partition specific configuration is activated, they have to be configured on the specific Partition! See the overview.