Venafi Platform
This guide outlines step-by-step instructions for seamlessly integrating Venafi Platform with a Luna HSM device or Luna Cloud HSM service. The Venafi Platform delivers significant advantages to its customers by providing comprehensive and automated management of digital certificates and cryptographic keys. Customers can bolster their security posture, minimize the risk of certificate-related outages, and streamline compliance efforts by maintaining visibility and control over their cryptographic assets. With Venafi, organizations can protect their digital identities, safeguard sensitive data, and maintain the trust and integrity of their online services and communications.
The key benefits of this integration are:
-
Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.
-
Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.
-
Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.
-
Significant performance enhancements by offloading cryptographic operations from application servers.
Supported Platforms
This integration has been tested and verified on the following platforms:
| HSM Type | Platform Tested |
|---|---|
| Luna HSM | Windows Server 2019 Windows 2016 Server Windows 2012 R2 Server |
| Luna Cloud HSM | Windows 2016 Server Windows 2012 R2 Server |
Prerequisites
The prerequisites for this integration are:
Set up Luna HSM
As the first step to accomplish this integration, you need to set up either On-Premise Luna HSM or Luna Cloud HSM.
Set up On-Premise Luna HSM
Follow these steps to set up your on-premise Luna HSM:
Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.
Create a partition that will be later used by Venafi TPP.
Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.
Initialize Crypto Officer and Crypto User roles for the registered partition.
Run the following command to verify that the partition has been successfully registered and configured:
C:\Program Files\SafeNet\LunaClient>lunacm.exe
Upon successful execution, you should observe an output similar to the example provided below:
lunacm.exe (64-bit) v7.3.0-165. Copyright (c) 2018 SafeNet. All rights reserved. Available HSMs: Slot Id -> 0 Label -> Venafi Serial Number -> 1213475834492 Model -> LunaSA 7.3.0 Firmware Version -> 7.3.0 Configuration -> Luna User Partition With SO (PW) Signing With Cloning Mode Slot Description -> Net Token Slot
Enable partition policies 22 and 23 to allow activation and auto-activation, in case you are using PED-authenticated HSMs.
Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.
Set up Luna HSM High-Availability Group
Refer to Luna HSM documentation for HA steps and details regarding configuring and setting up two or more HSM boxes on host systems. You must enable the HAOnly setting in HA for failover to work so that if the primary goes down due to any reason, all calls get automatically routed to the secondary until the primary recovers and starts up.
Set up Luna HSM in FIPS Mode
To configure Luna HSM in FIPS Mode, update the configuration file by adding or modifying the following setting within the [Misc] section:
RSAKeyGenMechRemap=1
This setting ensures that older calling mechanisms are redirected to the approved RSA key generation methods (186-3 with primes and 186-3 with aux primes) required for FIPS compliance. By making this configuration change, Luna HSM will be properly set up to operate in FIPS mode, adhering to the approved RSA key generation standards.
The configuration setting mentioned above, RSAKeyGenMechRemap=1, is not required for the Universal Client. It is applicable only for Luna Client 7.x.
Set up Luna Cloud HSM
Follow these steps to set up your Luna Cloud HSM:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means
This integration has been certified on the RHEL platform.
Extract the .zip file into a directory on your client workstation.
Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.
tar -xvf cvclient-min.tar
Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.
source ./setenv
To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.
Run the LunaCM utility and verify that the Cloud HSM service is listed.
If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.
Install Microsoft Visual C++
Install Microsoft Visual C++ on the Venafi Platform server. Microsoft Visual C++ is required to access some HSM on Demand applications and utilities. Refer to Microsoft Visual C++ Download Portal for more information on installing Microsoft Visual C++.
Install Venafi Platform
Install Venafi Trust Protection Platform on the target machine. For Venafi Code Signing, the installable components are:
-
Venafi Platform with Venafi Code Signing components
-
CSP for code signing workstations
Refer to Venafi Documentation for detailed instructions.
Integrating Venafi Platform with Luna HSM
The integration of Luna HSM with CyberArk Vault involves three key steps:
Create HSM (Cryptoki) Connector
To create an HSM connector, follow these steps:
Launch the Venafi Configuration Console.
Find and select Connectors in the Venafi Configuration section on the right side.
Click Create HSM Connector from the Actions pane on the right.
Enter the Venafi Trust Protection Platform administration credentials if needed, and then click OK.
Fill out the Name, Cryptoki Dll Path, Slot, User Type and Pin Fields in the Create New HSM (Cryptoki) Connector window that appears, and then click the Verify button.
Click the Create button that appears beneath the Permitted Keys field.
Verify that the HSM connector appears under the Platform Connectors pane.
Enable Venafi Advanced Key Protect
Venafi Advanced Key Protect enables you to orchestrate HSM-based generation and storage of cryptographically strong keys. To enable Venafi Advanced Key Protect:
Open the Venafi Configuration Console and click the Connectors node from the left pane.
In the Actions panel, click Enable Advanced Key Protect.
Review the information in the dialog boxes and confirm the action.
Restart the IIS service by going to the Product node, selecting Website Service, and then clicking Restart.
Restart the Venafi Platform service by selecting the Venafi Platform service, and then clicking Restart.
Restart the logging service by selecting Logging Service, and then clicking Restart.
For more information on Venafi Advanced Key Protect, refer to https://www.venafi.com/platform/advanced-key-protect.
Use Luna HSM in Venafi Platform
Venafi Platform leverages Luna HSMs in the following use cases:
Use Case I – Database Protection with HSM Encryption
Use Case II – Central HSM Key Generation
Use Case III – Remote HSM Key Generation
Use Case IV – Next-Gen Code Signing
Use Case I – Database Protection with HSM Encryption
Venafi Platform maintains all system information, including configuration settings, managed server and certificate information, credentials, archived certificates, and private keys, in a database. The platform uses Luna HSMs to encrypt the information used to connect to the database, as well as to secure the encryption assets within the database, including certificate private keys, credential objects, and SSH keys.
Please make sure to set up the HSM client on your system and confirm that the HSM partition is accessible from this client. In scenarios where HSM is operating in a high-availability (HA) mode, it's essential to activate the HAOnly feature from the HSM client.
To generate the encryption key:
Access the Venafi Configuration Console and navigate to HSM Connector. Click on Properties.
Navigate to the Permitted Keys section and initiate the process of creating a new encryption key on the designated HSM partition or service by selecting the New Key option.
In the ensuing window titled "Create New HSM Key," provide a name for the encryption key in the designated field.
From the Type dropdown menu, opt for AES 256 as the encryption algorithm. Conclude by clicking on the Create button.
Locate the recently created key within the Permitted Keys field and initiate the key creation by clicking the Create button. The encryption key will be successfully generated on the designated partition.
Verify the presence of the encryption key by executing the partition contents command in the lunacm tool and then examine the output results.
Use Case II - Central HSM Key Generation
Luna HSM enables you to centrally generate the private keys for certificates and SSH keys. Centrally generated private keys are exported from the HSM and stored as cipher text in the Venafi database. The private keys and certificates are installed on the target machines that will use them.
Central HSM Key Generation is supported by HSM on Demand with Key Export service in Non-FIPS mode and Luna HSM with Key Export in Non-FIPS mode. Ensure that the HSM client is configured on the system and the HSM partition is accessible from the client. If you are using HSM in HA mode, ensure that HAOnly is enabled and HAsync is disabled from HSM client. Ensure that the application is configured on the target machine and can be reached by Venafi Platform server.
To complete Central HSM Key Generation in Venafi Platform, you need to perform the following procedures:
Generate HSM Connector
To create an HSM Connector, please refer to the detailed instructions outlined in the Create HSM Connector section.
Initiate Venafi Advanced Key Protect
To initiate Venafi Advanced Key Protect, refer to the Enable Venafi Advanced Key Protect section.
Create Certificate Authority (CA) template
During the certificate enrollment and provisioning procedures, every certificate object must reference a CA template object. The CA template objects provide the information that Trust Protection Platform needs to submit the certificate signing request (CSR) to the CA and retrieve the signed certificate. You can create a self-signed CA template, a DigiCert CA template, or a Microsoft CA template. Refer to Venafi Documentation for details.
Configure Certificate Object for Central HSM Key Generation
Configure and update the Venafi platform policies to allow and use the Luna HSM for central HSM key generation. To configure test certificate for Central HSM Key Generation:
Log in to admin console from https://[IP_address_of_Venafi_TPP]/vedadmin. Select policy from the Policy tree in Venafi Platform.
Select Policy > Settings > Certificate tab.
Specify the HSM in the Key Generation drop-down menu.
Click Save.
Right click on the selected policy.
a. Navigate to Add > Certificates > Certificate.
b. Provide the necessary certificate information in General Information tab.
c. Open the Management Type drop-down menu and opt for Provisioning or Enrollment.
d. Enable the Service Generated CSR Radio button in the CSR Generation field.
e. Set Generate Key/CSR on Application to No.
f. Fill out the details in the Subject DN tab.
g. Specify the key type in the Private Key tab.
h. Choose the configured CA template in Other Information tab.
i. Click Save. The certificate gets generated with Certificate Status as OK.
j. Click the Renew Now button. The Certificate Status changes from OK to Queued for Renewal. Wait for a few moments and then click the Refresh button located in the top right corner of the screen.
k. Scroll down to view the certificate details. If the certificate is categorized as Provisioning, proceed with associating the certificate to the application object. Additionally, verify that the certificate has been successfully installed on the application server.
Use Case III - Remote HSM Key Generation
To complete Remote HSM Key Generation in Venafi Platform, you need to perform the following tasks:
Configure remote machine
Perform the following steps on remote machine where you want to install the certificate:
Install Luna HSM client on the target machine and configure the partition.
Configure the application on the remote machine to use Luna HSM. Refer to Venafi Documentation for the list of supported applications.
Activate Venafi Advanced Key Protect
To activate Venafi Advanced Key Protect, refer to the Enable Venafi Advanced Key Protect section.
Generate CA template
During certificate enrollment and provisioning procedures, every certificate object must reference a CA template object. CA template objects provide the information Trust Protection Platform needs to submit the certificate signing request (CSR) to the CA and retrieve the signed certificate. You can create a self-signed CA template, a DigiCert CA template, or a Microsoft CA template. Refer to Venafi Documentation for details.
Configure Certificate Object for Remote HSM Key Generation
To configure the Certificate object for remote HSM key generation:
Log in to the admin console: https://[IP_address_of_Venafi_TPP]/vedadmin.
Select the policy from the Policy tree in Venafi Platform.
Choose the application that you have configured on the target machine.
In the Remote Generation Settings window, choose Gemalto SafeNet HSM under the Private Key Location drop-down and specify the key label in the Key Label field.
Click Save to save the application object.
Perform the following actions:
a. Right-click on the Policy.
b. Select Add > Certificates > Certificate.
c. Provide the details of the certificate in the General Information tab.
d. Open the Management Type drop-down menu and select Provisioning.
e. Enable the Service Generated CSR radio button in the CSR Generation field.
f. Set Generate Key/CSR on Application to Yes.
g. Complete the required fields in the Subject DN tab.
h. Specify the desired key type in the Private Key tab.
i. In the Other Information tab, select the appropriate CA template.
Remote HSM key generation is not compatible with self-signed CA template.
Click Save to initiate the certificate generation process, which will be confirmed by the status changing to OK.
Navigate to the application object where you want to associate the certificate. In the Certificate section, choose the Renewed Certificate from the Associated Certificate field. Click Save.
Return to the certificate object and click Renew Now. The certificate status will change from OK to Queued for Renewal.
Wait for some time and then click the Refresh icon in top-right corner. Scroll down to view the details of the renewed certificate. Once the installation process is completed on the target machine, the status will return to OK.
Verify that the certificate is installed and that the keys are created on the HSM.
Use Case IV – Next-Gen Code Signing
Venafi Next-Gen Code Signing secures all private keys, automates code-signing workflows, and maintains a record of all code signing activities. To leverage Luna HSMs for secure storage of code signing keys, it is necessary to establish a connection between the HSMs and the Venafi Platform. Once the connection is established, the Luna HSMs can be utilized as a trusted key storage option when configuring code signing projects.
Before proceeding with the integration, the Venafi Next-Gen Code Signing software license must be enabled to ensure proper functioning of the solution.
Trust Protection Platform uses the vedauth and vedhsm endpoints to facilitate authentication and HSM functions, as shown in the figure below.
To complete code signing in Venafi Platform, you need to perform the following procedures:
Enable Key Storage in HSM Connector
Start using Venafi Advanced Key Protect
Assign Code Signing Administrator
Enable Key Storage in HSM Connector
Ensure that the HSM service client is configured on the host system and that the HSM partition or Luna Cloud HSM service is accessible over lunacm.
The HSM Connector is a crucial link between Venafi and the HSM, enabling Venafi to securely access the signing keys stored on the HSM. You'll create the HSM connector through the Venafi Configuration Console. For more details, refer to Create HSM Connector. To enable key storage in HSM Connector:
Open the Venafi Configuration Console, and click the Connectors node from the Venafi Configuration pane.
Select HSM Connector under Encryption Connectors and click Properties in Actions pane. HSM Encryption Connector Properties screen will appear.
Select the Allow Key Storage check box and click Apply > OK.
Restart the Venafi services.
Start using Venafi Advanced Key Protect
To enable Venafi Advanced Key Protect, please refer to the Enable Venafi Advanced Key Protect section.
Assign Code Signing Administrator
The Administrators node allows you to view, assign, and delete Code Signing Administrator users. Add the Code Signing Administrator capability to an existing Venafi user. To assign the Code Signing Administrator:
Click the Administrators node in Venafi Configuration Console.
In the Actions panel, click on Add Code Signing Administrator.
Search for the user you want to assign as a Code Signing Administrator and click Select.
Build CA Template
Each environment in a code-signing project requires a CA template. You can create a self-signed CA template, a DigiCert CA template, or a Microsoft CA template. Refer to Venafi Documentation for details.
Create Signing Flow
Flows in Venafi Code Signing define the approvals that must be granted before a signing can take place using a given private key. Create the Venafi approval flow to define the required approvals for code signing. To create the Signing Flow:
In the Flows node, click Add a New Code Signing Flow in the Actions Panel.
Specify the name of the flow and click Create.
Note down the name of the Signing Flow. You'll need it for a subsequent step.
Configure the flow by adding Approvers. Refer to Venafi Documentation for details.
Create Environment Template
Code Signing Environment Templates offer a way for Code Signing Administrators to recommend or enforce specific values for use within code signing projects. Each project necessitates at least one environment. Here's how to establish an Environment Template:
Within the Venafi Configuration Console's Venafi Code Signing node, navigate to Environment Templates.
Click Add Template in the Actions panel.
Specify the name of the template. This action will trigger the appearance of the Development Properties wizard.
Under the Settings section, specify Description, Certificate Container and Signing Flow established in the preceding steps.
Under the Certificate Authority tab, specify the CA template created in the preceding steps.
Navigate to the Keys tab and select the RSA key length values you want to allow. These selections will be incorporated into the certificate.
On the Key Storage tab, click on the drop-down menu and select the HSM Connector created in the preceding steps.
Click Add.
Provide additional details in the remaining tabs, such as the Subject Domain Name of the certificate. However, these specifics are not obligatory for the integration to be successfully completed.
Create Code Signing Project
Code signing projects govern the use of private code signing keys. Code signing projects rely on settings defined in the Environment Template. To create a Code Signing Project with the Venafi platform, follow these steps:
Log in to Aperture by navigating to https://[IP_address_of_Venafi_TPP]/Aperture/codesigning.
On the project list screen, click on Add Project to initiate the project configuration wizard.
Provide a Project Name and Description, and then click Next. You’ll be prompted to select the Environment to associate with the Project.
If you intend to use an existing key and certificate, you can skip the next step.
To create an environment that generates a new certificate and private key, follow these steps:
i. Click the Add Environment card.
ii. From the Environment Type drop-down, select the desired environment type.
iii. Choose the appropriate certificate provider from the Certificate Provider drop-down. If only one certificate provider is assigned to this environment, it will be automatically selected.
iv. Enter a name for the environment in the Environment Name box.
v. Ensure that Key Storage location is set to HSM Connector.
vi. Fill in the remaining fields based on the Subject DN of the certificate.
vii. Click Add to create the environment.
Click Next to proceed.
Assign the appropriate Users and Approvers to the project.
Click Next to continue.
Optionally, you can specify the signing applications that are allowed to use this project by entering them in the Permitted Applications field.
If you want to create new certificate and private key on approval, click Submit for Approval. Skip the Edit Existing Environment section that appears next and proceed to the Approving Code Signing Project section.
If you prefer to use an existing key or certificate, click Save as Draft.
Edit Existing Environment
If you want to use existing key or certificate as a code signing key, follow these steps:
From the project list, select the Draft project created in previous section.
Click Environments.
Select Use Existing Key in HSM.
Select Environment Template from drop down and specify Environment Name.
Click OK. Import Key from Existing HSM will appear.
Select HSM connector name in Key Storage Location drop down.
Select existing key pair on HSM in Private Key and Public Key drop downs.
Specify Certificate Provider and Certificate DN details in the respective fields.
Click Save.
Click Submit for Approval. The project will be submitted for approval by the Code Signing Administrator.
Approve Code Signing Project
Upon submission of the code-signing project for approval, the Code Signing Administrators receive an email notification indicating the project's readiness for review. The administrators should adhere to the subsequent steps for the review and approval of the code-signing project:
Sign into Aperture at https://[IP_address_of_Venafi_TPP]/Aperture/codesigning.
In the Code Signing menu, click Approvals > Pending Approvals.
Click Approve for the Code Signing Project created in the preceding steps. At this point, if you have selected to generate new key pair on HSM, the keys are created. With this step, the configuration for the Venafi Code Signing Project is successfully finalized.
Install and Configure Venafi Crypto Service Provider (CSP)(#)
The Venafi Cryptographic Service Provider (CSP) is the bridge between the workstation on which code signing operations take place and the Venafi Platform server that stores and manages use of private code signing keys. Install the Venafi CSP on every workstation where code will be signed using private keys managed by Venafi Platform. The Venafi CSP communicates with the Venafi Platform server over a TLS-encrypted REST API. The Venafi CSP supports both CSP and KSP. The Venafi CSP only supports RSA certificates. To install and configure the Venafi CSP:
Obtain the appropriate Venafi CSP installation file: VenafiCSP-x64.msi for 64-bit Windows or VenafiCSP-x86.msi for 32-bit Windows.
Run the CSP installation file as an administrator on the client machine. This will launch the CSP installation wizard.
Accept the license agreement, and click Next to proceed.
Select the location where you want the CSP to be installed, and then click Next.
Click Install to begin the installation process. On the Welcome screen, you can select whether you want to use an answer file for this installation. Click Next to continue.
On the Before You Begin screen, verify that you have all the information you need to complete installation.
Enter the URL addresses for the Authentication Server (https://<IP_address_of_Venafi_TPP>/vedauth) and the HSM Server(https://<IP_address_of_Venafi_TPP>/vedhsm) on the Host URLs screen.
Click Next to proceed.
On the Access Authorization screen, enter your Trust Protection Platform user name and password. Check whether you want to enable access for the Current User only, Local Machine only, or both.
On the Configure CSP screen, specify the location where the configuration progress and errors will be logged.
Click Finish.
Sign Code using Venafi Code Signing
When a Key User or a Local Machine is issued a grant, the associated certificates permitted to be used by that user or machine are installed in the CAPI store. These certificates can be used by the signing applications as code signing certificates. The certificate and project details are visible in the Venafi CSP Configuration Console and on the client machine.
This integration guide provides practical examples for application signing:
Example 1: Using jarsigner
Execute the jarsigner command to sign the .jar files on the target machine, using the installed code signing certificate.
Example 2: Using signtool
Execute the signtool command to sign the .exe or .dll files on target machine using the installed code signing certificate.
With these steps, the integration of Venafi Code Signing with the Luna HSM or Luna Cloud HSM service is successfully concluded.
