Configuring KeyControl as a Luna Cloud HSM Client with a Single Cluster Certificate

When you connect a KeyControl cluster to a hardware security module (HSM), you can create one certificate for the KeyControl cluster that you can use for all KeyControl nodes or you can have an individual certificate for each node in the KeyControl cluster.

The following procedure describes how to configure KeyControl as an HSM client that uses a single certificate for the entire cluster. If you want to use individual certificates for each node, see Configuring KeyControl as a Luna HSM Client with Individual Node Certificates.

Important: You can only configure both the Luna Cloud HSM and the Luna HSM if you are forming a cluster.

Before You Begin

For the HSM server that you want to connect to KeyControl, 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 that you want to assign to KeyControl on all of the HSM servers.

You will also need:

A KeyControl 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

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 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 
```
Log into the KeyControl webGUI using an account with Security Admin privileges.
In the top menu bar, click Settings.
In the System Settings section, click HSM Server Settings.
On the HSM Server Settings page, select Thales HSM from the Type drop-down menu.

On the Thales HSM Server Settings page, select the Luna Cloud 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.
Port	Enter the port number to use for the HSM server.
Partition Label or HA Group Name	Enter the partition label for the partition on the HSM server that KeyControl 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 partition or the Crypto Officer (CO) password for Luna HSM modules version 7 and above.
Service Client Bundle	Click Browse to specify the location of the service client bundle that you received when you configured the HSM.
Session Timeout	The length of time KeyControl keeps the communication session open with an HSM server. When the session expires, a new session is created with the same timeout value. The default is 30 minutes.
Admin Key ID	Indicates whether an Admin Key already exists on the HSM.

Click Apply, then click Proceed at the prompt. Do not test the connection yet.
Select Actions > Generate Client Certificate to download the cluster certificate that all KeyControl nodes can use. KeyControl automatically saves client-name.pem file to your browser's default download location.

For example, if you use the default client name KC_Cluster, the cluster certificate name would be KC_Cluster.pem.

Upload the cluster certificate to the root directory on the HSM server. For example:

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

KC_Cluster.pem             100% 1164     1.1KB/s   00:00

Using a shell account, log into the HSM server and:
1. Register the new KeyControl client using the same client name you specified in the webGUI for both the client name and hostname.
  
  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 client.
For example, if you want the KeyControl client KC_Cluster 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_Cluster -hostname KC_Cluster
'client register' successful
Command Result : 0 (Success)
[hsm1] lunash:>client assignPartition -client KC_Cluster -partition KC_partition1
'client assignPartition' successful
Command Result : 0 (Success)
[hsm1] lunash:>exit
```
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.