Configuring the Luna Network HSM 7 for Clustering

The following procedures will allow you to set up clustering on the Luna Network HSM 7, 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, and Luna HSM Client 10.6.0 to use clusters.

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.

>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.

PUT /api/lunasa/hsms/{hsmid}

>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.

>The Luna Network HSM 7 must have only a single network interface configured (see Configuring IP and Network Parameters). All members of a cluster must be able to communicate bi-directionally with all other members.

To configure the appliance for clustering

1.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.Turn off Per-Key Authorization by setting partition policy 40 to 0.

PUT /api/lunasa/hsms/{hsmid}/partitions/{partitionid}/policies/{policyid}

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}

2.Enable the cluster service on the appliance (serviceid: cluster, actionid: enable). Enabling the service means that it will be automatically restarted in the case of an appliance reboot.

POST /api/lunasa/services/{serviceid}/actions/{actionid}

3.Start the cluster service on the appliance (serviceid: cluster, actionid: start).

NOTE   The cluster service cannot be started if a user partition has not yet been created (refer to step 1).

POST /api/lunasa/services/{serviceid}/actions/{actionid}

4.Check the status of the cluster service (enabled 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.

GET /api/lunasa/services/{serviceid}

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 Configuring the Luna Network HSM 7 for Clustering.

PUT /api/cluster/config

{
  "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.

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).

PUT /api/cluster/config

{
  "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.

7.[Optional] Check that the network configuration was set correctly.

GET /api/cluster/config

LunaSH

Prerequisites

>The Luna Network HSM 7 must be configured and accessible over the network.

>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).

>HSM policy 21: Force user PIN change after set/reset must be set to OFF (see Setting HSM Policies Manually).

>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.Create a template file to initialize the partition with your desired policy settings. Partition policy 40: Require Per-Key Authorization Data must be set to 0. You must create the file yourself -- it is not possible to export the default template file from the partition using LunaSH.

Refer to Editing a Partition Policy Template. Use pscp/scp to transfer the policy file to the appliance filesystem. Your template file must contain the following line:

40:"Require Per-Key Authorization Data":0:1:0

CAUTION!   Changing partition policies after you have created and are using keyrings can cause unwanted behavior. Ensure that you have configured all your desired policy settings before you continue.

c.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 in the product documentation.

d.Initialize the Crypto Officer (CO) role in LunaSH.

Refer to Initializing the Crypto Officer Role.

2.Start the cluster service on the appliance, or, if you want the service to be started automatically on appliance reboot, enable the cluster service on the appliance.

NOTE   The cluster service cannot be started if a user partition has not yet been created (refer to step 1).

To enable the cluster service on the appliance (optional):

lunash:> cluster enable

The cluster service starts automatically after being enabled.

To start the cluster service without enabling it:

lunash:> service start cluster

3.Check the status of the cluster service (enabled and/or running).

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.

lunash:> cluster status

4.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 Configuring the Luna Network HSM 7 for Clustering.

lunash:> cluster config -service core -ipaddress <appliance_IP>

5.[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.

6.[Optional] Check that the network configuration was set correctly.

lunash:> cluster config show