Mutual Transport Layer Security using Fortanix Data Security Manager (on-prem only)

  • Updated on Mar 12, 2025
  • Published on Jun 26, 2024
  • 10 minute(s) read

1.0  Introduction

The purpose of this article is to describe the steps required to perform mutual Transport Layer Security (TLS) using 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.

1.1  Advantages of Mutual TLS

As compared to the default API key-based authentication, client certificate-based authentication has the following additional benefits:

  1. It supports the verification of client applications. Only applications that hold the private key (that signed the client certificate) can authenticate and establish a TLS connection.

  2. Compared to API Keys which must be put in plain text in configuration files or environment variables, the Application Team has the infrastructure to secure private keys using local key vaults.

  3. Compared to API keys that are sensitive and shared over email or other insecure channels, the initial setup in mutual TLS has better security as it only requires sharing non-sensitive public certificates between the Application Team and the Fortanix DSM Admin Team.

1.2  Important Considerations

The following considerations must be noted:

  • The Application Team is the owner of the client certificate that has an expiration date. This team is responsible to track the expiration date and renew the certificate on time. If the certificates expire, the API requests will start failing immediately. Fortanix DSM does not notify auth certificate expiration events (though the expiration date can be viewed on the Fortanix DSM dashboard).

  • The Application Team is responsible to secure their private keys. This can be done using key vaulting or by limited access to application servers.

2.0  Cluster Setup

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

2.1  New Endpoint and Certificates

  1. Allocate a new endpoint for the cluster that only accepts mutual TLS connections from client applications. This must be different from the main endpoint. Fortanix recommends using:
    For non-production: apps.sdkmsdev.uk.myorg.com .

  2. Map the above endpoint to the same Load Balancer IP addresses as the main endpoints with your DNS administrator.

  3. Obtain a new set of certificates for the cluster that has the above endpoints added to the existing SAN names.

    1. Perform get_csrs to generate new CSRs. Keep all the Distinguished names the same as the current (CN, OU, O, ST, C). Add new names to the list of SAN names (additional to existing SANs used). For more details, refer to Using Fortanix DSM.

    2. Get the signed certificate from a CA using the above CSRs.

    3. Install the signed certificate provided by the CA, using the install_certs .

    4. The above installation is non-disruptive due to the rolling restart of the services (consecutive restart of nodes such that only one node is down at a time). Existing authentication methods will continue to work as usual.

2.2  Sysadmin Setting

Now, enable client certificate-based authentication on the new DNS endpoints.

  1. Sign in to Fortanix DSM using the Sys Admin credentials. Select System Administration account.

  2. Go to Settings → Interfaces.

    1. Select the option “Request client certificate” for the new endpoints (For example: sdkmsdev.uk.myorg.com)

    2. Save changes.

    1. SSH to any Fortanix DSM.

    2. Run the following command:

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

    3. The changes are applied, and the cluster is ready to accept client certificate-based TLS connections on the new endpoint. Any changes to the Sysadmin settings will require a restart of Fortanix DSM services (rolling restart).

    Mutual_TLS.png

    Figure 1: Select the new endpoint

3.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:

3.1 Signing Up

To get started with the Fortanix Data Security Manager (DSM) cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

3.2 Creating an Account

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

Figure 2: Logging In

3.3 Creating a Group

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

  1. Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.

    Figure 3: Add Groups

  2. On the Adding new group page, enter the following details:

    • Title: Enter a title for your group.

    • Description (optional): Enter a short description for the group.

  3. Click the SAVE button to create the new group.

The new group has been added to the Fortanix DSM successfully.

3.4 Creating an Application

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

  1. Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.

    Figure 4: Add Application

  2. On the Adding new app page, enter the following details:

    • App name: Enter the name of your application.

    • Interface (optional): Select the REST API option as interface type from the drop down menu.

    • ADD DESCRIPTION (optional): Enter a short description for the application.

    • Authentication method: Select the default API Key as the method of authentication from the drop down menu. For more information on these authentication methods, refer to User's Guide: Authentication documentation.

    • Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.

  3. Click the Save button to add the new application. 

The new application has been added to the Fortanix DSM successfully.

3.5 Copying the App UUID

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

  1. Click the Apps menu item in the DSM left navigation bar and click the app created in the Section 3.4: Creating an Application to go to the detailed view of the app. 

  2. From the top of the app’s page, copy the app UUID to be used in Section 3.6.1: App ID as Common Name in Certificate as the value of Common Name (CN) to generate the certificate.

3.6  Generating the Certificate

The Application Team must generate a private key and certificate for mutual TLS authentication. The certificate is then shared with the Fortanix DSM Admin for whitelisting.

NOTE

The private key must not be shared and must be kept securely with the Application Team.

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

If client certificate authentication is used with PKCS#11 library or with KMIP compliant software, the certificate must have the Fortanix DSM app information embedded, for authentication to specific Fortanix DSM Group. Refer to the Section 4.0: Authentication.

If the Application Team plans to use the REST APIs or the Fortanix DSM SDKs, then the app information is not required in the certificate as this can be passed in the API request separately.

The following Section 3.6.1: App ID as Common Name in Certificate does not apply in this case.

3.6.1  App ID as Common Name in Certificate

The app UUID can be set in the certificate as the CN (Common Name or FQDN Name).

Examine the subject in the certificate to verify it contains the app ID as CN. A certificate generated correctly should look as follows (note the value of CN).

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/[email protected]
        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/[email protected]
        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 organization’s CA’s do not allow invalid hostnames for CN names. In such cases, add the app ID as a custom Fortanix Object ID (OID). Refer to the Section 3.6.2: App ID as Custom Object ID Value in Certificate.

3.6.2  App ID as Custom Object ID Value in Certificate 

The following configuration explains how to generate a self-signed certificate with a custom OID containing app UUID, using OpenSSL. Follow the instructions by your CA if you are not using OpenSSL.

  1. Edit the file /etc/ssl/openssl.cnfand add the custom OID in the “new_oids” section. The file should look as follows:

    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

  2. Now add a description in the “req_distinguished_name” section and add the following line:

    my_app_id = custom attribute for app id

  3. Save the file and generate a self-signed certificate (or CSR).

  4. Examine the subject in the certificate to verify that it contains the custom OID. A certificate generated correctly should look as follows (note the value of custom OID in the subject).

    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/[email protected]/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/[email protected]/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

3.7 Updating the Authentication Method

Perform the following steps to change the authentication method:

  1. Go to the detailed view of the app created in Section 3.4: Creating an Application and click the Change the authentication method button and select the Certificate option to change the authentication method to Certificate.

  2. Click the SAVE button.

  3. 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 previous section.

  4. Select both the check boxes to confirm your understanding about the action.

  5. Click the UPDATE button to save the changes.

4.0  Authentication

The following are sample API requests that authenticate using a client certificate and establish mutual TLS connections.

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

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

  • If client certificate does not contain 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>

Related articles