Installation

danger

This page describes how to install VaultCode on an external Docker host, outside of the HSM. This is intended for testing purposes only!

Start by downloading the example configuration files. The ZIP file contains examples for the docker-compose.yml and the application.yml files. Extract the ZIP file to a directory on your Docker host.

Docker Compose

First, use Docker Compose to define the containers that need to run.

Below is an example of the docker-compose.yml file. Copy this example to your host and fill it out with your custom values.

services:
  vaultcode_db:
    image: bitnami/postgresql:latest
    container_name: "vaultcode_db"
    volumes:
      - vaultcode_db:/bitnami/postgresql
    environment:
      # REPLACE with your credentials
      - POSTGRES_USER: replace-me_db-username
      - POSTGRES_PASSWORD: replace-me_db-password
      - POSTGRESQL_POSTGRES_PASSWORD: replace-me_admin-db-password
      - POSTGRES_DB: vaultcode

  vaultcode:
    container_name: "vaultcode"
    image: securosys.jfrog.io/vault-code/securosys-vault-code:latest
    #image: securosys.jfrog.io/vault-code/securosys-vault-code_arm64:latest
    restart: always
    volumes:
      - "./config:/app/vaultcode/config"
      - "./logs:/app/vaultcode/logs"
    environment:
      - SPRING_PROFILES_ACTIVE=local                    # REPLACE, based on the environment you are running
      - ALLOWED_DOMAINS=localhost                       # REPLACE with a list of allowed domains
      - ALLOWED_IPS=0.0.0.0                             # REPLACE with a list allowed IPs
      - logging.config=/app/vaultcode/config/logback.xml # Choose log level inside file
    depends_on:
      - vaultcode_db

Simulator mode

In simulator mode, set SPRING_PROFILES_ACTIVE=simulator.

Application config

The ZIP downloaded above also contains multiple application-xyz.yml example files in the config-files folder. For running with a connected HSM Partition, use the application-local.yml file. For running in simulator/demo mode without an HSM Partition, use the application-simulator.yml file.

Copy the relevant application-xyz.yml file and fill it out with your custom values.

Below is an example of the application-local.yml. See the files shipped in the ZIP file for the full reference, in particular see the inline comments.

spring:
  datasource:
    url: jdbc:postgresql://vaultcode_db:5432/vaultcode?allowPublicKeyRetrieval=true&useSSL=false
    username: replace-me_db-username                             # REPLACE according to the `POSTGRESQL_USERNAME` in the docker-compose.yml file
    password: replace-me_db-password                             # REPLACE according to the `POSTGRESQL_PASSWORD` in the docker-compose.yml file

hsm:
  host: 'ch01-api.cloudshsm.com,ch02-api.cloudshsm.com'          # REPLACE with the hsm URL or IP
  port: '2400'                                                   # REPLACE with HSM JCE-Port
  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
  proxyUser: 'primusdev_user'                                    # used for CloudsHSM access
  proxyPassword: 'primusdev_password'                            # used for CloudsHSM access
  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: false                                  # TSB request is from the same HSM as VaultCode
  statefulDatabaseExecutions: false                              # If true, loaded Executable can store persistent data in the DB
 
  #Default executable time limit. It can be overwritten using timeout parameter on /execute endpoint
  defaultExecutableTimeout: 60s
  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

tip

VaultCode is a Spring Boot application. In Spring Boot the config naming scheme is application-{profile}.yml.

You should always specify configurations using such as profile, and then specify the profile in the SPRING_PROFILES_ACTIVE environment variable. Don't override the base configuration.

Simulator mode

When running in simulator mode:

• Use the application-simulator.yml example.
• Set vaultcode.demo to true. Then VaultCode will ignore the hsm: section.

  vaultcode:
    demo: true
    # other lines omitted

• Alternatively, delete the hsm: section.

Note that in simulator mode, the keys do not have an attestation when calling GET /api/v1/get_public_key (see below).

Start the container

Log in to the Securosys container registry:

docker login securosys.jfrog.io -u robot.reader

You will be prompted for a password. You can find the password in the Downloads section.

Then start the containers:

docker compose up --detach

Onboard the output key to the TSB

If you want to use VaultCode for automated approval of SKA tasks, you need to onboard the output of VaultCode to the Transaction Security Broker (TSB) as an approver key.

To do this, follow the steps in the production installation guide.

What's Next

Congratulations, you have set up VaultCode on an external host! You can now begin your testing by loading and running custom executables.

• Install VaultCode in production.
• Test your custom JAR executables in a developer environment or a CI/CD pipeline.
• Read the samples:
  • Check out the tutorial on how to automatically sign a certificate request with VaultCode.
  • Look into the Blockchain use case to automatically approve transactions below a certain amount.
  • Review other executable samples provided by Securosys.