Using Fortanix Data Security Manager with Venafi - Keyless TLS

1.0 Introduction

This article outlines the process of integrating Fortanix-Data-Security-Manager (DSM) with Venafi using Keyless TLS instead of an HSM. The integration details the steps to incorporate Fortanix as a Keyless TLS connector within Venafi. 

2.0 Prerequisites

Ensure the following:

• Install the Fortanix CNG/EKM provider from here.

• Install VCert CLI from Venafi. For more details, refer to the 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 a Security Principal in Venafi for interacting with VCert/API.

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 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 <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

For more information on how to set up an account in Fortanix DSM, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

3.3 Creating a Group

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

1. In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.

   

2. 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.

3. Click SAVE to create the new group.

The new group is 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. In the DSM left navigation panel, click the Apps menu item, and then click the + button to create a new app.

   

2. 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 3.3: Creating a Group from the list.

3. Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

3.5 Copying the API Key

Perform the following steps to copy the API key from the Fortanix DSM:

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

2. On the INFO tab, click VIEW API KEY DETAILS.

3. From the API Key Details dialog box, copy the API Key of the app to use it later.

4.0 Installing Fortanix DSM Client on Web Server

1. Install the Fortanix DSM CNG client software:

   1. Download the MSI from 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.

5.0 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 the https://github.com/Venafi/vcert/blob/master/README-CLI-PLATFORM.md to download the VCert for Venafi TPP. Log in to the Venafi TPP node using the service account assigned to Venafi.
      OR

   2. Refer to the 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 a 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 backslashes are 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 refers to the base URL for Venafi TPP.

   • VCertPath refers to the location of VCert binary.

   • Policy refers to the destination policy for the newly created certificate.

   • KeySize refers to the size of the RSA keys to be generated up to 8K.

   • DistinguishedName refers to the complete Distinguished Name (DN) string for the new certificate. The Venafi policy should be set to allow variance in the individual elements.

   • FriendlyName refers to associated to the certificate as it exists in CertManager and is referenced by IIS. This value must be unique.

6.0 Fortanix DSM with Venafi Workflow

The following image illustrates keyless TLS with IIS.

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 5.0: Configuring the Script. If found, it imports the values such as URL, certificate path, and policy from the 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 4.0: Installing Fortanix DSM Client on Web Server. This is one of the prerequisites based on its default location.

4. Looks for the Vcert binary and verifies the location (VCert.exe) based on the .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, and CNG configuration ensures that the private key is generated on the HSM and does not leave. The output from this step is a Certificate Signing Request.

9. Invoke Vcert.exe to upload the CSR to Venafi - Venafi will issue the certificate based on Venafi policy configuration. 

Perform the following steps to verify the integration:

1. Using FriendlyName from the .txt configuration file, find the 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 the user to identify a 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.