Configuring KeyControl Vault as a Luna HSM Client with Individual Node Certificates

When you connect a KeyControl Vault cluster to a hardware security module (HSM), you can create one certificate for the KeyControl Vault cluster that you can use for all KeyControl Vault nodes or you can have an individual certificate for each node in the KeyControl Vault cluster. If you have a Luna HSM server with the ipcheck feature enabled, you must use unique node certificates.

The following procedure describes how to configure KeyControl Vault as an HSM client that uses unique certificates for each node in the cluster. If you want to use a single certificate that will be shared by all nodes in the cluster, see Configuring KeyControl Vault as a Luna HSM Client with a Single Cluster Certificate.

Before You Begin 

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

  • The HSM server name.
  • The user name and password for an HSM account with Admin privileges.

  • The HSM partition name and password.

  • The client name you want to assign to KeyControl Vault on all of the HSM servers.

You will also need:

  • A KeyControl Vault account with Security Admin privileges.
  • Access to the HSM server via a shell account. The following procedure uses ssh to connect to the server.

Note: The following instructions are specific to the Luna HSM.

Procedure 

  1. Download the HSM server certificate file server.pem from the HSM server to which you want to connect. We recommend that you rename the server.pem certificate file so that you can find the certificate file easily when you need to upload it to KeyControl Vault later in this procedure.

    For example, if your HSM server is hsm1.my-company.com, you could enter:

    # scp admin@hsm1.my-company.com:server.pem ./hsm1cert.pem
admin@hsm1.my-company.com's password: 

server.pem             100% 1155     1.1KB/s   00:00
  2. Log into the KeyControl webGUI using an account with Security Admin privileges.
  3. In the top menu bar, click Settings.
  4. In the System Settings section, click HSM Server Settings.
  5. On the HSM Server Settings page, select Thales HSM from the Type drop-down menu.

  6. On theThales HSM Server Settings page, select the Luna HSM tab and then specify the options you want to use for the HSM server.

    Field

    Description

    State

    Make sure this field is set to Enabled.

    Hostname

    Enter the hostname for the HSM server.

    Partition Label or HA Group Name

    Enter the partition label for the partition on the HSM server that KeyControl Vault will be using.

    Note: Make sure you enter the partition label and not the partition name in this field.

    Partition or
    Crypto Officer (CO) Password

    Enter the password for the KeyControl Vault partition or the Crypto Officer (CO) password for Luna HSM modules version 7 and above.

    Server Certificate

    Click Browse and open the appropriate HSM server certificate file.

    Client Certificate Mode

    Select the Individual Node Certificates radio button so that KeyControl Vault will use a unique certificate for each KeyControl Vault node in the cluster.

    Admin Key ID

    Indicates whether an Admin Key already exists on the HSM.

  7. Click Apply, then click Proceed at the prompt.  Do not test the connection yet.
  8. Navigate to the Client List tab. You should see one entry for each KeyControl Vault node in the cluster.

  9. Select the first node in the list, then select Actions > Generate Client Certificate for node-name.domain-name. KeyControl Vault automatically generates a unique certificate for that node called node-name.domain-name.pem and downloads it to your browser's default download location.

    For example, if the name of the node is KC-1 and it is running on the domain my-company.com, the certificate file would be called KC-1.my-company.com.pem.

  10. Repeat the previous step for each KeyControl Vault node in the cluster.

  11. Upload all certificates to the root directory on the HSM server. For example, if you have two KeyControl Vault nodes, you would copy both KeyControl Vault node certificates to HSM server:

    # scp KC-1.my-company.com.pem admin@hsm1.my-company.com:
admin@hsm1.my-company.com's password: 

KC-1.my-company.com.pem             100% 1164     1.1KB/s   00:00 

# scp KC-2.my-company.com.pem admin@hsm1.my-company.com:
admin@hsm1.my-company.com's password: 

KC-2.my-company.com.pem             100% 1164     1.1KB/s   00:00

  12. Using a shell account, log into the HSM server and:

    1. Register the new KeyControl Vault client using "node-name.domain-name" for both the client name and hostname. The double quotes are required because of the period in the client name.

      Tip: If the registration fails because a client of that name already exists, you either need to delete the existing client or go back to the webGUI, enter an new client name, click Apply, and then download a new cluster certificate that you can upload to the HSM server.

    2. Assign a partition to the KeyControl Vault client.

    For example, if you want the KeyControl Vault client to be assigned to KC_partition1 on hsm1.my-company.com, you could enter:

    # ssh admin@hsm1.my-company.com
admin@hsm1.my-company.com's password:

[hsm1] lunash:>client register -client "KC-1.my-company.com" -hostname "KC-1.my-company.com"
'client register' successful
Command Result : 0 (Success)
[hsm1] lunash:>client register -client "KC-2.my-company.com" -hostname "KC-2.my-company.com"
'client register' successful
Command Result : 0 (Success)
[hsm1] lunash:>client assignPartition -client "KC-1.my-company.com" -partition KC_partition1
'client assignPartition' successful
Command Result : 0 (Success)
[hsm1] lunash:>client assignPartition -client "KC-2.my-company.com" -partition KC_partition1
'client assignPartition' successful
Command Result : 0 (Success)
[hsm1] lunash:>exit

  13. Return to the Thales HSM Server Settings page and click Test. You should see a message that says the HSM connection is OK and that the Admin Key needs to be regenerated.

    To regenerate the Admin key, go to Settings > General Settings > Admin Key Parts, then click Generate New Key. You should get a message that the Admin Key was successfully generated and distributed. To verify this, go back to Settings > System Settings > HSM Server Settings.  The Admin Key ID field should display a GUID for the new Admin Key.