Configuring KeyControl as an HSM Client with Individual Node Certificates

You can configure KeyControl to work with a single hardware security module (HSM) server or with multiple HSM servers if you want to ensure High Availability.

In addition, 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. If you have a Safenet LUNA SA server with the ipcheck feature enabled, you must use unique node certificates even if you are using only one HSM server.

The following procedure describes how to configure KeyControl 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 as an HSM Client with a Single Cluster Certificate.

Before You Begin

For each 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. If you are planning to connect multiple Safenet servers, we recommend that you use a different partition name on each server so that you can tell which server is which when you are creating the Safenet HA group during in this procedure.

Note:

If you are planning to connect to multiple Safenet LUNA HSM servers in an HA (High Availability) group, Safenet requires that the partition password be the same on all servers. Safenet also requires that certain configuration options be the same on all HSM servers in the group. For details, see your Safenet LUNA documentation.

The client name you want to assign to KeyControl on all of the HSM servers that you want to connect to KeyControl. This client name must be unique on all of these HSM servers.

You will also need:

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

Note:

The following instructions are specific to the SafeNet LUNA SA HSM from Gemalto.

Procedure

Download the HSM server certificate file server.pem from each HSM server to which you want to connect. We recommend that you rename the server.pem certificate file so that you know which HSM server goes with which certificate file.

For example, if your HSM servers are hsm1.my-company.com and hsm2.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 
					
# scp admin@hsm2.my-company.com:server.pem ./hsm2cert.pem
admin@hsm2.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 tab, specify the options you want to use for the first HSM server.

Field

Description

State

Make sure this field is set to Enabled.

Hostname

Enter the hostname for one of your HSM servers.

Partition Label or HA Group Name

Enter the partition label for the partition on that 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 SafeNet LUNA modules version 7 and above.

Important:

If you are planning to connect multiple Safenet LUNA servers, the partition or CO password must be the same for all of that HSM servers to which you want to connect.

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 will use a unique certificate for each KeyControl node in the cluster.

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.

If you want to connect this KeyControl cluster to additional HSM servers, do the following:

Change the Hostname to the name of one of the additional HSM servers.
If needed, change the Partition Label or HA Group Name to the partition that KeyControl should use on this server. We recommend that you use a different partition name on each server so that you can tell which server is which when you are creating the Safenet HA group later in this procedure.
In the Server Certificate field, click Browse and select the server certificate for this HSM server.
Click Apply, then click Proceed at the prompt.
Repeat this procedure for each HSM server that you want to add.

Note:

Because Safenet requires that all HSM servers in a High Availability group have the same password, you do not need to enter the password for any additional HSM servers. KeyControl automatically uses the most recent password entered for all servers in the group.

Navigate to the Client List tab. You should see one entry for each KeyControl node in the cluster.
Select the first node in the list, then select Actions > Generate Client Certificate for node-name.domain-name. KeyControl 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.
Repeat the previous step for each KeyControl node in the cluster.

Upload all certificates to the root directory on each HSM server that you want to use. For example, if you have two KeyControl nodes and you are using two HSM servers, you would copy both KeyControl node certificates to both HSM servers:

# 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
 					
# scp KC-1.my-company.com.pem admin@hsm2.my-company.com:
admin@hsm2.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@hsm2.my-company.com:
admin@hsm2.my-company.com's password: 

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

Using a shell account, log into each HSM server and:

Register the new KeyControl 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 servers.

Assign a partition to the KeyControl client.

For example, if you want the KeyControl client to be assigned to KC_partition1 on hsm1.my-company.com and to KC_partition2 on hsm2.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
					
# ssh admin@hsm2.my-company.com
admin@hsm2.my-company.com's password:

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

If you have registered the KeyControl nodes with multiple HSM servers, you need to create a Safenet HA group that links all of those servers together before you can use the HSM connection. For details, see Configuring a Safenet HA Group.

If you have connected KeyControl to only one HSM server, return to the KeyControl 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.