Skip to main content

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.

Simple TSB architecture diagram

Features​

The TSB has four main feature areas:

REST-to-JCE Translation Layer​

The TSB allows applications to perform cryptographic operations and key management operations on the HSM over a REST API. For example, you can use HSM keys to encrypt/decrypt, sign/verify, wrap/unwrap. You can also compute keyed hashes with HMAC and read/write data objects. In this case, the TSB functions as a simple translation layer from REST to JCE.

This feature is controlled by the REST_API license.

SKA Workflow Engine​

The TSB can also function as a workflow engine for Smart Key Attribute (SKA) approval workflows.

In this case, the TSB is responsible for managing the state of an SKA key operations: receiving an SKA key usage request, generating pending tasks that approver applications can poll, collecting signatures from all approvers, and eventually forwarding the complete approvals to the HSM. This requires keeping the temporary state that is needed while an SKA operations is pending.

This feature is controlled by the TSB_ENGINE license.

SKA Approver Management​

The TSB can also function as the central place to manage SKA approvers.

This includes generating approver key pairs as PKCS#12 bundles that can be injected into approver applications, such as the Securosys Authorization App. The TSB can also back up the encrypted approver key pairs, allowing recovery when approvers use their phone. These backups are stored in a database.

This feature is controlled by the TSB_ENGINE license.

Helper Functions​

The TSB also provides helper functionality that is commonly needed when working with cryptographic options, but that are not exposed by the JCE or PKCS#11 APIs. For example, the TSB can create Certificate Signing Requests (CSRs), issue certificates, and create self-signed certificates.

This feature is controlled by the REST_API 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.

For all other features, the TSB merely acts as a translation/forwarding layer to the HSM. All cryptographic operations are executed by the HSM. SKA policy enforcement also happens inside the HSM.

What's next?​

Get started withCloudHSM for free.
Other questions?Ask Sales.
Last updated on
Feedback
Need help?