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.
The steps in this section are done by the HSM administrator (the SO or the PSO). Skip this section if you are using CloudHSM.
How to Edit the Configuration
In the steps below, you will edit the Network and Security Configurations to enable PKCS#11. Make sure that you are familiar with Primus HSM management before starting.
For more details, please see the Primus HSM - Management guide and the Primus HSM - Configuration guide. For comprehensive guidance, refer to the Primus HSM User Guide.
The commands below show how to edit the Device Security Config. If the User Security Config is enabled for your Partition, it overrides the Device Security Config. Therefore, you must configure the same settings in the User Security Config instead.
Activate SO
Make sure you have SO privileges:
- Device Front Panel
- Console
- Decanus Terminal
- SO ACTIVATE
hsm_so_activation
- 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
- Console
- Decanus Terminal
- XML Configuration File
- SETUP CONFIGURATION NETWORK SERVICES PKCS#11 INTERFACES: 1
- SETUP CONFIGURATION NETWORK SERVICES PKCS#11 TCP PORT: 2310
hsm_net_list_config serv=2 serv_if
hsm_net_list_config serv=2 serv_port
- SETUP CONFIGURATION NETWORK SERVICES
Verify the row PKCS#11 (default TCP Port:2310 and Interface:1)
<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
- Console
- Decanus Terminal
- ROLES USER NEW SETUP PW
hsm_sec_new_setup_pass
- 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
- Console
- Decanus Terminal
- XML Configuration File
- SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPTO POLICY CLIENT API ACCESS
- SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPTO POLICY PKCS#11
hsm_sec_set_config crypto_access=true
hsm_sec_set_config pkcs11=true
- Setup Configuration Security Device Security Crypto Policy
- Client API access
- PKCS#11
<pkcs_process>
<active>enabled</active>
<port>2310</port>
<interface>1</interface>
</pkcs_process>
...
<crypto_process>
<client_api_access>enabled</client_api_access>
...
The Client API Access and PKCS#11 must always be enabled in the Device Security Config.
If you are following this guide by modifying the User Security Config, you must enable Client API Access and PKCS#11 in both the Device and User Security Configs.
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 PKCS#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 define the PKCS#11 Password, also called the PKCS#11 PIN, and provide it to your application. This password is chosen by you. To set the PKCS#11 password:
- Device Front Panel
- Console
- Decanus Terminal
- XML Configuration File
- SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPTO POLICY PKCS#11 PASSWORD
hsm_sec_set_config pkcs_pwd=<password>
- Setup Configuration Security Device Security Crypto Policy PKCS#11 password: *******
<crypto_process>
<pkcs_password>MYPASSWORD</pkcs_password>
...
For restrictions on the PKCS#11 password, see this support article.
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").
Most applications require session objects enabled.
- Device Front Panel
- Console
- Decanus Terminal
- XML Configuration File
SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPO POLICY SESSION OBJECTS
hsm_sec_set_config session_objects=true
- Setup Configuration Security Device Security Crypto Policy
- Session objects
<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.
For high security it is recommended to disable import, export, and extract.
- Device Front Panel
- Console
- Decanus Terminal
- XML Configuration File
- 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
hsm_sec_set_config key_import=false
hsm_sec_set_config key_export=false
hsm_sec_set_config key_extract=false
- Setup Configuration Security Device Security Crypto Policy
- Key import
- Key export
- Key extraction
<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
- Console
- Decanus Terminal
- XML Configuration File
SETUP CONFIGURATION SECURITY DEVICE SECURITY CRYPO POLICY KEY INVALIDATION
hsm_sec_list_config inval_keys
- Setup Configuration Security Device Security Crypto Policy
- Key invalidation
<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
- Console
- Decanus Terminal
- XML Configuration File
SETUP CONFIGURATION SECURITY DEVICE SECURITY MANAGEMENT POLICY CLIENT API USER LOG
hsm_sec_set_config client_log=true
- Setup Configuration Security Device Security Management policy
- Client API User Log
<crypto_process>
<crypto_log>enabled</crypto_log>
...
Reminder: 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 explanation at the top.
Next Steps
Primus HSM should now be ready to accept client connections via PKCS#11. Additionally, you should now have the following information ready:
- HSM connectivity details (URL/IP, port)
- User/Partition name
- Setup Password
- PKCS#11 Password
Next, install the PKCS#11 Provider on the machine that hosts your client application.