Configuring KeyControl as an HSM Client using an nShield HSM

The following procedure describes how to configure KeyControl as an nShield HSM client. You can either use a standalone KeyControl node or a cluster.

Before You Begin 

For the nShield HSM server that you want to connect to KeyControl, make sure you have the following information available:

  • The HSM Server Name, Server IP/FQDN, ESN, Port, and Keyhash.
  • The Security World Bundle file that is provided by the HSM Administrator.

  • Information to create a softcard consisting of a label and password.

You will also need:

  • A KeyControl account with Security Admin privileges.

  • If you are using an on-premise HSM server, you must have access.

Procedure 

  1. Log into the KeyControl webGUI using an account with Security Admin privileges.

    Note: If you are using a cluster, you only need to use the webGUI for one node.

  2. In the top menu bar, click Settings.
  3. In the System Settings section, click HSM Server Settings.

  4. On the HSM Server Settings tab, select nShield HSM.

    The nShield HSM Server Settings window displays the information you will need to continue.

  5. Click the Copy the IP address and keyhashes to the keyboard link and paste them in a text window.

  6. Use the IP address and keyhash to authenticate KeyControl on nShield. Please see your nShield documentation.

    Important: For KeyControl clusters, you will need to authenticate the IP address and keyhash for each KeyControl cluster node.

  7. Copy the Security World Bundle from nShield and place it on your local machine. It should be in the format world.zip.
  8. After reading the Get Started Screen, click Continue.

  9. On the Enrollment screen, complete the following: 

    Note: All information is from the nShield HSM. The Server Name is used for display purposes and the Server IP/FQDN is used for communication.

    Field

    Description

    Server Name

    Enter the FQDN of the nShield HSM.

    Server IP/FQDN

    Enter the IP address or FQDN for the nShield HSM.

    Server ESN

    Enter the nShield Electronic Serial Number (ESN).

    Type

    Select the location of the nShield HSM. This can be On Prem or Cloud.

    Port

    Enter the port used for the nShield HSM.

    Keyhash

    Enter the keyhash of the nShield HSM.

  10. Click Enroll and Continue.
  11. On the Security World screen, click Load File and locate the security world bundle that you downloaded from the nShield HSM.
  12. Click Upload and Continue.

  13. On the Softcard screen, enter the Softcard Label and Softcard Password that you want to use to link to the HSM server.

  14. Click Complete Setup.

    After the setup is complete, you will be returned to the nShield HSM Server Settings page.

    Note: If the configuration failed, then you must select Actions > Reset HSM Configuration before you try again.

  15. Optional: Enable the HSM Root-of-Trust feature by selecting Actions > HSM Root of Trust Mode > Enabled.

    Field

    Description

    Disabled

    HSM Root-of-Trust is not enabled. KeyControl will boot unattended using a unique hardware signature to cryptographically protect the object store.

    Enabled

    HSM Root-of-Trust provides enhanced protection for the contents of the object store. Root-of-Trust is gained when the HSM provides the cryptographic keys necessary to unlock the object store.

    If the HSM cannot be contacted when KeyControl boots, or if the correct keys cannot be located, trust cannot be established with the HSM and KeyControl is not allowed to begin servicing key requests.

    If you remove the HSM from the KeyControl configuration, the HSM Root-of-Trust configuration is also destroyed.

    Root-of-Trust mode using HWSIG

    The hardware signature is used to wrap the HSM configuration file. Unless there is a change to KeyControl's hardware configuration, booting KeyControl will require no user intervention before it can begin servicing requests.

    Virtual machine configuration changes may result in a need to recover the HSM configuration changes. When this happens, the normal KeyControl Masterkey Recovery procedure is used which requires the admin key that had been downloaded when KeyControl was installed.

    Root-of-Trust mode using Password

    The HSM's softcard password is used to wrap the HSM configuration file. When KeyControl boots, the WebGUI will prompt for the HSM password. Only when the password is correctly entered is KeyControl allowed to begin booting.

    The HSM password must be entered on each node of the cluster. For instance, if the entire cluster is restarted, it will only begin servicing requests once the password has been entered on all of then nodes in the cluster.

  16. Select Actions > Test Connection from the Basic tab to ensure that the HSM is fully connected to KeyControl.

What to Do Next