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

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 panel and click the + button on the Groups page to add a new group.

   

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 panel and click the + button on the Apps page to add a new app.

   

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

   • App name: Enter the name of your application.

   • 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 API Key

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

1. Click the Apps menu item in the DSM left navigation panel and 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 the VIEW API KEY DETAILS button.

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