note

If you are planing to use Securosys CloudHSM you can skip this page and continue with the RestAPI docker setup.

Setup HSM

Installation Guide on setting up the PrimusHSM for the Securosys Rest-API. Before we can install and configure the Securosys Transaction Security Broker (Rest-API) we need to configure the Securosys on-premises Primus HSM. If you are using Securosys CloudHSM you can skip this installation and jump to Rest-API Installation If you operate your own PrimusHSM and have not initially setup the HSM, please follow the instructions of Running the initial wizard.

tip

This page gives an overview of the main HSM setup and settings. Note that information in this chapter may not be complete nor up-to-date, depending on the HSM firmware in use. This chapter is written exclusively for complete onPremise architecture ( Type 1 ). HSMaaS products are not affected. If the architecture types Type2, Type3 have been selected, you can skip to chapter 4 Transaction Security Broker Service Requirements

Running the Initial Wizard

If you have not already run the initial wizard for initial setup of the device, please following this guide.

Device configuration and partition setup

LC Display - Primus X/S-Series
Console Primus HSM, all Series

1) Activate SO role
```
    SETUP → ROLE ACTIVATION
```
2) Install and setup Root Key Store
Please ensure that you have copied the obtained license file to a USB stick.
Insert the USB stick into the device before proceeding with the following step.
```
    SYSTEM -> ROOT KEY ELEMENT -> INSTALL ROOT KEY STORE
    SYSTEM -> ROOT KEY ELEMENT -> SETUP ROOT KEY STORE
```
3) Enable REST-API
To utilize the basic TSB functionality, ensure that the REST-API is enabled.
Enabling this feature grants access to execute the following endpoint.
- Service Information (Information about the service)
- Synchronous Key Operations (Synchronous operations that are directly forwarded to the HSM.
- Keys (Access to the HSM KeyStore)
- Certificate (Access to certificate mangement)

    SETUP → CONFIGURATION → SECURITY → DEVICE SECURITY → CRYPTO POLICY → CLIENT API ACCESS
    SETUP → CONFIGURATION → SECURITY → DEVICE SECURITY → CRYPTO POLICY → KEY AUTH
    SETUP → CONFIGURATION → SECURITY → DEVICE SECURITY → CRYPTO POLICY → JCE
    SETUP → CONFIGURATION → SECURITY → DEVICE SECURITY → USER security → REST API ACCESS

4) Enable (TSB) Workflow Engine
Enable TSB Workflow Engine To utilize the enhanced multiauthorization signature workflow in TSB, ensure that the TSB Workflow engine is enabled, provided that the module is properly licensed.
Enabling this feature grants access to execute the following endpoints:
- /v1/sign, /v1/decrypt, /v1/unwrap, /v1/modify, /v1/block, /v1/request/**
```
    SETUP → CONFIGURATION → SECURITY → DEVICE SECURITY → CRYPTO POLICY → TSB WORKFLOW ENGINE
```

5) Additional device security Settings (Optional)
Please note that for a comprehensive understanding of the following settings being configured, it is advised to consult the Primus HSM User Guide.

    SETUP → CONFIGURATION → SECURITY → DEVICE SECURITY → CRYPO POLICY → SESSION OBJECTS
    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

5.1) Key Invalidation (Optional)
Activated Key Invalidation creates a shadow copy of the key when it is deleted.
Be careful. this prevent creation of a new key with the same key name and key id.
```
    SETUP → CONFIGURATION → SECURITY → DEVICE SECURITY → CRYPO POLICY → KEY INVALIDATION
```

5.2) Object Destruction (Optional)
If set to false, key cannot be deleted (delete will always fail)

    SETUP → CONFIGURATION → SECURITY → DEVICE SECURITY → CRYPO POLICY → OBJECT DESTRUCTION

6) Create User / Generate Setup-Password
If you have already created a user with the initial wizard you can skip this step. (the setup password has limited lifetime, default 3 days after first usage)

To create a new User:
```
    ROLES → USER → CREATE NEW USER
```
To generate a new Setup-Password:
```
    ROLES → USER → NEW SETUP PASSWORD
```
Note down the generated setup-password, It is required to setup TSB connection to the HSM.

You have now configured the HSM, created a new user and noted the setup-password. You can now continue on deploying Transaction Security Broker as a docker container.

Activate SO role:

1) Activate SO role

    hsm_so_activation

    Enter PIN for SO card (Device) in Slot 1 (4 attempts left):
    >>> ******
    PIN accepted!

    Enter PIN for SO card (Device) in Slot 3 (4 attempts left):
    >>> ********
    PIN accepted!
    
    SO-Role is successfully activated!

2) Install and setup Root Key Store
Please ensure that you have copied the obtained license file to a USB stick.
Insert the USB stick into the device before proceeding with the following step.
```
    hsm_sec_install_rke
```
```
    hsm_sec_setup_rks
```
3) Enable REST-API
To utilize the basic TSB functionality, ensure that the REST-API is enabled.
Enabling this feature grants access to execute the following endpoint.
- Service Information (Information about the service)
- Synchronous Key Operations (Synchronous operations that are directly forwarded to the HSM.
- Keys (Access to the HSM KeyStore)
- Certificate (Access to certificate mangement)

    hsm_sec_set_config crypto_access=true
    hsm_sec_set_config jce=true

5) Additional device security Settings (Optional)
Please note that for a comprehensive understanding of the following settings being configured, it is advised to consult the Primus HSM User Guide.
```
    hsm_sec_set_config session_objects=true
    hsm_sec_set_config key_import=true
    hsm_sec_set_config key_export=true
    hsm_sec_set_config key_extract=true
```
- 5.1) Key Invalidation (Optional)
  Activated Key Invalidation creates a shadow copy of the key when it is deleted.
  Be careful. this prevent creation of a new key with the same key name and key id.
```
    hsm_sec_set_config inval_keys=true
```
- 5.2) Object Destruction (Optional)
  If set to false, key cannot be deleted (delete will always fail)
```
    hsm_sec_set_config destroy_objects=true
```

6) Create User / Generate Setup-Password
If you have already created a user with the initial wizard you can skip this step. (the setup password has limited lifetime, default 3 days after first usage)

To create a new User:

    hsm_sec_create_user

    Enter new username:
    - SO >>> TEST_USERGUIDE

    Temporary setup password is: aaaaa-bbbbb-ccccc-ddddd-eeeee
    User created.

To generate a new Setup-Password:

    hsm_user_new_setup_pass

    Enter username:
    - SO >>> TEST_USERGUIDE
    
    Temporary setup password is: aaaaa-bbbbb-ccccc-ddddd-eeeee
    Successfully finished.

7) Setup User Policy

7.1) Enter user configuration

    hsm_sec_enter_user_config

    Enter username:
SO >>> TEST_USERGUIDE

7.2) User Policy

    hsm_user_set_config use_usr_cnf=true
    hsm_user_set_config key_import=false
    hsm_user_set_config key_export=false
    hsm_user_set_config key_extract=false
    hsm_user_set_config clone_modify=true
    hsm_user_set_config jce=true
    hsm_user_set_config max_partition_size=100
    hsm_user_set_config lifespan_setup_pwd=72
    hsm_user_set_config partition_ro=false
    hsm_user_set_config inval_keys=true
    hsm_user_set_config verify_block=false
    hsm_user_set_config client_api_access=true
    hsm_user_set_config mgmt_access=false
    hsm_user_set_config session_objects=true
    hsm_user_set_config external_storage=false
    hsm_user_set_config destroy_objects=true

7.1) Enable Rest-API
```
hsm_user_set_config rest_api=true
```
7.2) Enable (TSB) Workflow Engine (optional)
To utilize the enhanced multiauthorization signature workflow in TSB, ensure that the TSB Workflow engine is enabled, provided that the module is properly licensed.
Enabling this feature grants access to execute the following endpoints:
- /v1/sign, /v1/decrypt, /v1/unwrap, /v1/modify, /v1/block, /v1/request/**
```
hsm_user_set_config tsb_engine=true
```
- 7.2.1) Enable Key Authorization
  If licensed this will enable SmartKeyAttributes Usage.
```
hsm_user_set_config key_auth=true
```
7.3) Enable External Keystore
If you want start using unlimited keystore space, please contact Securosys for license. To activat the external keystore, please set:
```
hsm_user_set_config persistent_external_objects=true
```

hsm_sec_exit_user_config

Note down the generated setup-password, It is required to setup TSB connection to the HSM.

You have now configured the HSM, created a new user and noted the setup-password. You can now continue on deploying Transaction Security Broker as a docker container.

Listing current user configuration

To list parameters: use:

    hsm_sec_enter_user_config

    Enter username:
    SO >>> TEST_USERGUIDE

    SO already activated!        

    hsm_user_list_config <parameter>

Available Parameters:

client_api_access           - Allow access to the key store of this user
clone_modify                - Allow clone devices to modify the key store                                                                                      
destroy_objects             - Allow destruction of objects              
enforce_key_limits          - Limit key usage count to maximum defined by certification                                                                        
inval_keys                  - Invalidate keys instead of deleting them immediately                                                                             
jce                         - Enable JCE interface                      
key_auth                    - Allow key authorization                   
key_export                  - Allow key export                          
key_extract                 - Allow key extraction                      
key_import                  - Allow key import                          
lifespan_setup_pwd          - Time in hours a setup password is valid. 0 - OTP                                                                                 
max_partition_size          - Maximum size of the partition in MB       
mgmt_access                 - Allow management access for this user     
mscng                       - Enable MSCNG interface                    
partition_ro                - Set partition read only                   
persistent_external_objects - Allow export of objects for persistent storage                                                                                   
pkcs_pwd                    - PKCS#11 PIN for this user (write-only)    
pkcs11                      - Enable PKCS#11 interface                  
rest_api                    - Allow REST API access                     
session_objects             - Allow creation and usage of session objects                                                                                      
trust_store                 - Set all certificates as trusted           
tsb_engine                  - Allow TSB work flow engine                
use_objects                 - Allow usage of objects                    
use_usr_cnf                 - Enable user configuration                 
usrlog                      - Enable User specific log file             
usrlog_level                - User specific log level                   
usrlog_size                 - Maximum user specific log size            
verify_block                - Verify block state of keys on master 

To change user configuration:

Make sure you have enabled user configuration:
```
    hsm_user_list_config use_usr_cnf
```
- If the above command returns false
  Be careful herewidth you are ignoring the device configuration default and each property has to be set accordingly.
```
    hsm_user_set_config use_usr_cnf=true
```
- If the above command returns true
```
    hsm_user_set_config tsb_engine=true
```

Running the Initial Wizard​

Device configuration and partition setup​

Listing current user configuration​

Running the Initial Wizard

Device configuration and partition setup

Listing current user configuration