Configure the Execution Partition

Recall from the How It Works section that VaultCode can be configured with two Partitions: The Primary Partition and the Execution Partition. The credentials for the Execution Partition are forwarded to the executable, so that it can leverage the HSM keystore.

This page describes how to configure your application-vault-code-xyz.yml to grant access to an Execution Partition.

Via JCE

The first option is to provide Partition credentials for JCE. This is the recommended way for JAR executables.

Inside the HSM

When VaultCode runs inside the HSM on VaultContainers, both Partitions must be on the same HSM. JARs are not allowed to make network requests to outside hosts. Therefore, please omit the host, port, and proxy fields.

hsm:
  primary:
    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'

  execution:
    user: 'replace-me_hsm-username'
    setupPassword: 'replace-me_hsm-setupPassword'
    encryptionPassword: 'replace-me_db-encryptionPassword'
    attestationKeyName: 'attestation-key'

vaultcode:
  allowExecutableToConnectToPartition: true

Outside the HSM

When VaultCode runs outside the HSM, please additionally specify the host and port of the HSM. For CloudHSM, also specify the proxy username and proxy password.

hsm:
  primary:
    host: 'ch01-api.cloudshsm.com,ch02-api.cloudshsm.com'       # REPLACE with the hsm URL or IP
    port: '2300'                                                # 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: 'replace-me_proxy-username'                      # used for CloudsHSM access
    proxyPassword: 'replace-me_proxy-password'                  # used for CloudsHSM access
    attestationKeyName: 'attestation-key'

  execution:
    host: 'ch01-api.cloudshsm.com,ch02-api.cloudshsm.com'
    port: '2300'
    user: 'replace-me_hsm-username'
    setupPassword: 'replace-me_hsm-setupPassword'
    encryptionPassword: 'replace-me_db-encryptionPassword'
    proxyUser: 'replace-me_proxy-username'
    proxyPassword: 'replace-me_proxy-password'
    attestationKeyName: 'attestation-key'

vaultcode:
  allowExecutableToConnectToPartition: true

Flat version

For the Primary Partition, VaultCode supports both the nested version (shown above) and the flattened version (shown below). The nested version is more explicit, while the flattened version is aligned with other Securosys applications (such as the TSB).

hsm:
  user: 'replace-me_hsm-username'
  setupPassword: 'replace-me_hsm-setupPassword'
  # ...

  execution:
    user: 'replace-me_hsm-username'
    setupPassword: 'replace-me_hsm-setupPassword'
    # ...

vaultcode:
  allowExecutableToConnectToPartition: true

Via REST (TSB)

The second option is to provide credentials for the REST API (TSB). This is the recommended way for WASM executables.

For this to work, you first need to deploy a TSB instance. When running VaultCode inside the HSM, you must deploy the TSB inside the HSM as well, since network requests outside the HSM are denied.

Configure your application-vault-code-xyz.yml as follows:

tsb:
  execution:
    restApi: 'https://sbx-rest-api.cloudshsm.com'
    # restApi: 'http://tsb-rest-api-1'              # When running inside VaultContainers: use the container name

    appName: 'vaultcode-instance-1'                 # Name to identify requests in TSB logs
    auth: 'TOKEN'                                   # NONE, TOKEN, CERT
    bearerToken: '${TSB_BEARER_TOKEN}'              # JWT to authenticate to TSB

vaultcode:
  allowExecutableToConnectToTsb: true
  execution:
    wasm:
      allowHttp: true                               # Enable HTTP for trusted WASIp2 executables
      allowSockets: true                            # WASIp2 socket adapter to resolve local networking