Skip to main content

Configure mTLS for PrimusHSM REST API

Mutual TLS (mTLS) enhances security by requiring both the client and server to authenticate each other using X.509 certificates. Unlike standard TLS where only the server presents a certificate, mTLS enforces two-way trust.

In this guide, you'll learn how to:

  • Generate a complete certificate chain (Root CA → Intermediate CA → Client certificate)
  • Configure your environment for both on-premise and cloud-based (TSBaaS) deployment
  • Test your setup using curl

mTLS Diagram

Prerequisites​

Before you begin, install the following tools:

1. OpenSSL (for certificate generation)​

Available by default on most Unix systems. Install with:

sudo apt install openssl

2. Java Keytool (for Java TrustStore)​

Install OpenJDK 11 (includes Keytool):

sudo apt install default-jre

Verify the installation:

java -version

Step 1: Generate Certificate Chain​

Navigate to the configuration directory:

cd ~/securosys_tsb-configuration-v2.3.1/config-files
mkdir -p mtls && cd mtls

1.1 Create Root Certificate Authority (CA)​

openssl req -new -x509 -nodes -sha256 -newkey rsa:4096 -days 3650 \
-subj "/CN=RootCA" \
-keyout ca.key -out ca.crt

Output: ca.key, ca.crt

Root CA used to sign all subordinate certificates.

1.2 Create Intermediate CA​

openssl genrsa -out intermediate.key 4096

openssl req -new -key intermediate.key \
-subj "/CN=IntermediateCA" \
-out intermediate.csr

openssl x509 -req -in intermediate.csr -sha256 \
-CA ca.crt -CAkey ca.key -CAcreateserial -days 3650 \
-out intermediate.crt

Output: intermediate.key, intermediate.crt

Trusted by Root CA and signs client certificates.

1.3 Create Client Certificate​

openssl genrsa -out client.key 4096

openssl req -new -key client.key \
-subj "/CN=Client" \
-out client.csr

openssl x509 -req -in client.csr -sha256 \
-CA intermediate.crt -CAkey intermediate.key -CAcreateserial -days 3650 \
-out client.crt

Output: client.key, client.crt

info

client.crt and client.key are used by the client during mTLS authentication.

Step 2: Create PKCS#12 Bundle (Optional)​

This step simplifies mTLS usage in browsers or curl.

openssl pkcs12 -export \
-out client.p12 \
-inkey client.key \
-in client.crt \
-password pass:secret

Output: client.p12 — bundled client certificate protected with password secret.

Step 3: Configure mTLS in REST API​

Import Client Certificate into Java TrustStore​

keytool -importcert \
-keystore securosys-ska-truststore-server.jks \
-alias client-cert \
-file client.crt \
-storepass <truststore-password>

Ensure securosys-ska-truststore-server.jks is in config-files/mtls.

Update application-local.yml​

server:
  ssl:
    trust-store: 'file:/etc/app/config/mtls/securosys-ska-truststore-server.jks'
    trust-store-password: <truststore-password>
    trust-store-type: 'JKS'
    client-auth: need

client-auth: need enforces client certificate authentication.

Restart the service​

docker compose down && docker compose up -d

Step 4: Test mTLS with curl​

If client.p12 is missing, you may get:

curl: (35) OpenSSL error: ssl/tls alert bad certificate
IMPORTANT

Never use --insecure in production! Use --cacert or install trusted Root CA.

curl -v --insecure \
--cert-type P12 \
--cert client.p12:secret \
https://localhost:8080/v1/key

Step 5: Manage Certificate Trust​

Modify Trust in CloudHSM​

Open a support ticket:

  • Type: 5 - Change request → CloudHSM → Security Policy Change
  • Include:
    • Certificate alias
    • SHA256 fingerprint
    • Action: add or revoke

Only Security Managers can submit these changes.

Last updated on