1.0 Introduction

This article describes the steps required to perform mutual Transport Layer Security (mTLS) using {{glossary.Fortanix-Data-Security-Manager}} (DSM).

Fortanix DSM supports client certificate-based mutual TLS authentication for API requests. Using this method, applications can securely authenticate themselves and perform crypto and key management operations.

2.0 Advantages of Mutual TLS

Compared to the default API key-based authentication, client certificate-based (mTLS) authentication provides several enhanced security and operational benefits:

Only applications that hold the corresponding private key (used to sign the client certificate) can establish a connection. This prevents unauthorized clients from accessing Fortanix DSM.
While API keys are often stored in plain text within config files or environment variables, private keys can be securely stored and managed using local key vaults. For example, HSMs, TPMs, or OS-managed keystores.
API keys are sensitive secrets often shared insecurely, for example, through email or chat. In contrast, mTLS only requires the exchange of non-sensitive public certificates, significantly reducing the risk of credential leakage during setup.

3.0 Important Considerations

The following considerations must be noted when using client certificate-based authentication:

The Application Team owns the client certificate, which includes an expiration date, and is fully responsible for monitoring and renewing it before it expires. If the certificate is not renewed on time and expires, all API requests using it will immediately begin to fail.
It is important to note that Fortanix DSM does not generate alerts or notifications for authentication certificate expiration, although the expiration date is visible on the Fortanix DSM dashboard.
Additionally, the Application Team must ensure the security of their private keys. This can be achieved using secure key vaults or by restricting access to application servers that store the keys.

4.0 Cluster Setup

To enable a new endpoint for all mTLS requests, Fortanix DSM must be configured once at the Cluster level, and then at the Group level for onboarding application teams.

4.1 New Endpoint and Certificates

Perform the following steps to enable mutual TLS (mTLS) authentication on a dedicated endpoint:

Allocate a new endpoint for the Fortanix DSM cluster that only accepts mTLS connections from client applications. This must be distinct from the main endpoint; for non-production, Fortanix recommends using apps.sdkmsdev.uk.myorg.com.
Ask your DNS administrator to map the new endpoint to the same Load Balancer IP addresses as the existing cluster endpoints.
Generate a new set of certificates for the cluster with the updated endpoint included in the Subject Alternative Names (SANs).
1. Run the get_csrs command to generate CSRs, keeping the Distinguished Names (CN, OU, O, ST, C) the same as before. Add the new endpoint to the existing SAN list. For more information, refer to the Fortanix Data Security Manager Installation Guide - On-Prem.
2. Submit the CSRs to a Certificate Authority (CA) and obtain the signed certificates.
3. Use the install_certs command to install the signed certificates.
The certificate update is non-disruptive and triggers a rolling restart of services. This ensures only one node restarts at a time, allowing existing authentication methods to remain functional during the change.

4.2 System Administration Setting

Perform the following steps to enable client certificate-based authentication on the new DNS endpoints in Fortanix DSM:

Sign in to Fortanix DSM using System Administrator credentials.
Select the System Administration account.
In the DSM left navigation panel, click the Settings menu item, and then click INTERFACES.
On the Interfaces page, select the REQUEST CLIENT CERTIFICATE check box for the new endpoints. For example: apps.sdkmsdev.uk.myorg.com.
Click SAVE CHANGES.

Perform the following steps to restart Fortanix DSM services to apply the configuration changes:

SSH into any Fortanix DSM appliance.

Run the following command to start a rolling restart:

sudo KUBECONFIG=/etc/kubernetes/admin.conf kubectl patch deployment sdkms -p '{"spec": {"template": {"metadata": {"annotations":{"restart-date":"'`date --iso-8601=seconds`'"}}}}}'

Once the patch is applied, the cluster is ready to accept client certificate-authenticated TLS connections on the configured DNS endpoint.
Figure 1: Select the new endpoint

5.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

5.1 Signing Up

{{snippet.Signing Up}}

5.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

{{snippet.Creating an Account}}

5.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.
Figure 3: Add groups
On the Adding new group page, do the following:
1. Title: Enter a name for your group.
2. Description (optional): Enter a short description of the group.
Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

5.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

In the DSM left navigation panel, click the Apps menu item, and then click the + button to create a new app.
Figure 4: Add application
On the Adding new app page, do the following:
1. App name: Enter the name for your application.
2. ADD DESCRIPTION (optional): Enter a short description of the application.
3. Authentication method: Select the default API Key as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication.
4. Assigning the new app to groups: Select the group created in Section 5.3: Creating a Group from the list.
Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

5.5 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 5.4: Creating an Application to go to the detailed view of the app.
From the top of the app’s page, click the copy icon next to the app UUID to copy it to use in Section 5.6.1: App ID as Common Name in Certificate as the value of Common Name (CN) to generate the certificate.

5.6 Generating the Certificate

The Application Team must generate a private key and corresponding certificate to enable mTLS authentication. The certificate must then be shared with the Fortanix DSM Administrator for whitelisting.

NOTE
The private key must remain confidential and must not be shared. It should be securely stored and managed by the Application Team.

Fortanix DSM supports both self-signed and CA-signed certificates for mTLS authentication.

If the client certificate is used with the PKCS#11 library or with KMIP-compliant software, the certificate must embed the Fortanix DSM App information. This enables authentication to a specific Fortanix DSM Group. For more information, refer to Section 6.0: Authentication.
If the Application Team uses REST APIs or Fortanix DSM SDKs, embedding app information in the certificate is not required, as it can be passed separately within the API request.

5.6.1 App ID as Common Name in Certificate

The application UUID (App ID) can be embedded in the certificate as the Common Name (CN) or Fully Qualified Domain Name (FQDN).

To verify the correct configuration:

Inspect the Subject field in the certificate.
Ensure that the CN contains the app UUID.

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 11285796284824083476 (0x9c9f33ed245cdc14)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=US, ST=CA, L=Mountain View, O=Fortanix, OU=Test, CN=da7f2800-4122-4681-aebf-90beb779b73f/emailAddress=test@fortanix.com
        Validity
            Not Before: Aug 8 23:31:20 2018 GMT
            Not After : Aug 8 23:31:20 2019 GMT
        Subject: C=US, ST=CA, L=Mountain View, O=Fortanix, OU=Test, CN=da7f2800-4122-4681-aebf-90beb779b73f/emailAddress=test@fortanix.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:d2:ae:15:66:bf:78:d4:98:f4:4d:a5:57:bf:04:
                    08:76:83:1f:40:e8:8b:c4:da:8a:a0:71:22:43:84:
                    6d:c9:05:f2:81:91:83:04:75:bd:c9:83:86:92:bf:
                    ff:a0:e4:b4:e4:ee:56:09:10:2a:dc:e2:f4:0c:65:
                    43:96:a1:31:0d:15:92:49:87:ee:46:91:5d:f1:8c:
                    61:b3:ca:4a:9f:be:01:00:d5:30:5f:ee:56:35:75:
                    3c:e1:0d:a6:34:66:7f:3b:26:69:97:33:6d:2e:c7:
                    fd:c9:42:7d:14:f7:12:18:4a:5b:a6:90:52:7a:4b:
                    1b:45:b3:79:33:31:99:03:1d:a4:ed:51:dc:7b:43:
                    20:02:bb:08:22:27:27:8c:51:6a:5f:59:87:45:95:
                    d7:f3:ca:fa:30:3d:d5:a6:50:77:03:e3:de:eb:30:
                    17:45:48:fe:5b:76:d4:c1:03:3f:b8:99:73:ae:ad:
                    ae:e2:69:95:e2:14:1e:42:b1:ac:72:cd:0b:c6:01:
                    e3:20:8d:5a:6a:5d:19:79:17:f0:80:5f:75:fc:d5:
                    da:9c:af:07:d8:c7:96:02:a5:94:19:64:d7:9a:e4:
                    56:f1:cf:54:b9:a7:29:28:22:52:f2:c4:8a:97:04:
                    45:b1:9b:b5:4f:c0:18:53:ff:08:3f:3b:81:bd:f1:
                    d1:e9
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier: 

87:65:C6:B6:B6:3A:0A:A6:30:BA:CB:D2:27:9E:C4:E6:2E:7F:2F:6D
            X509v3 Authority Key Identifier: 

keyid:87:65:C6:B6:B6:3A:0A:A6:30:BA:CB:D2:27:9E:C4:E6:2E:7F:2F:6D

            X509v3 Basic Constraints: 
                CA:TRUE
    Signature Algorithm: sha256WithRSAEncryption
         71:da:8c:da:ab:9d:6d:8a:f1:9c:56:a9:7d:e2:e2:1b:fd:90:
         b7:5e:45:db:d4:69:47:ca:98:2f:b0:3b:2c:1f:49:3a:75:dd:
         1d:96:b3:bd:11:a6:d7:06:60:4f:18:11:e1:cf:db:5c:52:03:
         29:78:47:6e:36:c0:64:d8:4d:34:00:d9:94:55:48:a9:d4:b2:
         b2:ed:b8:13:fc:3d:c6:b4:61:a3:56:aa:9d:73:80:62:38:da:
         0c:94:b0:4a:e6:86:da:6a:f9:aa:f3:a4:3c:48:32:93:f7:d3:
         27:f9:2c:77:b4:91:9c:84:62:96:86:7d:d2:c8:20:79:d1:12:
         ef:f0:cc:15:31:ea:86:e9:b4:02:00:55:83:0f:6a:c6:5b:d2:
         19:67:9b:b2:44:f8:3b:36:f9:b0:02:b2:98:7d:1e:fa:95:58:
         92:92:57:68:f8:56:bb:43:db:01:08:bb:d6:ab:52:e6:c7:88:
         7a:1c:8d:f4:31:90:70:0a:dd:d2:96:7c:8b:93:8f:1f:4a:80:
         fe:3a:f8:df:82:a7:99:ac:2f:e8:02:e5:8b:fe:ec:3b:3b:0a:
         a3:c0:82:4d:f7:93:66:a1:76:6f:fa:c2:19:8e:d8:b6:b4:27:
         8c:57:22:a4:f7:e6:45:61:27:af:fc:5f:51:88:eb:32:

NOTE
Many organizational Certificate Authorities (CAs) do not allow non-hostname values in the CN field. In such cases, the app ID should be added as a custom Fortanix Object Identifier (OID). Refer to Section 5.6.2: App ID as Custom Object ID Value in Certificate.

5.6.2 App ID as Custom Object ID Value in Certificate

If your CA enforces hostname validation on CN fields, you can embed the app ID using a custom OID.

Perform the following steps to describe how to configure a self-signed certificate using OpenSSL:

Open the OpenSSL configuration file, located at /etc/ssl/openssl.cnf, and define a custom OID under the new_oids section:

oid_section = new_oids
      
# To use this configuration file with the "-extfile" option of the
# "openssl x509" utility, name here the section containing the
# X.509v3 extensions to use:
# extensions = 
# (Alternatively, use a configuration file that has only
# X.509v3 extensions in its main [= default] section.)

[ new_oids ]
my_app_id=1.3.6.1.4.1.49690.1.2.1

Locate the [ req_distinguished_name ] section and add a label for the custom OID:
```
my_app_id = custom attribute for app id
```
Use OpenSSL to generate a self-signed certificate or a Certificate Signing Request (CSR) using this config file. Include the -extfile option if needed.

Examine the certificate subject to ensure the custom OID (1.3.6.1.4.1.49690.1.2.1) is present with the correct app UUID value:

Certificate:
      Data:
          Version: 3 (0x2)
          Serial Number: 18122652583846371291 (0xfb809881cffa5fdb)
      Signature Algorithm: sha256WithRSAEncryption
          Issuer: C=US, ST=California, L=Mountain View, O=Fortanix Inc, OU=Engineering, CN=test.kmip.fortanix.com/emailAddress=test@fortanix.com/1.3.6.1.4.1.49690.1.2.1=acc15bf3-e626-47aa-9373-7b08b3f26ee8
          Validity
              Not Before: Aug 8 23:19:45 2018 GMT
              Not After : Aug 8 23:19:45 2019 GMT
          Subject: C=US, ST=California, L=Mountain View, O=Fortanix Inc, OU=Engineering, CN=test.kmip.fortanix.com/emailAddress=test@fortanix.com/1.3.6.1.4.1.49690.1.2.1=acc15bf3-e626-47aa-9373-7b08b3f26ee8
          Subject Public Key Info:
              Public Key Algorithm: rsaEncryption
                  Public-Key: (2048 bit)
                  Modulus:

00:97:a4:5b:d4:11:ee:c6:89:e1:f8:44:39:f9:69:
43:be:ee:69:78:5b:32:26:53:9d:a7:46:f4:17:0e:
5a:dc:b4:58:23:af:69:a1:86:de:2e:c5:46:14:98:
b6:6a:fc:f5:26:73:f7:56:6f:60:d8:2c:52:69:c9:
58:2a:d6:fd:4e:6e:22:0d:8c:e5:99:01:10:70:59:
6c:68:a2:a8:ee:e6:37:f7:08:8a:8a:75:bb:91:2b:
db:ad:1c:03:56:5f:01:ae:55:ff:3a:8b:40:91:e7:
04:4d:49:31:76:dc:ec:9e:d5:cb:d5:73:00:4f:13:
f2:12:f3:45:9f:df:fc:aa:2d:5f:d4:95:b2:e9:fa:
ad:38:d8:36:a5:f3:99:92:e5:b4:0a:39:99:85:ee:
13:39:fb:8d:1c:7a:52:03:e3:86:8a:d8:24:e9:28:
70:18:72:e0:b5:e6:f2:66:6f:1c:1a:be:f7:23:2c:
e0:9f:79:2b:2e:6e:be:c6:b1:31:65:00:cb:9c:8b:
bd:c0:56:dc:bd:0c:24:6a:d2:20:91:5f:14:84:63:
ef:18:b2:de:33:a8:ec:dd:4e:a5:3f:11:7b:7d:eb:
a1:e1:49:fc:d7:9e:26:98:6f:cb:3b:7e:5d:7e:2d:
1e:34:ca:3a:f9:12:95:b2:aa:ff:40:95:e1:5e:b9:
a5:a3
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier: 
9C:74:2E:5B:16:76:F9:59:9F:E0:B5:53:C9:26:45:45:F7:4C:8D:99
            X509v3 Authority Key Identifier: 
keyid:9C:74:2E:5B:16:76:F9:59:9F:E0:B5:53:C9:26:45:45:F7:4C:8D:99

        X509v3 Basic Constraints: 
            CA:TRUE
    Signature Algorithm: sha256WithRSAEncryption
72:95:6a:8a:4c:18:53:e9:f6:3d:87:e9:97:d2:48:fe:2b:60:
ea:e2:ca:81:cb:9b:15:48:38:30:62:16:6b:b0:54:f6:91:2d:
b0:72:af:36:36:39:8e:78:1f:8c:17:19:df:5c:e5:ae:4d:f4:
ae:41:39:04:f2:95:d1:0a:99:ef:ef:63:72:5e:83:96:c1:c7:
f1:d7:f6:45:58:23:76:3d:1a:ba:a3:08:e4:4a:a0:6a:33:8f:
e5:50:04:b1:08:74:b3:37:9c:fd:f9:9c:5d:27:7d:63:a8:7d:
40:3e:d5:aa:7d:a7:9e:70:79:38:91:45:68:29:0d:a8:80:42:
f8:9b:e0:17:bb:93:9f:71:89:04:0f:39:d0:2e:3c:10:62:44:
6b:41:5d:e5:78:42:50:c5:f7:ee:bc:a8:5e:90:01:ad:3c:f2:
27:f2:81:16:ba:1e:79:d8:c4:09:cb:01:fd:71:11:9f:91:14:
72:71:0f:f1:d3:b0:4d:91:78:dd:12:fb:fd:d6:22:93:15:67:
df:4e:da:df:74:de:68:95:d7:d8:70:48:e2:5f:bc:ec:b2:0f:
bb:14:83:ad:c9:f9:a0:81:0d:a8:68:64:77:db:5a:71:4a:8b:
8f:91:d6:ce:e1:33:42:ba:98:76:a1:cd:89:8e:3a:cb:aa:b1:
8e:ca:42:af

NOTE
A correctly generated certificate will display the custom OID and app UUID in the subject or extensions section.

5.7 Updating the Authentication Method

Perform the following steps to change the authentication method:

Go to the detailed view of the app created in Section 5.4: Creating an Application and click the Change authentication method button and select the Certificate option to change the authentication method to Certificate.
Click the SAVE button.
On the Add certificate dialog box, click the UPLOAD NEW CERTIFICATE button to upload the certificate file or paste the content of the certificate generated in the previous section.
Select both check boxes to confirm your understanding of the action.
Click the UPDATE button to save the changes.

6.0 Authentication

The following are example curl commands for authenticating with Fortanix DSM using mTLS.

These use a client certificate and private key to establish a secure session.

If the client certificate contains the app ID as the CN name or a custom OID:

curl -k https://sdkmsdev.uk.myorg.com/sys/v1/session/auth -X POST --key <private key file> --cert <certificate file>

If the client certificate does not contain the app ID:

curl -k https://sdkmsdev.uk.myorg.com/sys/v1/session/auth -X POST --key <private key file> --cert <certificate file> -u <App UUID>

Does Fortanix DSM support the Certificate Management Protocol (CMP)?