Configuring KeyControl Vault as an HSM Client using an nShield HSM

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

Before You Begin 

For the nShield HSM server that you want to connect to KeyControl Vault, 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 Vault account with Security Admin privileges.

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

FIPS 140-2 Level 3

The following details apply where nShield HSMs are configured in a FIPS 140-2 Level 3 compliant Security World environment.

Security World Files – For each nShield HSM, the following files must be present and up to date in KeyControl Vault. These files are supplied in the world.zip file uploaded when configuring the HSM:

  • world

  • A module_<ESN> file for each module that KeyControl uses

  • A cards_<IDENT> file for each card set that is to be used

  • A card_<IDENT>_<NUMBER> file for each card in each card set that is to be used to provide FIPS authorization

These files are not updated automatically. You must ensure that they are synchronized whenever the Security World is updated on the module. For more information, see ‘Creating a Security World’ in your HSM User Guide. The updated files should be in included in a world.zip archive and updated using the 'Upload Security World' action on the nShield HSM Server Settings page.

Smart cards – In FIPS 140-2 Level 3 Security Worlds, an ACS or OSC card must be loaded in the HSM or presented using a remote admin client. A card from either the ACS or an OCS is required to authorize most operations, including the creation of keys and OCSs. Cards are usually configured when setting up an HSM, so Entrust recommends leaving one of the configured OCS cards in the HSM slot to satisfy this requirement.

Smart card serials numbers – nShield HSMs include a security feature that checks the serial numbers of the cards as well as checking they are part of an OCS for this HSM. This allows the admin to disable a card that is mislaid for example. In KeyControl, you can specify whether all cards are accepted, no cards are accepted, or cards in a specific list are accepted. Card serial numbers are 16 decimal digits and, if you enable the option, KeyControl checks that the card in use matches one of the serial numbers listed.

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 Vault on nShield. Please see your nShield documentation.

    Important: For KeyControl Vault clusters, you will need to authenticate the IP address and keyhash for each KeyControl Vault 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).

    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.

    The Softcard Label and Softcard Password must meet the following requirements:

    Softcard Label

    • At least 8 characters

    • No more than 31 characters

    • Can include uppercase, lowercase, numbers, and special characters

    • No space or tab character

    Softcard Password

    • At least 8 characters

    • No more than 127 characters

    • At least 1 uppercase

    • At least 1 lowercase

    • At least 1 number

    • No space or tab character

  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 Vault 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 Vault boots, or if the correct keys cannot be located, trust cannot be established with the HSM and KeyControl Vault is not allowed to begin servicing key requests.

    If you remove the HSM from the KeyControl Vault 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 Vault's hardware configuration, booting KeyControl Vault 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 Vault Masterkey Recovery procedure is used which requires the admin key that had been downloaded when KeyControl Vault was installed.

    Root-of-Trust mode using Password

    The HSM's softcard password is used to wrap the HSM configuration file. When KeyControl Vault boots, the WebGUI will prompt for the HSM password. Only when the password is correctly entered is KeyControl Vault 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 Vault.

What to Do Next