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 "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 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 "Configuration with XML Export and Import" in the Primus User Guide.

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 vault_containers section of an exported .sconfig file. Export the .sconfig file from your HSM, edit the file according to your needs, and import it again.

<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-automated-approval.yml</config>
    </container>

    <container id="vault-code-1" name="vault-code">
        <image>vaultcode</image>
        <port>8082</port>
        <auto_start>enabled</auto_start>
        <config>application-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="value">	ID and name for the container. The ID is automatically set by the HSM, and must not be manually set or changed. The 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.

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.

hsm:
  host: 'host.primus-hsm'                                       # Don't change - this is the equivilent of localhost when running inside the HSM.
  port: '2510'                                                  # 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 

tip

From other Spring Boot based applications, you may be used to setting the spring.datasource section in the application config file. When running inside the HSM in VaultContainers, you do not need to set this section. The VaultContainers runtime automatically inject these values, to specify the connection parameters for the local database that is also running in VaultContainers.

info

The normal default JCE port is 2300. However, inside the HSM, JCE is reachable from VaultContainers via port 2510. This port will never be reachable from the outside of the HSM.