On-premise Primus HSM Connectivity Details

This page describes the factory default connectivity details for an on-premise Primus HSM and TSB/REST API deployment. As these values will differ between organizations, please contact your HSM administrator for help.

Primus HSM

To set up and configure the Primus HSM hardware, please refer to the Primus HSM User Guide.

info

Ensure that the APIs to be used are included in your HSM license. For license upgrades please contact Securosys.

Also ensure that the APIs are enabled both in the device security config and in the user/partition security config.

Default Configuration

HSM URL/IP	TCP Port JCE/JCA	TCP Port PKCS#11	TCP Port MS CNG	TCP Port High Availability	TCP Port Management (Decanus)	Partition Administration
Provided by your HSM administrator.	2300	2310	2320	2330	2340	If enabled: uses JCE, PKSC11, or MSCNG ports.

JCE API port

The Transaction Security Broker (TSB) and REST API are using the JCE API port.

Setup Password & Permanent Secret

To establish a valid connection to the HSM, an application requires a valid setup password. Your HSM administrator (specifically, the Security Officers (SO)) can issue a setup password as follows:

Primus HSM User Interface and Decanus

ROLES → USER → NEW SETUP PASSWORD

Primus HSM Console

hsm_sec_new_setup_pass

warning

The setup password has limited time validity and will expire! You should exchange the setup password for the "permanent secret" as soon as possible.

See the respective documentation for each API on how fetch the permanent secret:

• JCE/JCA
• PKCS#11
  • The PKCS#11 password is a separate password configured by your HSM administrator. It is required to fetch the permanent secret.
• MSCNG
• REST API: The TSB automatically obtains the permanent secret internally. No action is required from you.

Decanus Terminal

The Decanus is the tamper-protected remote administration terminal for the Primus HSM. It has two main applications:

• HSM Device Administration:
  • For remote administration of up to 64 Primus HSMs.
  • Connects over an IP network to the HSM management interface and TCP port.
• Partition Administration and Auditing:
  • For administration and audit of up to 64 Primus HSM partitions (Partition SO, PSO).
  • Connects to one of the API interfaces and ports (JCE, PKCS#11, or MSCNG). At least one of them must be available.
  • In a cluster: connects to the master HSM.

For both applications, see the default configuration given above.

For more details, see the Decanus Terminal User Guide. Note that remote administration and/or partition administration need to be enabled in the device security config and in the user/partition security config.

High Availability

Production environments are usually set up as a cluster of multiple Primus HSMs in order to provide high availability. This enables load balancing and failover. Devices in the cluster automatically synchronise their keystores and security settings.

In terms of connectivity this means:

• For applications: Configure your API provider with all HSMs in the cluster.
• For administrators: The HSMs must be able to connect to each other at the "High Availability" interface and port. The clones try to connect to the master at the configured "Master URL".

For more details on High Availability, please see the "High-Availability Remote Cloning" section in the Primus User Guide.

Transaction Security Broker

The Transaction Security Broker (TSB) connects to the HSM using the JCE provider. When hosting your own TSB, configure it with:

• hsm.host=<IP> - the JCE interface of your HSM
  • For high availability, you can set multiple, comma-separated hosts. See the TSB configuration guide.
• hsm.port=2300 - the JCE port of your HSM

Externally, the TSB exposes a REST API that applications can interact with.

• Endpoint: defaults to http://localhost:8080
• Authentication: JWT, mTLS, or API keys. Depends on how the TSB is configured.

Contact your TSB administrator for the production endpoint that you should connect to.

Applications usually only connect to a single REST API endpoint. For high availability, you should employ standard mechanisms, such as running multiple TSB instances that applications access through a load balancer or using round-robin DNS.