Procedures

Prerequisites

Ensure the following prerequisites are implemented:

Install the Entrust nShield HSM using the instructions in the Installation Guide for the HSM.
Install the Entrust nShield Security World Software, and configure the Security World as described in the User Guide for the HSM.

Edit the cknfastrc file located in %NFAST_HOME%\cknfastrc.

If using OCS or Softcard protection:

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=explicitness
CKNFAST_NO_ACCELERATOR_SLOTS=1
CKNFAST_LOADSHARING=1

If using Module protection:

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=explicitness
CKNFAST_FAKE_ACCELERATOR_LOGIN=1
CKNFAST_LOADSHARING=1

Install Venafi TLS Protect Datacenter. For more information, see the Venafi online documentation.

Create an HSM (Cryptoki) connector

You must setup an HSM connector before the nShield HSM functionally can be used within Venafi TLS Protect Datacenter.

To create an HSM (Cryptoki) connector:

Open the Venafi Configuration Console.
Select the Connectors node.
Select Create HSM Connector in the Actions panel.
Enter your Venafi TLS Protect Datacenter user credentials if required.
For Name, enter any name for the HSM connector.
For Cryptoki Dll Path, select Browse and locate the following path to the DLL file:

C:\Program Files\nCipher\nfast\toolkits\pkcs11\cknfast.dll.
Select Load Slots.
Select a slot to use for the intended key protection type. This is the partition on the HSM where Venafi TLS Protect Datacenter will access the encryption keys.
For User Type, select the required user to access the HSM keys on the designated partition.
For Pin, enter the passphrase of the Card Set being used. If Module protection is being used, leave the pin blank.
Select Verify.

Enable Venafi Advanced Key Protect

Venafi Advanced Key Protect is required for Central and Remote HSM Private Key Generation. In addition, Venafi Code Signing Certificate Private Key Storage requires this feature to be enabled.

To enable Venafi Advanced Key Protect:

Open the Venafi Configuration Console.
Select Enable Advanced Key Protect in the Actions panel.
Review the information and confirm the action.
Restart the IIS, Venafi Platform, and Logging services:
1. Select the Product node.
2. Select Website and then select Restart.
3. Select Venafi Platform and then select Restart.
4. Select Logging and then select Restart.

Using HSM-protected encryption keys

HSM-protected AES keys can be generated to encrypt data stored in the Venafi TLS Protect Datacenter Secret Store.

To generate an AES key:

Open the Venafi Configuration Console.
Select the Connectors node.
Select the HSM Connector generated in an earlier step.
Select Properties in the Actions panel under Encryption Driver.
Enter your Venafi TLS Protect Datacenter user credentials if required.
Select New Key.
On the Create New HSM Key page, enter a Name and select a Type for the key.
Select Create.
Select Apply.
Select OK.
To list the newly created key and its protection type, open a command prompt and run the following command:
```
nfkminfo -l
```

HSM Central Private Key Generation

Venafi TLS Protect Datacenter uses the Entrust nShield HSM for private key generation for SSH keys and certificates.

Certificate Authority (CA) template objects are used in Venafi TLS Protect Datacenter to manage the certificate lifecycle. Creating one is a prerequisite to HSM Central Key Generation. For more information, see the Venafi online documentation.

Configure the Venafi platform policy to enable the Entrust nShield HSM for central HSM key generation:

Log in to admin console: https://[IP_address_of_Venafi_TLS_Protect_Datacenter]/vedadmin.
Select Policy.
Select Certificate.
Under Other Information, select your HSM Connector in the Key Generation drop-down menu.
Select Save.

Generate the certificate:

Select Policy.
Select Add > Certificates > Certificate.
In the General Information tab, enter the required information.
For Management Type, select Provisioning or Enrollment.
For CSR Generation, select Service Generated CSR.
For Generate Key/CSR on Application, select No.
In the Subject DN tab, enter the required information.
In the Private Key tab, enter the key information.
In the Other Information tab, search for the previously configured CA Template.
Select Save.
Select the newly generated certificate from the policy tree. The Certificate Status should be OK.
Select Renew Now.
After a minute, select Refresh. The certificate details will appear at the bottom of the screen.
If you selected Provisioning for Management Type, associate the certificate to the intended application object.
Check to see if the certificate was installed on this application server.

HSM Remote Private Key Generation

Venafi TLS Protect Datacenter uses the Entrust nShield HSM for private key generation on a remote machine hosting an application server.

There are many configurations possible for HSM Remote Private Key Generation. Not all were tested as part of the Venafi TLS Protect Datacenter integration testing.

Certificate Authority (CA) template objects are used in Venafi TLS Protect Datacenter to manage the certificate lifecycle. Creating one is a prerequisite to HSM Remote Key Generation. For more information, see the Venafi online documentation.

To set up a remote server and configure remote generation settings:

Install and configure the Entrust nShield HSM and Security World on the intended remote application server. The application server needs to be able to use the HSM to generate keys. For more information about compatible application servers, see the Venafi online documentation. See the Entrust nShield Integration Guides which contain integration steps for the intended application server.
Log in to admin console: https://[IP_address_of_Venafi_TLS_Protect_Datacenter]/vedadmin.
In the policy tree, select the application set up on the remote server.
In the Remote Generation Settings, for Private Key Location, select Entrust nShield HSM.

Generate the certificate:

Select Policy.
Select Add > Certificates > Certificate.
In the General Information tab, enter the required information.
For Management Type, select Provisioning.
For CSR Generation, select Service Generated CSR.
For Generate Key/CSR on Application, select Yes.
In the Subject DN tab, enter the required information.
In the Private Key tab, enter the key information.
In the Other Information tab, search for the previously configured CA Template.
Select Save.
Select the newly generated certificate from the policy tree. The Certificate Status should be OK.
In the policy tree, select the application set up on the remote server.
In the Certificate tab, for Associated Certificate, select the previously generated certificate.
Select Save.
In the policy tree, select the certificate.
Select Renew Now.
After a minute, select Refresh. The certificate details will appear at the bottom of the screen.
Check to see if the certificate was installed on the remote application server.
To list the newly created key and its protection type, open a command prompt on the remote application server and run the following command:
```
nfkminfo -l
```

Code signing

Venafi CodeSign Protect can store private code signing keys in the Entrust nShield HSM. This section of the document describes the basic steps used to achieve this functionality for the integration. For more detailed procedures, see the Venafi online documentation.

Certificate Authority (CA) template objects are used in Venafi TLS Protect Datacenter to manage the certificate lifecycle. Creating one is a prerequisite to CodeSign. For more information, see the Venafi online documentation.

To use an HSM for key storage, you must first enable Key Storage on the HSM Connector:

Open the Venafi Configuration Console.
Select the Connectors node.
Select the HSM Component generated in an earlier step.
Select Properties in the Actions panel under Encryption Driver.
Enter your Venafi TLS Protect Datacenter user credentials if required.
Select Allow Key Storage.
Select Apply.
Select OK.

To choose a code signing Administrator:

Open the Venafi Configuration Console.
Select the System Roles node.
Select Add CodeSign Protect Administrator in the Actions panel.
Select a user to gain CodeSign Protect Administrator rights.

To create a code signing flow:

Open the Venafi Configuration Console.
Under the Venafi Code Signing node, select Custom Flows.
Select Add new Code Signing Flow in the Actions panel.
Enter a name for the Code Signing Flow.
Select the newly created Code Signing Flow and add an approver through the Actions panel.

To create an environment template for the code signing project:

Open the Venafi Configuration Console.
Under the Venafi Code Signing node, select Environment Templates.
Select Certificate in the Actions panel under Add Single Template.
Enter a name for the Code Signing Environment Template.
In the Properties window that appears, enter the Description, Certificate Container, and Signing Flow within the Settings tab.
Open the Certificate Authority tab and search for the previously configured CA Template. Select Add.
Open the Keys tab and select which key sizes to allow.
Open the Key Storage and open the drop-down menu.
Select the previously created HSM Connector.
Enter any optional information in the remaining tabs.

To create a new code signing project:

Log in to Aperture: https://[IP_address_of_Venafi_TLS_Protect_Datacenter]/Aperture/codesign.
Select Projects.
Select Create Project.
Enter a Project Name and Description.
Select Create.

To create an environment for the project with a new HSM private key and certificate:

Select the Environments tab.
Select Create.
Enter the Environment Name.
For Environment Type, select Certificate & Key.
For Environment Template, select the previously created Environment Template.
Optionally enter a value for Time Constraint and IP Restrictions.
Select Next.
Signing Flow should list your code signing flow and Key Storage Location should list your HSM Connector.
For Creation Type, select Create new key.
For Certificate Provider, select a CA.
For Key Algorithm, select a key algorithm.
Enter any other necessary information for the certificate.
Select Create Environment.
Select Submit for Approval to generate a new certificate and private key once it is approved.

To create an environment for the project with an existing HSM private key and certificate:

Select the Environments tab.
Select Create.
Enter the Environment Name.
For Environment Type, select Certificate & Key.
For Environment Template, select the previously created Environment Template.
Optionally enter a value for Time Constraint and IP Restrictions.
Select Next.
Signing Flow should list your code signing flow and Key Storage Location should list your HSM Connector.
For Creation Type, select Use Existing.
Import an existing certificate or manually enter its details.
Select an existing Private HSM Key and Public HSM Key.
For Certificate Provider, select a CA.
For Key Algorithm, select a key algorithm.
Enter any other necessary information for the certificate.
Select Create Environment.
Select Submit for Approval to generate a new certificate and private key once it is approved.

To approve the project:

Log in to Aperture: https://[IP_address_of_Venafi_TLS_Protect_Datacenter]/Aperture/codesign.
Select Approvals.
Select Pending Approvals.
Select the request.
Select Approve/Reject.
Enter a Comment for the approval.
Select Approve.
If you selected the option to generate new keys, the keys are now created on the Entrust nShield HSM. To list it, open a command prompt and run the following command:
```
nfkminfo -l
```