Venafi Trust Protection Platform
Thales Luna HSMs are available as on-premise hardware HSMs, also known as Luna HSMs and as a cloud offering, Luna Cloud HSM Service. The benefits of integrating an HSM with Venafi Trust Protection Platform include:
- Secure generation, storage and protection of the Identity signing private key on FIPS 140-2 level 3 validated hardware.
- Full life cycle management of the keys.
- HSM audit trail*.
- Significant performance improvements by off-loading cryptographic operations from application servers.
* Luna Cloud HSM Services do not have access to the secure audit trail.
Certified Platforms
HSM | Certified Platforms |
---|---|
Luna HSM | Windows 2016 Server Datacenter Windows 2012R2 Server |
Luna Cloud HSM Service | Windows 2016 Server Datacenter Windows 2012R2 Server |
Install and Configure Luna HSM
Install and configure your Luna Network HSM or Luna Cloud HSM Service for integration with the Venafi Trust Protection Platform.
Verify the HSM is set up, initialized, provisioned and ready for deployment. Refer to the Luna HSM Product Documentation for more information.
Create a partition for use with Venafi Trust Protection Platform.
If using a Luna Network HSM, register a client for the system and assign the client to the partition to create an NTLS connection. Initialize the Crypto Officer and Crypto User roles for the registered partition. Refer to Client Partition Connections for more information.
Ensure that the partition is successfully registered and configured. The command to see the registered partition is lunacm.exe
.
If using a PED-authenticated HSM enable partition policies 22 and 23 to allow activation and auto-activation. Refer to Partition Capabilities and Policies for more information.
Set up Luna HSM High-Availability
Refer to the 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 automatically route to the secondary until the primary recovers and starts up.
Set up Luna HSM in FIPS Mode
Under FIPS 186-3/4, the RSA methods permitted for generating keys are 186-3 with primes and 186-3 with aux primes. This means that RSA PKCS and X9.31 key generation is no longer approved for operation in a FIPS-compliant HSM. If you are using the Luna HSM in FIPS mode, you have to make the following change in the configuration file:
[Misc]
RSAKeyGenMechRemap=1
The above setting redirects the older calling mechanism to a new approved mechanism when Luna HSM is in FIPS mode.
You can configure Luna Cloud HSM Service in the following ways:
- Standalone Luna Cloud HSM Service using a minimum Luna client package
- Standalone Luna Cloud HSM Service using a full Luna client package
- Luna HSM and Luna Cloud HSM Service in hybrid mode
Luna Client v10.x or higher is required for configuring Luna HSM and Luna Cloud HSM Service in hybrid mode.
Luna Cloud HSM Service operates in both FIPS and non-FIPS mode. If your organization requires non-FIPS algorithms for your operations, enable the Allow non-FIPS approved algorithms check box when configuring your Luna Cloud HSM Service. The FIPS mode is enabled by default. Refer to the Mechanism List in the SDK Reference Guide for more information about available FIPS and non-FIPS algorithms.
Standalone Luna Cloud HSM Service using a minimum Luna client package
To configure Luna Cloud HSM Service using minimum client package:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means.
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.
[Windows]
cvclient-min.zip
[Linux]
cvclient-min.tar
Run the setenv script to create a new configuration file. The configuration file contains information required by the Luna Cloud HSM Service.
[Windows]
Right-click setenv.cmd and select Run as Administrator.
[Linux]
Source the setenv script.
source ./setenv
Run the LunaCM
utility and verify that the Luna Cloud HSM Service is listed.
Standalone Luna Cloud HSM Service using a full Luna client package
To configure Luna Cloud HSM Service using full Luna client package:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means.
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.
[Windows]
cvclient-min.zip
[Linux]
cvclient-min.tar
Run the setenv script to create a new configuration file. The configuration file contains information required by the Luna Cloud HSM Service.
[Windows]
Right-click setenv.cmd and select Run as Administrator.
[Linux]
Source the setenv script.
source ./setenv
Copy the server and partition certificates from the Luna Cloud HSM Service Client directory to Luna client certificates directory:
You do not need to complete this step if using Luna Client v10.2 or higher.
Luna Cloud HSM Service Certificate
- server-certificate.pem
- partition-ca-certificate.pem
- partition-certificate.pem
Luna Client Certificate Directory
[Windows default location for Luna Client]
C:\Program Files\Safenet\Lunaclient\cert\
[Linux default location for Luna Client]
/usr/safenet/lunaclient/cert/
Open the configuration file from the Luna Cloud HSM Service Client directory and copy the XTC and REST section.
[Windows]
crystoki.ini
[Linux]
Chrystoki.conf
Edit the Luna Client configuration file and add the XTC and REST sections copied from Luna Cloud HSM Service Client configuration file.
Change server and partition certificates path from step 5 in XTC and REST sections. Do not change any other entries provided in these sections.
You do not need to complete this step if using Luna Client v10.2 or higher.
[XTC]
. . .
PartitionCAPath=<LunaClient_cert_directory>\partition-ca-certificate.pem PartitionCertPath00=<LunaClient_cert_directory>\partition-certificate.pem
. . .
[REST]
. . .
SSLClientSideVerifyFile=<LunaClient_cert_directory>\server-certificate.pem
. . .
Edit the following entry from the Misc section and update the correct path for the plugins directory:
[Misc]
PluginModuleDir=<LunaClient_plugins_directory>
[Windows Default]
C:\Program Files\Safenet\Lunaclient\plugins\
[Linux Default]
/usr/safenet/lunaclient/plugins/
Save the configuration file. If you wish, you can now safely delete the extracted Luna Cloud HSM Service Client directory.
Reset the ChrystokiConfigurationPath environment variable and point back to the location of the Luna Client configuration file.
Windows
In the Control Panel, search for "environment" and select Edit the system environment variables. Click Environment Variables. In both list boxes for the current user and system variables, edit ChrystokiConfigurationPath and point to the crystoki.ini file in the Luna client install directory.
Linux
Either open a new shell session, or export the environment variable for the current session pointing to the location of the Chrystoki.conf file:
export ChrystokiConfigurationPath=/etc/
Run the LunaCM utility and verify that the Luna Cloud HSM Service is listed. In hybrid mode, both Luna and Luna Cloud HSM Service will be listed.
Luna HSM and Luna Cloud HSM Service in hybrid mode
To configure Luna HSM and Luna Cloud HSM Service in hybrid mode, follow the steps described under the Standalone Luna Cloud HSM Service using full Luna client package mentioned above.
You require Luna Client v10.x or higher for configuring Luna HSM device and Luna Cloud HSM Service in hybrid mode.
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 the Venafi Documentation for detailed instructions.
Create an HSM (Cryptoki) Connector
To create an HSM connector you need to:
Open the Venafi Configuration Console, and select the Connectors node from the left pane beneath Venafi Configuration.
In the Actions panel, click Create HSM Connector.
If requested, enter the Venafi Trust Protection Platform administrator credentials.
The Create new HSM (Cryptoki) Connector screen displays.
Fill out the Name, Cryptoki Dll Path, Slot, User Type and Pin fields, and then click the Verify button.
Click the Create button that appears under 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.
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, and clicking on Website, and then clicking Restart.
Restart the Venafi Platform service by clicking on Venafi Platform, and then clicking Restart.
Restart the Logging service by clicking on Logging, and then clicking Restart.
Refer to the Venafi documentation for more information about Venafi Advanced Key Protect Module.
Use Luna HSM in Venafi Platform
Venafi Trust Protection 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 (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.
Ensure that the HSM client is configured on the system and HSM partition is accessible from the HSM client. If you are using HSM in HA mode, ensure that HAOnly is enabled from the HSM client.
Create the Encryption Key
In Venafi Configuration Console, select HSM connector and click Properties.
In the Permitted Keys field, click on New Key to create a new encryption key on the HSM partition or service.
In the Create New HSM Key window, specify the name of the encryption key in the Name field, select AES 256 from the Type drop down menu, and then click Create.
Select the new key in the Permitted Keys field and click Create.
The encryption key is generated on the partition. You can verify the encryption key exists by executing the partition contents
command in lunacm
.
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 it is assumed you have completed Enable Venafi Advanced Key Protect and Use Case I - Database Protection with HSM Encryption.
Create the 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 the Venafi Documentation for more information.
Configure Certificate Object for Central HSM Key Generation
Configure the Venafi platform policies to allow and use the Luna HSM for central HSM key generation. To configure the 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 HSM policy.
a. Click Add > Certificates > Certificate.
b. Specify the details of the certificate in General Information tab.
c. Open the Management Type drop-down menu and select 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 some time and then click refresh in top rightmost corner. Scroll down to see the details of the certificate. If the certificate is of type Provisioning, associate the certificate to the application object and verify that the certificate is installed on the application server.
Use Case III - Remote HSM Key Generation
Venafi Platform orchestrates the connection to the system that requires the certificate. The key pair is securely maintained on the HSM, delivering HSM-based key protection, and the private key never leaves the HSM.
Configure the Remote Machine
Complete the following on remote machines where you want to install the certificate. Refer to the Venafi Documentation for a list of supported applications.
Install Luna HSM client on the target machine and configure the partition.
Configure the application on the remote machine to use Luna HSM.
Enable Venafi Advanced Key Protect on Venafi Platform
Refer to the Enable Venafi Advanced Key Protect for detailed instructions.
Create the Certificate Authority (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 the Venafi Documentation for details.
Configure 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.
Select the application that you have configured on the target machine.
a. Under Remote Generation Settings, expand the Private Key Location drop-down menu and select Gemalto SafeNet HSM and specify the key label in the Key Label field.
b. Click Save to save the application object.
Right click on policy.
a. Click on Add > Certificates > Certificate.
b. Specify the details of the certificate in General Information tab.
c. Open the Management Type drop-down menu and select Provisioning.
d. Enable the Service Generated CSR radio button in the CSR Generation field.
e. Set Generate Key/CSR on Application to Yes.
f. Fill out the details in the Subject DN tab.
g. Specify the key type in the Private Key tab.
h. Choose the CA template in Other Information tab. Click Save. Certificate generates with the Status OK.
Remote HSM key generation will not work with self-signed CA template.
Go to the application object where you want to associate the certificate. Under Certificate section, choose the renewed certificate in the Associated Certificate field. Click Save.
Go back to the certificate object and click Renew Now. The certificate moves from OK to Queued for Renewal stage.
Wait for some time and then click refresh icon in top rightmost corner. Scroll down to see the details of the renewed certificate.
After the installation process gets completed on the target machine, the status returns to OK.
Verify that the certificate is installed on the application on the target machine and the encryption key is generated on the partition. You can verify the encryption key exists by executing the partition contents
command in lunacm
.
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 use Luna HSMs for code signing key storage, the HSMs must be connected to the Venafi Platform. After being connected, the HSMs become available as a key storage option when setting up code signing projects.
Verify that the Venafi Next-Gen Code Signing software license is enabled before proceeding with the Integration.
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 Trust Protection Platform, you need to perform the following procedures:
- Enable Key Storage in the HSM Connector
- Enable Venafi Advanced Key Protect for Code Signing
- Assign the Code Signing Administrator
- Create the Certificate Authority (CA) Template
- Create the Signing Flow
- Create the Environment Template
- Create the Code Signing Project
- Edit an Existing Environment
- Approve the Code Signing Project
- Install and Configure the Venafi Crypto Service Provider (CSP)
- Sign Code using Venafi Code Signing
Enable Key Storage in the 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 provides the HSM credential information to Venafi, allowing Venafi to access signing keys stored on the HSM. You create the HSM connector using the Venafi Configuration Console. To create the HSM connector refer to Create an HSM (Cryptoki) Connector.
Ensure that the HSM client is configured on the host system and that the HSM is accessible over lunacm
.
Open the Venafi Configuration Console, and click on the Connectors node from left pane under Venafi Configuration.
Select HSM connector under Encryption Connectors and click Properties in Actions pane. HSM Encryption Connectors Properties screen will display.
Select the Allow Key Storage check box and click Apply > OK.
Restart the Venafi services.
Enable Venafi Advanced Key Protect for Code Signing
Refer to Enable Venafi Advanced Key Protect for detailed instructions.
Assign the Code Signing Administrator
The Administrators node allows you to view, assign, and delete Code Signing Administrators. 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 Add Code Signing Administrator.
Search for the user you want to assign, and click Select.
Create the 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 the Venafi Documentation for more information.
Create the 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.
In the Flows node, click Add a new Code Signing Flow in the Actions panel.
Specify the name of the flow and click Create.
Record the Signing Flow name, it is required for an upcoming procedure.
Configure the flow by adding Approvers. Refer to the Venafi Documentation for detailed steps.
Create the Environment Template
Code Signing Environment Templates allow the Code Signing Administrator to suggest or require specific values to be used in code signing projects. Each project requires at least one environment.
In the Venafi Code Signing node of the Venafi Configuration Console, select Environment Templates.
Click Add Template from the Actions panel.
Specify the name of the template.
The Development Properties wizard displays.
Under Settings, specify Description, Certificate Container and the SIgning Flow created in the previous procedure.
Under the Certificate Authority tab, specify the CA template created in the earlier procedure.
Under the Keys tab, select the RSA key length values you want to allow. This becomes the algorithm and key length that appear as part of the certificate.
Under the Key Storage tab, click on the drop-down menu and select the HSM Connector created in a previous procedure. Click Add.
You can specify addition details, such as the Subject Domain Name of the certificate, in the remaining tabs, but they are not required to complete the integration.
Create the 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.
Log in to Aperture by going to https://[IP_address_of_Venafi_TPP]/Aperture/codesigning
.
Click on Add Project on the project list screen to open the project configuration wizard.
Enter a Project Name and Description.
Click Next.
Click the Add Environment card.
a. From the Environment Type drop-down, select the type of environment.
b. Click the Certificate Provider drop-down list, and select the certificate provider you want to associate with this environment. If only one certificate provider is assigned to this environment, that provider is automatically sealed and the drop-down is not editable.
c. In the Environment Name box, enter a name for this environment.
d. Ensure that key Storage location points to HSM connector.
e. Complete the remaining fields as required.
f. Click Add.
Click Next.
Assign Users and Approvers to the project.
Click Next.
Optionally, if you want to restrict what signing applications are allowed to use this project, enter 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 an Existing Environment and proceed to the Approve the Code Signing Project section. If you want to use an existing key or certificate, click Save as Draft and proceed to Edit an Existing Environment.
Edit an Existing Environment
To use an existing key or certificate as a code signing key, complete the following:
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 respective fields.
Click Save.
Click Submit for Approval.
The project will be submitted for approval by the Code Signing Administrator.
Approve the Code Signing Project
After a new code signing project is submitted for approval, the Code Signing Administrators receive an email informing them that a project is ready for review.
Code signing administrators should follow these steps for reviewing and approving 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 previous procedure.
This completes the configuration for Venafi Code Signing Project.
Verify the certificate is installed on the CAPI store on the target machine and the keys are created on HSM.
The certificate and project details are visible in the Venafi CSP Configuration Console and on the client machine.
Install and Configure the 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 Trust Protection Platform server, which 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 Trust Protection Platform. The Venafi CSP communicates with the Trust Protection Platform server over a TLS-encrypted REST API.
The Venafi CSP supports both CSP and KSP. The Venafi CSP only supports RSA certificates.
Obtain VenafiCSP-x64.msi.
Run the CSP installation file as the administrator on a client machine.
The CSP installation wizard opens.
Accept the license agreement, and click Next.
Select the location where you want the CSP to be installed, and then click Next.
Click Install.
On the Welcome screen, select whether you want to use an answer file for this installation. Click Next.
On the Before You Begin screen, verify that you have all the information you need to complete the installation.
On the Host URLs screen, enter the UrL addresses for the AUthentication Server and the HSM Server.
Authentication Server URL: https://<IP_address_of_Venafi_TPP>/vedauth
HSM Server URL: https://<IP_address_of_Venafi_TPP>/vedhsm
Click Next.
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, determine 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 Venafi CSP Configuration Console and on the client machine.
Example 1: Using jarsigner
Execute jarsigner
to sign .jar files on the target machine using the installed Code Signing Certificate.
jarsigner.exe -storetype Windows-My -keystore NONE sample.jar -signedjar signedsample.jar CodeSigning jar signed
Example 2: Using signtool
Execute signtool
to sign .exe or .dll files on target machine using the installed Code Signing Certificate.
signtool sign /n "codesigning" sample.dll