This document provides instructions for setting up nShield Connect (nShield) as a HSM provider for PrivX. This integration allows PrivX to store and/or encrypt its cryptographic keys with HSM.

These instructions are only applicable to fresh deployments: existing PrivX deployments cannot be integrated with HSM.

These instructions are to be used together with the PrivX-setup instructions provided in the PrivX Administrator Manual.

Disclaimers

This document includes instructions regarding third-party products by nCipher Security (nCipher). These instructions are provided for general guidance only.

Documentation involving third-party products include setting up nShield clients. The instructions in this manual were verified against nShield Security World software version 12.60.5. These instructions will need to be adapted when using other versions of nCipher.

SSH Communications Security Corporation does not make any warranties as to the accuracy, reliability, or usefulness of these instructions, nor guarantee that the content related to third-party products is up to date.

SSH Communications Security Corporation does not provide any warranties regarding third-party products, such as nShield, nor provide any support or other services for third- party products.

For instructions about setting up and operating nCipher products, we always recommend that you consult the official vendor documentation intended for the specific version(s) of nCipher products in your use and/or directly contact nCipher representatives or support.

It is always your responsibility to define the final production setup for the nCipher products that you use.

Prerequisites

Check and ensure the following before performing the procedures in this document:

• Your nShield HSM must be running on Security World software version 12.60.5 or later.

• The nShield Security World must have a Remote File System (RFS) for storing PrivX cryptographic secrets.

• You have familiarized yourself with the PrivX-deployment prerequisites and setup instructions. Note that these differ between single-server and HA deployments.

• Obtain the following permissions:

  • Permissions for enrolling clients to your nShield HSM.

  • Root-terminal access to machines where PrivX server shall be installed (PrivX machines).

• Obtain the nShield-client software packages.

Integration Steps

The high-level workflow for nShield-Connect integration involves:

1. Connecting PrivX machines to nShield HSM.

2. Setting up PrivX-server software on PrivX machines.

These steps are described in more detail in the following sections.

Connecting PrivX Machines to nShield HSM

Set up client access from machines where PrivX shall be installed (PrivX machines). This involves:

• Installing nShield client software on your PrivX machines. You will at least need to install the hwsp and ctls packages.

• Setting up authentication between PrivX machines and nShield HSM.

• Enrolling your PrivX machines as clients to your nShield HSM.

• Creating a slot on your nShield HSM for PrivX use. You must also obtain the slot ID, required later for configuring PrivX.

You may verify your setup with:

# /opt/nfast/bin/enquiry

Ensure from the output that you have at least one operational module, similar to the following:

Server:
  enquiry reply flags  none
  enquiry reply level  Six
  serial number        3C09-02E0-D94A
  mode                 operational
  version              12.60.5
...
Module #1:
  enquiry reply flags  UnprivOnly
  enquiry reply level  Six
  serial number        3C09-02E0-D94A
  mode                 operational
  version              3.4.2
...

For more detailed instructions about setting up nShield clients, please refer to your nShield vendor documentation.

Setting Up PrivX-Server Software on PrivX Machines

Set up PrivX-server software on your PrivX machines according to the PrivX Administrator Manual, while paying attention to the following points.

• After installing the PrivX rpm package but before postinstall, provide the privx user sufficient permissions for running nShield-client libraries:

  1. Ensure the library has execute permissions:
     # chmod +x /opt/nfast/toolkits/pkcs11/libcknfast.so

  2. Append the following line to /opt/nfast/cknfastrc:
     CKNFAST_OVERRIDE_SECURITY_ASSURANCES=all

  3. Make sure the privx user belongs to a group that owns /opt/nfast:
     # chown -R nfast:nfast /opt/nfast
# usermod -a -G nfast privx

• You will be prompted for HSM settings during postinstall. Provide them as follows:

  Enable pkcs11 keyvault support? [y/N]
  To enable, enter y

  Select pkcs11 provider [1-4]:
  To select nCipher HSM, enter 4

  Enter pkcs11 provider library file path:
  Enter /opt/nfast/toolkits/pkcs11/libcknfast.so

  Enter pkcs11 slot:
  Enter the slot ID (not the slot index).

  Enter pkcs11 pin: and Enter pkcs11 pin again:
  Enter and verify the password of the PrivX slot.

  After this, proceed with setup as normal. You should have access to the PrivX GUI after postinstall completes.
  If you need to set up additional PrivX servers, duplicate the PrivX-server setup to other PrivX machines as described in the PrivX Administrator Manual.