Installing and Configuring the Cluster Package
The following procedures will allow you to install the lnh_cluster secure package on the Luna Network HSM 7, and configure the appliance for a cluster, using REST API calls or LunaSH. This procedure must be completed whether you are creating a new cluster (see Creating a Cluster), or joining an existing cluster (see Adding a New Member to an Existing Cluster).
NOTE Thales recommends Luna Appliance Software 7.8.3 with cluster package 1.0.3, Luna HSM Firmware 7.8.2,
CAUTION! Only one cluster can exist on the appliance. Do not attempt to:
>create multiple application partitions on the HSM
>create more than one cluster on the appliance
>join a second cluster when the appliance is already a member of a different cluster
REST API
Prerequisites
>The Luna Network HSM 7 must be configured and accessible over the network. All members of a cluster must be able to communicate bi-directionally with all other members. Refer to Configuring IP and Network Parameters.
>If you are setting up a cluster on a multifactor quorum-authenticated HSM, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.
>If you plan to use REST API to work with clusters, set up the webserver service so that the appliance can accept calls from your web application.
Refer to Webserver Setup.
After configuring the webserver service, you must synchronize the HSM time with the time on the appliance.
lunash:> hsm time sync
>The Luna Network HSM 7 must be initialized.
>Thales recommends Luna Appliance Software 7.8.3 with cluster package 1.0.3, Luna HSM Firmware 7.8.2,
Refer to:
•Updating the Luna Network HSM 7 Appliance Software
•Updating the Luna HSM Firmware
>The Luna Network HSM 7 and any clients must have NTP configured, or have their system clocks synchronized manually. Clocks must be synchronized before starting the cluster service:
•Using NTP (actionid: synchronize): POST /api/lunasa/ntp/actions/{actionid}
•Manually: PUT /api/lunasa/time
CAUTION! If the system clock is adjusted after the cluster certificate is created, the certificates might not be valid due to date/time. For example, if the certificate is generated while the system clock is ahead by a few minutes, and the clock is then corrected, the certificate will not be valid until the clock catches up to the time it was set to when the cert was created. If the current system time does not fall within the certificate's range of validity, the cluster service fails to start. Refer to known issue Known and Resolved Issues.
To configure the appliance for clustering
1.Open a session to the Luna REST API on the Luna Network HSM 7.
2.Create a new application partition or provision an existing partition for cluster and keyring creation.
a.Create a new application partition, specifying a V1 partition.
CAUTION! Using a V0 partition to create a cluster can cause undesired behavior and require you to factory reset the cluster service and recreate the partition.
Only one V1 partition can exist on an appliance configured for clustering; do not create more than one V1 partition.
POST /api/lunasa/hsms/{hsmid}/partitions
b.Initialize the partition and the Partition Security Officer (PO) role.
NOTE The partition that will hold the SKS Master Key (SMK) on each cluster member must use the same cloning domain. If you are configuring this appliance to join an existing cluster, ensure that you use the same domain string or PED key that was used to initialize the partition on the primary member.
PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}
c.Log in with the new Partition SO credential, and set partition policy 40: Require Per-Key Authorization Data to 0. Confirm the policy change task (actionid: start).
i.POST /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/login
ii.PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/{policyid}
iii.POST /tasks/{taskid}/actions/{actionid}
CAUTION! Changing partition policies after you have created and are using clusters can cause unwanted behavior. Ensure that you have configured all your desired policy settings before you continue. This includes policies for Activation on Multifactor Quorum-Authenticated Partitions.
d.Initialize the Crypto Officer (CO) role (roleid: co).
NOTE If HSM policy 21: Force user PIN change after set/reset is enabled (this is the default setting), the CO must change the password/PED key from its initial value before any other actions are permitted.
i.PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid}
ii.PATCH /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/roles/{roleid}
3.Install the lnh_cluster secure package on the Luna Network HSM 7.
a.Transfer the secure package update file to the Luna Network HSM 7 using pscp or scp.
pscp <path>/lnh_cluster-1.0.#-###.spkg admin@<appliance_host/IP>:
b.Log in as HSM SO.
POST /api/lunasa/hsms/{hsmid}/login
c.[Optional] Verify that the secure package file is present on the Luna Network HSM 7.
d. [Optional] Verify the package file, specifying the authorization code you received from Thales.
POST /api/lunasa/packageFiles?VerifyOnly=true
e.Install the lnh_cluster secure package.
POST /api/lunasa/packageFiles?VerifyOnly=false
f.Restart the cluster service (serviceid: cluster, actionid: restart). This step completes the service installation.
POST /api/lunasa/services/{serviceid}/actions/{actionid}
4.Enable the cluster service on the appliance (serviceid: cluster). Enabling the service means that it will be automatically restarted in the case of an appliance reboot.
PATCH /api/lunasa/services/{serviceid}
{
"onBoot": true
}
5.Check the status of the cluster service ("onBoot": true and running). It may take several minutes for the cluster service to start, and the next step will fail if it is still starting up. This resource reports "status": "stopped" until the cluster service startup has finished.
GET /api/lunasa/services/{serviceid}
6.Set the IP address to use for the core cluster traffic on this member appliance. This must be the same IP address as one of the appliance's network interfaces.
{
"service": "core",
"IpAddress": "127.0.0.1"
}
NOTE If you have configured more than one network interface on this Luna Network HSM 7, Thales recommends restarting the cluster service before continuing.
7.[Optional] You can also bind the administrative and cryptographic traffic to the cluster to specified network devices, including assigning a port number from a limited range (admin: 50075-50079, crypto: 50055-50059).
{
"service": "crypto",
"interface": "eth0",
"port": 50075
}
CAUTION! In this release, changing the default port used for crypto operations on the cluster (50052) can cause communication problems between cluster members. Refer to known issue LUNA-26485.
8.[Optional] Check that the network configuration was set correctly.
You can now create a new cluster on the appliance (see Creating a Cluster) or join a cluster on a different appliance (see Adding a New Member to an Existing Cluster).
LunaSH
Prerequisites
>The Luna Network HSM 7 must be configured and accessible over the network. All members of a cluster must be able to communicate bi-directionally with all other members. Refer to Configuring IP and Network Parameters.
>If you are setting up a cluster on a multifactor quorum-authenticated HSM, you require a local or remote Luna PED. Refer to Multifactor Quorum Authentication for setup procedures.
>The Luna Network HSM 7 must be initialized (see Initializing the HSM).
>Thales recommends Luna Appliance Software 7.8.3 with cluster package 1.0.3, Luna HSM Firmware 7.8.2,
Refer to:
•Updating the Luna Network HSM 7 Appliance Software
•Updating the Luna HSM Firmware
•Updating the Luna HSM Client Software
>The Luna Network HSM 7 and any clients must have NTP configured, or have their system clocks synchronized manually. Clocks must be synchronized before starting the cluster service. Refer to NTP on Luna Network HSM 7 or Setting the System Date and Time.
CAUTION! If the system clock is adjusted after the cluster certificate is created, the certificates might not be valid due to date/time. For example, if the certificate is generated while the system clock is ahead by a few minutes, and the clock is then corrected, the certificate will not be valid until the clock catches up to the time it was set to when the cert was created. If the current system time does not fall within the certificate's range of validity, the cluster service fails to start. Refer to known issue Known and Resolved Issues.
To configure a partition for clustering
1.Create a new application partition for cluster and keyring creation.
a.Create a new application partition in LunaSH, specifying a V1 partition.
CAUTION! Using a V0 partition to create a cluster can cause undesired behavior and require you to factory reset the cluster service and recreate the partition.
Only one V1 partition can exist on an appliance configured for clustering; do not create more than one V1 partition.
Refer to Creating or Deleting an Application Partition.
b.Initialize the partition and the Partition Security Officer (PO) role in LunaSH, specifying the policy template filename.
NOTE The partition that will hold the SKS Master Key (SMK) on each cluster member must use the same cloning domain. If you are configuring this appliance to join an existing cluster, ensure that you use the same domain string or PED key that was used to initialize the partition on the primary member.
Refer to Initializing an Application Partition.
c.Set partition policy 40: Require Per-Key Authorization Data to 0 (OFF).
Refer to Setting Partition Policies Manually.
d.Initialize the Crypto Officer (CO) role in LunaSH. If necessary, change the initial CO credential.
Refer to Initializing the Crypto Officer Role and Changing a Partition Role Credential.
2.Install the lnh_cluster secure package on the Luna Network HSM 7.
a.Transfer the secure package update file to the Luna Network HSM 7 using pscp or scp.
pscp <path>/lnh_cluster-1.0.#-###.spkg admin@<appliance_host/IP>:
b.Using a serial or SSH connection, log in to the appliance as admin (see Logging In to LunaSH).
c.Log in as HSM SO (see Logging In as HSM Security Officer).
lunash:> hsm login
d.[Optional] Verify that the secure package file is present on the Luna Network HSM 7.
lunash:> package listfile
e. [Optional] Verify the package file, specifying the authorization code you received from Thales.
lunash:> package verify <filename>.spkg -authcode <code_string>
f.Install the secure package for the cluster service.
lunash:> package update lnh_cluster-1.0.#-###.spkg -authcode <authcode_string>
g.Run the restart command for the cluster service, as prompted. This step completes the service installation procedure.
lunash:> service restart cluster
NOTE The cluster service cannot be started if a user partition has not yet been created (refer to step 1).
The new cluster and keyring commands become available when you open a new LunaSH session.
3.Check the status of the cluster service (enabled and/or running).
lunash:> cluster status
NOTE It can take up to 1-2 minutes for the cluster service to start. Until startup is complete, the status is reported as starting.
4.[Optional] If you want the service to be started automatically on appliance reboot, enable the cluster service on the appliance.
lunash:> cluster enable
5.Set the IP address to use for the core cluster traffic on this member appliance. This must be the same IP address as one of the appliance's network interfaces.
NOTE The core IP address cannot be changed later, except after factory reset. Refer to Installing and Configuring the Cluster Package.
lunash:> cluster config -service core -ipaddress <appliance_IP>
6.[Optional] You can also bind the administrative and cryptographic traffic to the cluster to specified network devices, including assigning a port number from a limited range (admin: 50075-50079, crypto: 50055-50059).
lunash:> cluster config -service admin [-interface <netdevice>] [-port <port>]
lunash:> cluster config -service crypto [-interface <netdevice>] [-port <port>]
CAUTION! In this release, changing the default port used for crypto operations on the cluster (50052) can cause communication problems between cluster members. Refer to known issue LUNA-26485.
7.[Optional] Check that the network configuration was set correctly.
lunash:> cluster config show
You can now create a new cluster on the appliance (see Creating a Cluster) or join a cluster on a different appliance (see Adding a New Member to an Existing Cluster).
