Configure the containers

Begin by configuring the on the HSM, to prepare the Partitions and to define 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 of the Primus User Guide E25).

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 VaultCode for the Partition

VaultCode needs to be explicitly in the "User Security" settings of that Partition. Prepare a device security configuration (as an .sconfig file) with the following structure:

<crypto_user state="enabled">
        <user_name>VAULTCODE_USER</user_name>
        <jce_allowed>enabled</jce_allowed>
        <rest_api>enabled</rest_api>
        <tsb_engine>enabled</tsb_engine>
        <vault_code>enabled</ate_enabled>
</crypto_user>
<!-- other lines omitted -->

You can export the current configuration as a template, edit it locally, and then import it again. See section 3.8 of the Primus User Guide E25.

UI

SETUP → CONFIGURATION → IMPORT/EXPORT → SECURITY CONFIG EXPORT
SETUP → CONFIGURATION → IMPORT/EXPORT → SECURITY CONFIG IMPORT

Serial

hsm_sec_export_config
hsm_sec_import_config

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 container_platform section of .sconfig file. Change this according to your setup and add it to your local .sconfig file. Import the resulting .sconfig file as described above.

<container_platform>
    <active>enabled</active>
    <interface>1</interface>
    <vault_containers>
        <container name="database">
            <image>database</image>                                 <!-- name of DB container file on your USB -->
            <port/>
            <auto_start>enabled</auto_start>
            <config/>
        </container>
        <container name="tsb">
            <image>tsb</image>                                      <!-- name of TSB container file on your USB -->
            <port>8081</port>                                       <!-- external port for swagger UI -->
            <auto_start>enabled</auto_start>
            <config>application-automated-approval.yml</config>     <!-- name of TSB config file on your USB -->
        </container>
        <container name="vaultcode">
            <image>vaultcode</image>                                <!-- name of VaultCode container file on your USB -->
            <port>8082</port>                                       <!-- external port for swagger UI -->
            <auto_start>enabled</auto_start>
            <config>application-hsm.yml</config>                    <!-- name of VaultCode config file on your USB-->
        </container>
    </vault_containers>
</container_platform>
<!-- 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.

Define the application configuration

In the same .zip, you will find multiple application.yml configuration files under the config-files folder. The sample application-hsm.yml file is intended for running inside the HSM. Below is a breakdown of the core details to consider, but the file itself contains the full default list.

spring:
  datasource:
    url: jdbc:postgresql://vaultcode_db:5432/securosys?allowPublicKeyRetrieval=true&useSSL=false
    username: database_user
    password: database_password

hsm:
  host: 'host.primus-hsm'                                       # Don't change - this is the equivilent of localhost when running inside the HSM.
  port: '2300'                                                  # Don't change - port for communicating with HSM
  user: 'replace-me_hsm-username'                               # REPLACE with your HSM username (PartitionName)
  setupPassword: 'replace-me_hsm-setupPassword'                 # REPLACE with your HSM SetupPassword
  encryptionPassword: 'replace-me_db-encryptionPassword'        # REPLACE it is used to encrypt the hsm user secret, stored in the database
  attestationKeyName: 'attestation-key'

vaultcode:
  certificates:
    whitelist:                                                  # PEM certificate that allowlists signed executabes
       - |
          --BEGIN--
          PEM HERE
          --END--
  fingerprint:                                                  # Fingerprint of allowed .jar executable. Empty = allow all
  onlyInternalExecutions: true                                  # Set to true for Inside HSM, TSB request is from the same HSM as VaultCode
  statefulDatabaseExecutions: false                             # Store arbitrary data that VaultCode can use; default is false
  keys:
    output:
      label: output_key_vaultcode                               # key name for output signature
    evidence:
      label: environment_key_vaultcode                          # key name for environment signature
    timestamp:
      label: timestamp_iso_key_vaultcode                        # key name for timestamp signature
    encrypt:
      label: encrypt_key_vaultcode                              # key name for encrypt execution_code

# Set port:8080, TSB sends requests on this port when 'onlyInternalExecutions: true'. For inside HSM use only.
server:
  port: 8080