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

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 Fortanix Data Security Manager Install Guide: Section 5.6.
    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  Client Onboarding

3.1  Fortanix Data Security Manager App

The Fortanix DSM Admin must generate an App in the designated Group for API authentication.

  1. Note the App UUID. Share this with the Application Team. This is required for authentication.
  2. When the client certificate is shared by the Application Team (see Section 3.2 ), do the following:
    1. Go to the detailed view of your Application.
    2. Navigate to the Info tab and click the “Change authentication method” drop-down. Select the method as “Certificate” and click Save.
    3. You will be prompted to upload a certificate. Upload the certificate and click Update. Now your app is set to authenticate using the certificate provided by the Application Team.

3.2  Certificate Generation

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 PKCS11 library or with KMIP compliant software, the certificate must have the Fortanix DSM App information embedded, for authentication to specific Fortanix DSM Group (see Section 3.3).

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 (Section 3.2.1) does not apply in this case.

3.2.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/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 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) (see Section 5.2.2).


3.2.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/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

3.3  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>
     

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful