Deploy Services

This section explains how to deploy the web services that are needed for integrating Primus HSM with Fireblocks Key Link. Recall from the architecture section in How It Works that you need to deploy three services:

• Securosys Transaction Security Broker (Primus REST API Provider)
• Securosys Custom Server
• Fireblocks Key Link Agent

Step 1: Deploy the REST API Provider / TSB

You need an instance of the Transaction Security Broker (TSB) running somewhere. The TSB provides a REST API, and can act as a simple REST-to-JCE proxy. Additionally, the TSB can also orchestrate the SKA workflow state.

For on-premise Primus HSMs you need to host the TSB yourself. Follow the TSB installation guide to deploy it.

Step 2: Deploy the Securosys Custom Server

Obtain the download credentials from the Securosys Support Portal.

Log in to the Securosys Container Registry, using the password you just obtained:

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

Define Application Config

Create a file application.yml with the following contents:

spring:
  datasource:
    url: jdbc:mariadb://localhost:3306/customserver
    username: customserver
    password: changeme

tsb:
  tsbRestApi: 'https://sbx-rest-api.cloudshsm.com'
  tsbAccessToken: '<JWT Token>'

custom-server:
  fireblocksAgentConfiguration:
    # Choose a secret value. Must be non-empty.
    # Set the CUSTOMER_SERVER_AUTHORIZATION envvar in the Fireblocks Key Link Agent to the same value.
    apiAuthorization: 'my-secret-api-key-123'

swaggerUI.enabled: true

This file defines the configuration options the Securosys Custom Server will use. It tells the Custom Server which database it should use, where it can reach the TSB, and how it should authenticate against APIs of the TSB and the Fireblocks Key Link Agent.

For a full list of all available options, see the template.yml example on GitHub.

Define Docker Compose

In this guide, we will use Docker Compose to define and run the containers. You can also use another container runtime, such as Kubernetes.

Create a file docker-compose.yml with the following contents:

services:

  fireblocks_custom_server_db:
    image: mariadb:11.8
    container_name: fireblocks_custom_server_db
    expose:
      - "3306"
    volumes:
      - ./fireblocks_custom_server_db:/var/lib/mysql
    environment:
      # REPLACE with your credentials
      MYSQL_ROOT_PASSWORD: changeme
      MYSQL_DATABASE: customserver
      MYSQL_USER: customserver
      MYSQL_PASSWORD: changeme
    restart: unless-stopped

  fireblocks_custom_server:
    image: securosys.jfrog.io/fireblocks/external-key-store-application:latest
    container_name: fireblocks_custom_server
    depends_on:
      - fireblocks_custom_server_db
    ports:
      - "8080:8080"
    volumes:
      # place for application configuration files
      - ./config-files:/etc/app/config:ro
      # output folder of e.g. logfiles
      - ./output:/etc/app/output
    environment:
      - logging.config=/etc/app/config/log/logback.xml
    restart: unless-stopped

Create the directories that the Docker Compose file uses as volumes to persist data:

mkdir ./fireblocks_custom_server_db ./config-files ./output

Start the Containers

Next, start the containers:

docker compose up --detach

Step 3: Deploy the Fireblocks Key Link Agent

Deploy the Fireblocks Key Link Agent as explained in the Fireblocks documentation.

In the Fireblocks Key Link configuration:

• Set the CUSTOMER_SERVER_URL to a URL that points to the Securosys Custom Server you have deployed above. For example, if you placed them into the same Docker network: http://fireblocks_custom_server:8080
• Set the CUSTOMER_SERVER_AUTHORIZATION variable to the same value as custom-server.fireblocksAgentConfiguration.apiAuthorization (in the Securosys Custom Server configuration).

Next Steps

You have now deployed the web services needed for integrating Primus HSM with Fireblocks Key Link. Next, you need to create the validation keys and signing keys and add them to your Fireblocks workspace.