Cluster-Client Connections

Thales provides a client-side script, LNHClientRegistration, to connect Luna HSM Client to a cluster. You must run the script on any Luna HSM Client computers that will create or use keyrings on the cluster. The client requires a specified member Luna Network HSM 7 to use as an entry point to the cluster. All traffic from the client will be directed to this member appliance, although the operations may be performed by other cluster members.

If this client will be used by a customer with monitor privileges in a service provider deployment, you can specify a LunaSH username to associate with the client. This can be the default monitor role, or a custom user with the monitor role assigned (see Creating Custom Appliance User Accounts). The specified user must already exist on the appliance.

Connecting Luna HSM Client to a Cluster

The following procedure will allow you to connect a Luna HSM Client computer to a Luna Network HSM 7 cluster. Each cluster is assigned an index number from 00 to 09 on the client. In this release, the configuration can be viewed only in the crystoki.ini / Chrystoki.conf configuration file; the following entries for each cluster are added to the LunaSA Client section (see Configuration File Summary):

LNHServer##
LNHServerClientCert##
LNHServerClientKey##
LNHServerCAFile##
LNHServerCN##

Prerequisites

>Ensure that you have a supported Luna HSM Client version installed. Thales requires minimum Luna Appliance Software 7.8.5 with the lnh_cluster-1.0.4 package, Luna HSM Firmware 7.8.4, and Luna HSM Client 10.7.2 to use clusters in production environments, or minimum Luna Appliance Software 7.9.0 with the lnh_cluster-1.0.5 package, Luna HSM Firmware 7.8.4, and Luna HSM Client 10.8.0 to migrate keys from Luna application partitions.

CAUTION!   Using Luna HSM Client 10.7.2, running the script while specifying the same common name (usually an IP address) that was used to create an existing NTLS certificate causes the existing NTLS private key to be deleted. To preserve this key, located in <install directory>/cert/client/, save a copy in another location and restore it after running the registration script. Refer to known issue LUNA-32033.

Refer to Updating the Luna HSM Client Software.

>Ensure that you have the following information about each cluster you want to access using this client:

•the Cluster ID

•the IP address for an authorized member appliance that will accept this client's traffic

>If you customize the port numbers for admin traffic to the appliance, you must edit the LNHClientRegistration script to account for these port numbers, or client registration will fail. To update the script, replace all instances of the default admin port 50070 with your configured admin port.

>On AIX, theLNHClientRegistrationscript requiresGNU sed 4.8.

Rundnf install sedto install it before using the script.

>On Windows Server 2025, theLNHClientRegistrationscript requirescurl 8.10.1or newer.

This version was first included in the monthly Windows Server 2025 update released on December 10, 2024 (KB5048667). Ensure that you have this or a more recent update installed.

To connect Luna HSM Client to a cluster member

1.Run the LNHClientRegistration script to connect the client to the cluster, specifying the Cluster ID (-c), the IP address of the member the client will connect to (-i), a Common Name for the client certificate (-n), an optional label for the client (-l), and an optional LunaSH username with a monitor role to associate with this client (-u). This assigns the cluster to the 00 index position on the client.

•Linux/AIX:

# ./LNHClientRegistration.sh -n <client Common Name> -i <IPaddress> -c <clusterID> [-l <optional_client_label>] [-u <monitor_LunaSH_user>]

•Windows PowerShell:

./LNHClientRegistration.ps1 -n <client Common Name> -i <IPaddress> -c <clusterID> [-l <optional_client_label>] [-u <monitor_LunaSH_user>]

•Windows command prompt:

powershell.exe -command "LNHClientRegistration.ps1 -n <client Common Name> -i <IPaddress> -c <clusterID> [-l <optional_client_label>] [-u <monitor_LunaSH_user>]"

2.Run the script again for each additional cluster you wish to add. The options are different as follows, based on your client version:

UsingLuna HSM Client 10.8.0or newer:

Run the script again. Additional clusters are added to the index by UUID and automatically assigned an index number. You can only add a specific cluster in one index position; it is not possible to add the same cluster multiple times with different LunaSH usernames.

UsingLuna HSM Client 10.7.2or older:

Run the script again, including the-moption to indicate that you are adding multiple clusters. Each new cluster added will be assigned to the next incremental index position (01, 02, 03... 09). If all the positions are filled, an error message is returned. Do not add the same cluster multiple times.

Removing a Cluster From the Luna HSM Client

If you are usingLuna HSM Client 10.8.0or newer, theLNHDeleteClusterRegistrationscript allows you to easily remove a cluster from the client index. This script performs a best-effort scan to detect any running applications or processes that are using the cluster. It will not proceed if any active processes are found. This scan may not detect all active processes; ensure that all applications using the cluster are stopped before running the script.

If you are usingLuna HSM Client 10.7.2or older, you must manually delete a cluster from the index.

Prerequisites

>On AIX, theLNHDeleteClusterRegistrationscript has the following dependencies:

GNU sed 4.8

GNU grep 3.7

Rundnf install sed grepto install these before using the script.

>On Windows Server 2025, theLNHDeleteClusterRegistrationscript requirescurl 8.10.1or newer.

This version was first included in the monthly Windows Server 2025 update released on December 10, 2024 (KB5048667). Ensure that you have this or a more recent update installed.

To remove a cluster from theLuna HSM Clientusing the LNHDeleteClusterRegistration script

1.Stop all applications on this client that are using the cluster you will remove.

2.Run theLNHDeleteClusterRegistrationto delete the cluster from the client, specifying the cluster's UUID.

•Linux/AIX:

# ./LNHDeleteClusterRegistration.sh -c<clusterID>

•Windows PowerShell:

./LNHDeleteClusterRegistration.ps1 -c<clusterID>

•Windows command prompt:

powershell.exe -command "LNHDeleteClusterRegistration.ps1 -c<clusterID>"

To remove a cluster from theLuna HSM Clientmanually

1.Stop all applications on this client that are using the cluster you will remove.

2.Edit theLunaSA Client section of the crystoki.ini / Chrystoki.confconfiguration file. Delete the entries for that cluster and save the configuration file.

LunaSA Client = { ReceiveTimeout = 20000; SSLConfigFile = /usr/safenet/lunaclient/bin/openssl.cnf; ClientPrivKeyFile = /usr/safenet/lunaclient/cert/client/ClientNameKey.pem; ClientCertFile = /usr/safenet/lunaclient/cert/client/ClientNameCert.pem; ServerCAFile = /usr/safenet/lunaclient/cert/server/CAFile.pem; NetClient = 1; TCPKeepAlive = 1; LNHServer00 = 1.2.3.4:50052; LNHServerClientCert00 = /usr/safenet/lunaclient/cert/client/c2c94c40-6491-409e-bd3d-16e236544b7f/2.3.4.5.pem; LNHServerClientKey00 = /usr/safenet/lunaclient/cert/client/c2c94c40-6491-409e-bd3d-16e236544b7f/2.3.4.5Key.pem; LNHServerCAFile00 = /usr/safenet/lunaclient/cert/server/c2c94c40-6491-409e-bd3d-16e236544b7f/lnh_ca.pem; LNHServerCN00 = lnh.thalesgroup.com;LNHServer01 = 5.6.7.8:50052; LNHServerClientCert01 = /usr/safenet/lunaclient/cert/client/3fed78e8-58ad-4aec-be5f-4a12a04ff073/2.3.4.5.pem; LNHServerClientKey01 = /usr/safenet/lunaclient/cert/client/3fed78e8-58ad-4aec-be5f-4a12a04ff073/2.3.4.5Key.pem; LNHServerCAFile01 = /usr/safenet/lunaclient/cert/server/3fed78e8-58ad-4aec-be5f-4a12a04ff073/lnh_ca.pem; LNHServerCN01 = lnh.thalesgroup.com;}