Configure the HSM

Begin by configuring the on the HSM, preparing the Partition Security Config, and defining the containers.

Create a Partition

VaultCode requires an HSM Partition to store its key pairs in.

First, create the Partition as you usually would (see Section 5.5 "User (Partition)" of the Primus User Guide).

UI

ROLES → USER → CREATE

Serial

hsm_sec_create_user

Securely store the setup password, as you will need it later. If you are using an existing Partition, create a new setup password:

UI

ROLES → USER → NEW SETUP PASSWORD

Serial

hsm_user_new_setup_pass

Enable Partition-Level Options

Enable VaultCode in the "User Security" settings of the Partition. Also enable the related required settings.

UI

SETUP → CONFIGURATION → SECURITY → USER SECURITY → (user) → (setting)

Enable the following settings:

• User Configuration
• JCE
• VaultCode

Optionally, when using the TSB and/or SKA, also enable:

• Key Authorization
• REST API access
• TSB Workflow Engine

Serial

hsm_user_enter_config

hsm_user_list_config use_usr_cnf

hsm_user_set_config use_usr_cnf=true
hsm_user_set_config jce=true
hsm_user_set_config vault_code=true

# Optional, when using the TSB and/or SKA
hsm_user_set_config rest_api=true
hsm_user_set_config tsb_engine=true
hsm_user_set_config key_auth=true

hsm_user_exit_config

Export the Security Config

Export the security config (.sconfig file) from the HSM.

Transfer the USB stick with the file to your laptop. You will need to edit this file in the next step.

UI

SETUP → CONFIGURATION → IMPORT/EXPORT → SECURITY CONFIG EXPORT

Serial

hsm_sec_export_config

See also Section 3.8 "Configuration with XML Export and Import" in the Primus User Guide.

Define the Containers

Next, define the containers that you want the VaultContainers subsystem to run. You should have containers for VaultCode and the database, and possibly one for the TSB.

Below is an example of the vault_containers section of an exported .sconfig file. Edit this file according to your needs.

<vault_containers>
    <active>enabled</active>
    <interface>1</interface>

    <container id="database-1" name="database">
        <image>database</image>
        <port/>
        <auto_start>enabled</auto_start>
        <config/>
    </container>

    <container id="tsb-1" name="tsb-rest-api">
        <image>tsb</image>
        <port>8081</port>
        <auto_start>enabled</auto_start>
        <config>application-tsb-automated-approval.yml</config>
    </container>

    <container id="vault-code-1" name="vault-code">
        <image>vault-code</image>
        <port>8082</port>
        <auto_start>enabled</auto_start>
        <config>application-vault-code-hsm.yml</config>
    </container>

</vault_containers>
<!-- other lines omitted -->

These values only define the names of the container image and the application config files. In a later step, you will load the actual files onto the HSM.

XML tag	Meaning
<container id="value" name="container-name">	ID and name for the container. For the ID, see the notes below. The container name can be freely chosen.
<image>	Name of the container image file on the USB stick.
<config>	Name of the container config file on the USB stick.
<auto_start>	Whether VaultContainers should automatically start this container.
<port>	Port to the outside world over which the container should be reachable, if any. VaultContainers will set up the port binding from outside to inside the container. The container image should document the port inside the container with an EXPOSE statement.
<interface>	Interface on which all containers will be reachable from the outside. One of the physical HSM network interfaces. The VaultContainers runtime will internally bridge this to the containers.

info

The ID must be of the form <type>-<counter>, where <type> is one of database, tsb, vault-code and where <counter> must be an integer starting at 1.

This is important, because VaultContainers uses this to determine the type of the container.

Import Container Definitions

Having edited the .sconfig file on your laptop, import it back into the HSM.

UI

SETUP → CONFIGURATION → IMPORT/EXPORT → SECURITY CONFIG IMPORT

Serial

hsm_sec_import_config

tip

Writing and loading the .sconfig file only defines the containers. It does not yet load the actual container image files (<image>) and config files (<config>), nor does it start the containers. All of this will be done in a subsequent step. However, the <image> and <config> names are important, and they will be needed later!