Using Fortanix Data Security Manager with Venafi - Keyless TLS

1.0 Introduction

This article describes how to integrate Fortanix Data Security Manager (DSM) with Venafi. The integration describes steps to add Fortanix as an HSM connector within Venafi and then leverage that connector to secure the Venafi Trust Protection Platform (TPP) database with an AES256 key stored within the Fortanix HSM system. It also contains the information that a user requires to create a Fortanix DSM account with a group and an application (app).

1.1 Prerequisites

• Install the Fortanix CNG/EKM provider from here.
• Install VCert CLI from Venafi. For more details, see VCert CLI for Venafi Trust Protection Platform or VCert CLI for Venafi as a Service to get started with the command line utility.
• Configure the Venafi account with Security Principal in Venafi for interacting with VCert/API.

2.0 Fortanix DSM with Venafi Integration Steps

2.1 Creating an App in Fortanix DSM

1. Log in to the Fortanix DSM UI.
2. Click the Groups tab. On the Groups page, click the create a new group icon to create a new group. 
   
   Figure 1: Create a Group in DSM
3. Click the Apps tab. On the Apps page, click the create a new app icon to create a new app.
   Enter the following information:
   • App name: This is the name to identify the Venafi app.
   • Authentication method: This can be left at the default API Key.
   • Group: This is a logical construct that will contain keys created and owned by the Venafi cluster.
4. Click Save to complete creating the application. 
   
   Figure 2: Create New App
5. Note down the application’s API key to use later while configuring the Fortanix DSM client.
   1. Go to the detailed view of an app and click the COPY API KEY as shown below.
      
      Figure 3: Copy App API Key

2.2 Installing Fortanix DSM Client on Web Server

1. Install the Fortanix DSM CNG client software:
   1. Download the MSI from the URL below:
      https://support.fortanix.com/hc/en-us/articles/360018084132-CNG-EKM 
   2. Run the MSI package and accept the default values.
2. Configure the Fortanix DSM CNG client:
   1. Navigate to the Fortanix default client directory - C:\Program Files\Fortanix\KMSClient
   2. Execute the following commands to configure the Fortanix DSM client:

      FortanixKmsClientConfig.exe user --api-endpoint [Fortanix DSM URL]
      FortanixKmsClientConfig.exe user  --api-key

   3. An example of the Fortanix DSM URL is: https://amer.smartkey.io

For more details refer to the Developer’s Guide: Microsoft CNG Key Storage Provider.

2.3 Configuring the Script

Before running the Venafi script, perform the following steps to configure the script:

1. Venafi VCert is a command line tool designed to generate keys and simplify certificate acquisition, eliminating the need to write code required to interact with the Venafi REST API.
   Perform either of the following two methods:
   
   1. Refer to https://github.com/Venafi/vcert/blob/master/README-CLI-PLATFORM.md to download the VCert for Venafi TPP. Log in to Venafi TPP node using the service account assigned to Venafi.
      OR
   2. Refer to https://github.com/Venafi/vcert/blob/master/README-CLI-CLOUD.md to download the Venafi CLI if you are using Venafi as a service.
2. Set up the Headers and Body in the Venafi script for authenticating to Venafi. Refer to the Readme file in the package.
3. On Windows Web Server that has IIS installed, use Vcert to upload a Certificate Signing Request (CSR).
4. You must create a .txt configuration file with the following parameters to modify the values as per your environment.
   NOTE

   • This .txt configuration file must be available in the same directory as the Venafi script file.
   • Ensure that the back slashes must be doubled to avoid errors.

   {
   "Venafi": 
     { 
         "URL":"https://venafi-tpp.company.com", 
         "VCertPath":"c:\\temp", 
         "Policy":"\\VED\\Policy\\Certificates\\IIS" 
     },
   "IIS":  
     { 
         "KeySize":"2048", 
         "DistinguishedName":" CN=example.com,O=Company,OU=TeamName,L=City,ST=State,C=US", 
         "FriendlyName":"certname" 
     }
   }

   Where,

   • URL – This is the base URL for Venafi TPP.
   • VCertPath – This is the location of VCert binary.
   • Policy – This is the destination policy for the newly created certificate.
   • Keysize – This is size of the RSA keys to be generated up to 8K.
   • DistinguishedName – This is the complete Distinguished Name (DN) string for the new certificate. The Venafi policy should be set to allow variance in the individual elements.
   • FriendlyName - This is associated to the certificate as it exists in CertManager and referenced by IIS. This value must be unique.

3.0 Fortanix DSM with Venafi Workflow

The following image illustrates keyless TLS with IIS.

Figure 4: Venafi Workflow

The script performs the following steps:

1. It fetches credentials (Username and Password) for Venafi TPP from the user.
2. It looks for the .txt configuration file that you created above in Section 2.3: Configuring the Script. If found, it imports the values such as URL, certificate path, and policy from configuration file, otherwise it displays a message “config file not found”. An example is attached in the Powershell script package.
3. It looks for the Fortanix CNG provider client that you installed in Section 2.2: Installing Fortanix DSM Client on Web Server. This is one of the prerequisites based on its default location.
4. Looks for Vcert binary and verifies the location (VCert.exe) based on .txt configuration file value.
5. Checks whether the same FriendlyName has been used previously. FriendlyName configured in the .txt configuration file should be unique in the Windows certificate store. If FriendlyName has already been used, the Venafi script will exit here.
6. It makes the API call (/authorize/oauth) to authenticate to Venafi and fetch a session token.
7. After successful authentication, the script will create the configuration file (.inf file) for certutil.exe.
8. certutil is invoked to create the key pair, CNG configuration ensures that the private key is generated on the HSM and does not leave. Output from this step is a Certificate Signing Request.
9. Invoke Vcert.exe to upload CSR to Venafi - Venafi will issue certificate based on Venafi policy configuration. 

Perform the following steps to verify the integration:

1. Using FriendlyName from the .txt configuration file, find thumbprint of the certificate from the certificate store.
2. Update the IIS binding by entering the valid IIS site ID.
   • If the entered Site ID is greater than 1, ask user to identify site for an update.
   • If the entered site ID is less than 1, then alert and exit.
   • If the entered site ID is equal to 1, the default website will be selected.
3. Restart IIS and verify the certificates.