REST API & Transaction Security Broker

To perform cryptographic operations, applications use APIs to interact with the Primus HSM. The Securosys Primus HSM provides three APIs natively: Java JCE, Microsoft CNG, and PKCS#11. However, many modern applications prefer REST APIs. REST APIs are language-agnostic, since they generally run over HTTP(S). A REST API also doesn't require the installation of a client-side API provider library.

To address this need, Securosys provides the Transaction Security Broker (TSB).

Architecture

The TSB is a Java application that internally communicates with the Primus HSM over JCE. Externally, the TSB exposes a REST API that applications can consume.

Usage Modes

The TSB can be used as:

• A translation layer, or
• As a workflow engine.

The TSB allows applications to perform cryptographic operations (such as signing and decrypting) and key management operations on the HSM over a REST API. In this case, the TSB functions as a simple translation layer from REST to JCE. This feature is controlled by the REST-API license.

The TSB can also function as a workflow engine for Smart Key Attribute (SKA) workflows. In this case, the TSB is responsible for managing the state of an SKA key operations, such as managing approvers, collecting signatures from all approvers, and forwarding them to the HSM. This feature is controlled by the TSB license.

Deployment Modes

The TSB is deployed as a containerized application that uses its own database and connects to an HSM. All cryptographic operations are performed by the HSM, while the TSB orchestrates and forwards requests - ensuring that the confidentiality and integrity protections of the HSM remain intact. Each TSB instance connects to a single HSM partition, enabling scalability and load balancing by deploying multiple TSB instances that connect to the same partition. The partition can be served by an HSM cluster for high availability.

The TSB is distributed as a Docker container image. There are two main ways to deploy this container:

• Outside of the HSM:
  • This is the traditional deployment mode. It deploys the TSB as a Docker container on an outside system, such as a Kubernetes cluster.
  • This enables scaling the TSB independently of the HSM cluster, by scaling the number of TSB containers.
  • In CloudHSM, Securosys deploys and manages such a TSB deployment for you.
• Inside the HSM:
  • With VaultContainers it is possible to run Docker containers inside the Primus HSM. This makes it possible to run the TSB inside the Primus HSM. No external Docker host is required.

How you should deploy the TSB depends on your environment and operational requirements. Here is a comparison:

Docker

• Purpose: Lightweight, standalone deployment for evaluation, development, or isolated on-premise environments.
• Ideal for: Quick setup, testing SKA workflows, development environments, and small-scale production deployments.
• Setup: Deploy TSB as a container using the Docker quickstart guide, then configure authentication and select a TSB application profile.

Kubernetes

• Purpose: Scalable, production-grade deployment for enterprise or cloud environments with high availability.
• Ideal for: Enterprise production environments and deployments requiring automated orchestration, scaling, and self-healing capabilities.
• Setup: Deploy TSB using the official Helm Charts, then configure authentication and select a TSB application profile.

VaultContainers

• Purpose: Controlled, tamper-protected deployment for high-security on-premise environments.
• Ideal for: High-security deployments that need a tamper-proof environment or that want every container image update to go through a 4-eyes review by the HSM Security Officers. Also for small-scale deployments that don't want to maintain a separate server cluster for hosting Docker containers.

Security Considerations

The TSB can manage and back up the approvers and their approver keys. In this case, the TSB becomes relevant for security, in particular for the access control to the approver keys (and hence the SKA keys). To manage these, the TSB creates its own keys on the HSM partition, acting like a normal application (from the view of the HSM). For details, see the SKA documentation.

What's next?

• Follow the quickstart to get an overview of how you can use the REST API.
• For an on-premise setup: follow the installation guide to install the TSB.
• Explore the Swagger-style REST API documentation.
• Use Smart Key Attributes (SKA) and the TSB workflow engine to build multi-authorization flows.