Configure mTLS

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

---

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

On-Premise

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

CloudHSM (TSBaaS)

Send Certificate to Securosys Support

Send one of:

• client.crt (preferred)
• intermediate.crt

Create a Support Ticket:

• Type: 5 - Change request → CloudHSM → Security Policy Change
• Note: Only Security Manager Clouds can request changes.

---

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.

Using P12

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

Using Certificate + Key

curl -v --insecure \
--cert client.crt \
--key client.key \
https://localhost:8080/v1/key

---

Step 5: Manage Certificate Trust

CloudHSM (TSBaaS)

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.

OCSP Revocation

Enable OCSP (Online Certificate Status Protocol)

OCSP provides real-time certificate revocation checks.

Add OCSP URL in Certificate

X509v3 extensions:
  Authority Information Access:
    OCSP - URI:http://your-ocsp.example.com

You can:

• Host a custom OCSP responder
• Use your CA’s built-in OCSP
• Integrate with AWS Private CA

warning

OCSP increases security, but may add latency or become a single point of failure.