REST API – Configuration

After setting up your REST API Docker container, you can fine-tune its behavior by modifying the application-local.yml properties file. This guide provides a detailed overview of the available configuration options, helping you adapt the REST API to your development or deployment needs.

Before proceeding, make sure:

The REST API is up and running.
The database is properly configured.
You have completed the REST API Setup (Docker) guide.

What You'll Learn

How to understand and use Spring profiles for environment-specific configurations
How to setup API Authentication
How to set up HSM load-balancing and failover behavior
How to customize REST API behavior, such as connection timeouts and retry logic
How to control the maximum number of allowed connections
How to configure SKA (Smart Key Attributes)

REST API Profiles

The REST API supports multiple profiles, each tailored to a specific deployment scenario. Selecting the appropriate profile ensures the API behaves correctly based on your infrastructure and security requirements.

`local` (Default)

Intended for on-premise deployments within private networks such as VPNs.
Connects to a single HSM partition.
Ideal for development and environments where the REST API has direct access to the HSM.

📄 Configuration template: config-files/application-local.yml

`access-token` (JWT)

Enables JWT-based authentication using a whitelisted client certificate.
Supports connecting to multiple HSM partitions, selected dynamically based on the JWT token.
Best suited for cloud environments or multi-tenant deployments requiring secure and scalable access control.

📄 Configuration template: config-files/application-local-access-token.yml

`standalone` (Air-Gapped)

Designed for offline environments with no direct HSM access.
Does not connect to the HSM or its keystore.
Can generate SKA Challenges (ApprovalToBeSigned), useful for workflows involving SKA keys where signing occurs in a separate, secure step.
Ideal for air-gapped deployments or secure signing operations in regulated environments.

📄 Configuration template: config-files/application-standalone.yml

API Authentication

The REST API supports multiple authentication methods to secure access, depending on your deployment needs:

mTLS – Mutual TLS using client certificates
JWT – JSON Web Token authentication with certificate-based validation
API Keys – Static token-based access control for trusted clients

For detailed setup instructions, refer to the respective guides:

HSM Load-Balancing

The REST API supports automatic load-balancing and failover across multiple HSMs by specifying multiple hosts in the configuration. The actual key replication and high availability are handled at the HSM cluster level, while the REST API acts as a smart client, choosing how to connect.

You can configure the client behavior in one of the following modes:

Random – Requests are randomly distributed across the available HSMs.
Prioritized – Always connects to the first HSM; uses others as fallback.
Weighted – Random distribution with defined weight per HSM.

Configure Load Balancing

Open the configuration file:

nano config-files/application-local.yml

Then update the hsm.host value based on your desired strategy.

Load-Balancing Modes

Mode	Example Configuration	Description
Random	`ch01-api.cloudshsm.com,ch02-api.cloudshsm.com`	Unweighted round-robin style load-balancing
Prioritized	`ch01-api.cloudshsm.com;ch02-api.cloudshsm.com`	Always tries first HSM; others act as failover
Weighted	`ch01-api.cloudshsm.com(.8),ch02-api.cloudshsm.com(.2)`	Random load-balancing with assigned connection weights

hsm:
  host: 'ch01-api.cloudshsm.com,ch02-api.cloudshsm.com'

🔧 For weighted mode, use parentheses to assign a probability factor (e.g., (.8) = 80%).

Implications When Master HSM is Unreachable

In a High-Availability PrimusHSM Cluster, if the master HSM becomes unreachable, the following behaviour applies:

Still Possible:

Key creation: creating keys on clones (if master in not available)
Key Usage: (e.g., sign, verify, encrypt, decrypt operations)
Key Store enumeration

List of working API-Endpoints (on clones)

All Approval Tasks endpoints
All Request endpoints
All Synchronous Request endpoints
Export Key [POST] /v1/key/explort/plain
Import Key [POST] /v1/key/import/plain
Fetch Key-Attributes [POST] /v1/key/attributes
Key-Attestation [POST] /v1/key/keyAttestation
Address Generation [POST] /v1/key/address
Key-Derivation [POST] /v1/key/derivedKey
Data Object creation [POST] /v1/dataObject

Not Possible:

Keystore modifications: (e.g., delete key, change password)
Smart Key Attribute operations (if verify_block=true) these are operations that require coordination with the master HSM

List of non working API-Endpoints (on clones)

All Certificate endpoints
All Approval Management endpoints /v1/approverManagement
Verify on Temporary Derived Keys
Blocking / Unblocking SKA-Keys [POST] /v1/block, /v1/unblock
Modify Key [POST] /v1/modify
Delete a key: [POST] /v1/key/deleteKey
Change key password: [POST] /v1/key/changePassword
Delete a data object: [DELETE] /v1/dataObject/{dataObjectName}
Import Private/Public/Certificate (if it already exists)
- [POST] /v1/key/import/plain
- [POST] /v1/certificate/import/plain

API Behavior When Master Is Down

When a non-supported operation is attempted during a master disconnect, the REST API responds with:

{
  "errorCode": 701,
  "reason": "res.error.in.hsm",
  "message": "HSM error: status: MasterNotReachable; for key TESTKEY2025-05-06_19-39-44.70784067305833"
}

Special Case: Smart Key Attributes (SKA)

If the security configuration on your HSM is:

SO >>> hsm_sec_list_config verify_block=true

Then SKA-related operations require master availability because the clone must check if a SKA key is blocked.

Allow Offline SKA Requests (on Clones)

To allow SKA-related requests even when the master is offline, update the security configuration:

SO >>> hsm_sec_list_config verify_block=false

⚠️ Disabling verify_block means blocked SKA keys are still usable if the master is down.

Additional HSM Configuration Parameters

In addition to hsm.host, the application-local.yml file provides several other configuration options to control how the REST API interacts with the HSM. These include authentication credentials, timeouts, key references, and optional proxy settings for CloudHSM environments.

hsm:
  port: '2300'                             # REPLACE with the HSM's JCE port
  user: replace-me_hsm-username            # REPLACE with your HSM username (PartitionName)
  setupPassword: replace-me_hsm-setupPassword  # REPLACE with your HSM setup password
  encryptionPassword: replace-me_db-encryptionPassword  # Used to encrypt the HSM user secret stored in the database

  clusterFailoverGraceTimeMilliSeconds: 5000 # Timeout in milliseconds for connection failover

  #proxyUser: replace-me_proxy-username    # Optional: used for CloudHSM access via proxy
  #proxyPassword: replace-me_proxy-password # Optional: used for CloudHSM access via proxy

  timeout: 1800                            # Time (in seconds) after which all idle/pending HSM connections are closed
  maxTimeDifferenceToHsm: 100              # Optional: Logs a warning if local time differs from HSM time by more than X seconds (default is 30)

  attestationKeyName: 'attestation-key'    # Name of the key used for attestation processes
  timestampKeyName: 'timestamp-key'        # Name of the key used for generating timestamps
  #rfcTimestampKeyName: 'rfc-timestam-key' # Optional: Licensed feature for RFC-compliant timestamping

  useExternalKeyStore: false # optional, storing encrypted keys in database
  useKeyReplicationService: false # optional, using builtIn key replication technology with external KeyStore: requires: 'spring.slaveDatasource...' to be configured.
  persistRequestResults: true # temporarily persists the results of an approved sign and decrypt-request in the database, default is true  
  standalone: false # by default is false, if it is true then the TSB without HSM is enabled

Attribute Description

Attribute	Description
`host`	The hostname or IP address of the HSM.
`port`	The port of the JCE API on the HSM. Default: `2300`.
`user`	The case-sensitive name of the HSM user (partition).
`setupPassword`	Temporary setup password (29-character alphanumeric, dash-separated): `FXAJX-XWVQ3-DC0O5-3SLQF-LJ9L3` 🔐 Validity: • On-Prem HSM: 3 days • CloudHSM: 1 week • Developer Account: 1 year This password is used to retrieve or update a permanent secret during initial setup. Provided by Securosys.
`encryptionPassword`	Password used to encrypt the user secret retrieved from the HSM. Should be high-entropy and free of special characters.
`clusterFailoverGraceTimeMilliSeconds`	Timeout (in milliseconds) for connection failover during login, including hello exchanges. Default: `300000` (5 minutes).
`proxyUser` / `proxyPassword`	(Optional) Credentials for proxy access (e.g., when connecting to CloudHSM through a proxy).
`timeout`	Time (in seconds) after which all idle/pending HSM connections are closed.
`attestationKeyName`	Required. Name of the attestation key generated at startup. Used to assert the origin of keys and the HSM environment. ⚠️ Requires EXTENDED_KEY_ATTRIBUTES (Attestation) license.
`timestampKeyName`	Required. Name of the timestamp key, which is generated at startup Used to sign a timestamp
`rfcTimestampKeyName`	(Optional) Name of the RFC 3161-compliant timestamp key. Used for signature and certificate validity assertions.
`maxTimeDifferenceToHsm`	Threshold in seconds to detect clock drift. Logs a `WARN` if system time differs from HSM time beyond this value. Default: 30 seconds.
`useExternalKeyStore`	Enables encrypted key storage in the database. Default: `false` ⚠️ Requires additional license.
`useKeyReplicationService`	Enables built-in key replication instead of SQL clustering logic. Requires configuration of a secondary datasource. Default: `false` ⚠️ Requires additional license.
`persistRequestResults`	Temporarily stores results of approved signing or decryption requests in the database. Default: `true`.
`standalone`	Enables Standalone (Air-Gapped) mode when set to `true`. In this mode, the REST API runs without connecting to the HSM. Default: `false`.

Webserver Configuration

You can tune the embedded Tomcat server to handle higher or lower concurrency depending on your workload.

Increase Maximum Threads

server:
  tomcat:
    max-threads: 200

note

server.tomcat.max-threads: Defines the maximum number of threads that can be used to process incoming HTTP requests.
Default: 10
Increasing this value may improve performance under high load, but also increases resource usage.

💡 For REST APIs with high concurrency or large-scale deployments, you may consider increasing this value along with proper container resource limits.

warning

When tuning server.tomcat.max-threads, the database connections have to be increased as well, otherwise the database container cannot handle the load.

spring:
  datasource:
    maximumPoolSize: 150    

TLS Configuration

Enable HTTPS for secure communication with the REST API by configuring the tls section in your application-local.yml file.

Follow the Configure TLS (HTTPS) guide which explains the https setup in detail.

## HTTPS (TLS) CONFIGURATION
tls:
  # set to true if you want to use TLS (https)
  enabled: false
  keyStore: 'file:/etc/app/config/tls/securosys-ska-server.p12'
  keyStorePassword: secret

note

The keyStore must contain a valid server certificate and private key.
Make sure the file path is accessible inside the container if using Docker.
TLS should be enabled for production environments to ensure encrypted communication.

mTLS Configuration

Enable mutual TLS (mTLS) to require client authentication using trusted certificates. This is useful for environments where secure, certificate-based access control is required.

Follow the Configure mTLS guide which explains the setup in detail.

Configure the server.ssl section in your application-local.yml:

# Trust-Store configuration (m)TLS
server:
  ssl:
    # add client certificates and/or CA's to the trustStore if you want mTLS, otherwise comment out.
    trust-store: 'file:/etc/app/config/mtls/securosys-ska-truststore-server.jks'
    trust-store-password: secret # yourTrustStorePassword
    trust-store-type: jks

    # Client authentication mode (choose one):
    # - need: client authentication is mandatory
    # - want: client authentication is optional but preferred
    # - none: client authentication is disabled
    client-auth: need

note

The trust store should contain public certificates of the clients or CA certificates that issued them.
File paths must be accessible within the container.
To fully enable mTLS, client-auth must be set to either need or want.

✅ Recommended for production environments requiring secure, certificate-authenticated communication.

Smart Key Attributes Configurations

⚠️ Note: This section requires an additional license to enable Smart Key Attributes (SKA) workflow features.

These optional configuration settings allow for advanced workflow management, background service scheduling, and system cleanup tasks.

#GENERAL CONFIGURATION FOR TSB (Smart Key Attributes Workflow Engine) - License required
general:
  maxTimestampDiffApprovalClient: 600 #in seconds
  maxFutureTimestampDiffApprovalClient: 0 # in seconds, allows the timestamp to be allowed chosen in the future. Default 0 seconds.
  hsmRequestsTimerServiceInterval: 60000 # in milliseconds, if not specified the hsm requests timer service is disabled
  hsmRequestsTimerServiceMinLock: 0 # optional, default is 0s, lock hsm requests timer service for at least the specified value to prevent multiple executions
  hsmRequestsTimerServiceMaxLock: 30 # optional, default is 30s, wait at most for the specified value in case the node doing the hsm requests timer service has problems
  approvalTaskCleanupInterval: 300000 # in milliseconds, if not specified the approval task cleanup is disabled
  approvalTaskCleanupMinLock: 0 # optional, default is 0s, lock approval task cleanup for at least the specified value to prevent multiple executions
  approvalTaskCleanupMaxLock: 30 # optional, default is 30s, wait at most for the specified value in case the node doing the approval task cleanup has problems
  certificateLookupInterval: 86400000 # in milliseconds (24 hours), if not specified the hsm certificate lookup service is disabled

Configuration Description

Parameter	Description
`general.maxTimestampDiffApprovalClient`	Maximum allowed time difference (in seconds) between the timestamp submitted by a client and the server’s time. Prevents replay attacks.
`general.maxFutureTimestampDiffApprovalClient`	Allows clients to set future timestamps within a permitted range (in seconds). Default: `0` (future timestamps not allowed).
`general.hsmRequestsTimerServiceInterval`	Interval (in milliseconds) for triggering scheduled HSM requests. If not specified, the service is disabled.
`general.hsmRequestsTimerServiceMinLock`	Minimum time (in seconds) the HSM request timer will hold a lock, to prevent concurrent executions. Default: `0`.
`general.hsmRequestsTimerServiceMaxLock`	Maximum wait time (in seconds) if a node already holds the HSM request lock. Default: `30`.
`general.approvalTaskCleanupInterval`	Interval (in milliseconds) for cleaning up completed or expired approval tasks. If not specified, cleanup is disabled.
`general.approvalTaskCleanupMinLock`	Minimum lock time (in seconds) for the approval task cleanup process. Default: `0`.
`general.approvalTaskCleanupMaxLock`	Maximum wait time (in seconds) for the cleanup process if the lock is held by another node. Default: `30`.
`general.certificateLookupInterval`	Interval (in milliseconds) for HSM certificate revalidation and lookup. Default: `86400000` (24 hours). If not specified, the lookup service is disabled.

Log Referrences

Time drift sample log:

2025.04.15 06:16:40.338 WARN  [nio-8080-exec-1] [ka.service.business.HsmService] The system time and the HSM time differ by 125 seconds which exceeds the maximum allowed time difference of 100 seconds. The HSM UTC time is: 2025-04-15T06:14:35. The system UTC time is: 2025-04-15T06:16:40.337828993

What's next?

Explore the Tutorial Section.
Follow the instructions to Create a Key and use it to encrypt and decrypt a payload
Configure HTTPS
Configure Database TLS
Setup API Authentication

What You'll Learn​

REST API Profiles​

local (Default)​

access-token (JWT)​

standalone (Air-Gapped)​

API Authentication​

HSM Load-Balancing​

Configure Load Balancing​

Load-Balancing Modes​

Implications When Master HSM is Unreachable​

Still Possible:​

Not Possible:​

API Behavior When Master Is Down​

Special Case: Smart Key Attributes (SKA)​

Additional HSM Configuration Parameters​

Webserver Configuration​

Increase Maximum Threads​

TLS Configuration​

mTLS Configuration​

Smart Key Attributes Configurations​

Log Referrences​

What's next?​

What You'll Learn

REST API Profiles

`local` (Default)

`access-token` (JWT)

`standalone` (Air-Gapped)

API Authentication

HSM Load-Balancing

Configure Load Balancing

Load-Balancing Modes

Implications When Master HSM is Unreachable

Still Possible:

Not Possible:

API Behavior When Master Is Down

Special Case: Smart Key Attributes (SKA)

Additional HSM Configuration Parameters

Webserver Configuration

Increase Maximum Threads

TLS Configuration

mTLS Configuration

Smart Key Attributes Configurations

Log Referrences

What's next?