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

The HSM Connector gets created and displayed under the Encryption Connectors section under Platform Connectors.

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 by selecting Enable.
Restart the IIS, Venafi Platform, and Logging services:

Select the Product node. Under Windows Services do the following:
1. Select Website and then select Restart in the Actions panel.
2. Select Venafi Platform and then select Restart in the Actions panel.
3. Select Logging and then select Restart in the Actions panel.

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

Keys with module protection:
 key_pkcs11_ua63b67f4b141c2babd1f5f47e7aab4a3f68fbb851 `5cmodulekey'

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]/Aperture.
In the Application Menu in the top right side of the application, select TLS Protect.
Select Policy Tree under the TLS Protect Menu.
Select Policy, on the left pane.
On the right pane, select the Certificate tab.
Under Other Information, select your HSM Connector in the Key Generation drop-down menu.
Select Save.

Generate the certificate:

Select Policy.
Select Add > Certificates > The Certificate Type you Want.
In the General Information tab:
1. Enter the Certificate Name and another other required information.
2. For Management Type, select Provisioning or Enrollment.
In the CSR Handling tab:
1. For CSR Generation, select Service Generated CSR.
2. 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, Refresh the browser window.

Select the certificate and the certificate details will appear.
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.

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.
1. Select Standard in the Actions panel.
2. Select Apply.
  - Select OK.

To create an environment template for the code signing project:

Open the Venafi Configuration Console.
Under the 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.
1. 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.
Select Apply and then OK.

To create a new code signing project:

Log in to Aperture: https://[IP_address_of_Venafi_TLS_Protect_Datacenter]/Aperture.
In the Application Menu in the top right side of the application, select CodeSign Project.
Select Projects under the CodeSign Project Menu.
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 Key in HSM.
Select an existing Private HSM Key and Public HSM Key.
Import an existing certificate or manually enter its details.
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.
In the Application Menu in the top right side of the application, select CodeSign Project.
Select Approvals under the CodeSign Project Menu.
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

Keys with module protection:
 key_pkcs11_ua1cac4e0dea2a281c70ace86ddc318742658f23c2 `RSA 2048 723b231b04a24a70adeda208d5dbb5c1'
```