Primus HSM Configuration

To setup the Primus HSM please follow the steps in the Primus HSM User Guide chapter 3.

Overview

Primus HSM configuration can be performed via different user interfaces (Device frontpanel, command-line Console, Decanus Terminal, XML configuration file).

Security configuration parameters can be applied at either the global device level or scoped to individual partitions (user), both requiring security officer role. The table below outlines the corresponding command differences. For comprehensive guidance, refer to the Primus HSM User Guide.

Device Security Configuration

Device Frontpanel

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

• SETUP CONFIGURATION SECURITY USER SECURITY ...

Console

For individual partition/user configuration, enter first into the specific user configuration by typing

  hsm_user_enter_config 

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

  hsm_user_enter_config
  
  Enter username:

  SO >>> PART001

  SO already activated!

  SO : PART001 >>> 

Then apply the necessary user specific security configuration parameters by replacing hsm_sec_... with hsm_user_...:

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

Below illustrated security configuration parameters refer to global device security configuration (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).

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 Frontpanel

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

Make sure you have SO privileges for the steps below (security configuration):

Device Frontpanel

• SO ACTIVATE
  (or in some older releases: - ROLE ACTIVATION SO ACTIVATE)

Console

hsm_so_activation

Decanus Terminal

• SO Activation

Setup Password

If a new user is setup, note down the user's setup password. It is required to setup the HSM connection and retrieving the permanent user secret with the ppin command.

In case you need a new setup password for the ppin command, on the HSM acquire SO privileges and execute the following command (the setup password has a limited lifetime, default 3 days from first usage onwards):

Device Frontpanel

• ROLES USER NEW SETUP PW

Console

hsm_sec_new_setup_pass

Decanus Terminal

• Roles User New Setup Password

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. Set the respective security configuration in

Device Frontpanel

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

PKCS#11 operates in two modes: Public object mode and logged-in mode, where private key operations can be performed. On the Primus HSM, access to the HSM is granted with permanent user secret. The additional password¹ for the PKCS#11 login command must be set using the SO role, per device or partition specific.

In case you have to set a PKCS#11 password:

Device Frontpanel

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

Using HSM Session Objects

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

Recommendation

Most applications require session objects enabled.

Device Frontpanel

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

Export / Import Settings

caution

Secure operation requires import, export, and extract to be disabled.

Following policies define key import/export allowance (see HSM User Guide for details):

Device Frontpanel

• 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

Activated Key Invalidation creates a shadow copy of the key when it is deleted. This prevents creation of a new key with the same key name and key id and some later mentioned tests may fail. To check if Key Invalidation is disabled:

Device Frontpanel

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 Frontpanel

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

Above configuration parameters are shown for device level. If user specific configuration is activated, they have to be configured on the specific user partition! See section Overview.

info

• Primus HSM in FIPS mode requires PKCS#11 Provider 2.0 or newer to connect.
• It is recommended to use HSM firmware v2.8 or later.

Footnotes

1. See PKCS#11 Password Restrictions ↩