IBM Cloud Docs
Deploying a hardware security module (HSM) to use with Key Protect on Satellite

Deploying a hardware security module (HSM) to use with Key Protect on Satellite

Key Protect on Satellite must connect to two on-prem customer-managed hardware security modules (HSMs), which is the root of trust store for master encryption keys and provides the FIPS certified cryptographic boundary for key operations performed by Key Protect.

To work correctly with Key Protect, these HSMs must not only be of a specific type, but must be configured to work specifically with Key Protect.

Overview

Before a Key Protect on Satellite location can be deployed, HSMs must both exist and have been configured to create the kinds of keys that work with Key Protect. At a high level, this is a two step process:

  • The purchase and initial setup of the HSMs. Users are responsible to purchase and setup the HSMs within their own infrastructure. For more information about the type of HSMs that are supported, check out About the HSMs supported for use with Key Protect on Satellite. Because these HSMs are not purchased from IBM, make sure to follow the relevant product documentation from your HSM vendor in regard to setup, maintenance, and resolving service incidents. IBM is only responsible for errors that result from issues with the Key Protect service, not from any issues with your HSM.
  • Configure the HSMs to work with Key Protect. In order for an HSM to work properly with Key Protect, it must not only have a partition dedicated to work with Key Protect, but it also must be configured to produce keys using the key algorithms supported by Key Protect. The labels for these keys must be provided as part of deploying the Key Protect console.

About the HSMs supported for use with Key Protect on Satellite

Key Protect requires particular HSMs running specific firmware and software versions to run properly. Specifically, Key Protect supports:

  • Thales SafeNet Luna Network A730 and A750 model HSMs. The A750 is an enterprise-grade appliance, able to handle up to 10000 AES-GCM / ECC P256 concurrent transactions per second (TPS) or up to 5000 RSA-2048 TPS. These HSMs are high efficient and powerful appliances designed to provide mainly over the network cryptographic services. To do so, they always provide four physical adapters.
  • Application/OS version 7.4.2.
  • Firmware version 7.3.3.

Older firmware and application/OS version are not explicitly supported as using them runs the risk of having issues if Key Protect adds features that depend on later hardware or software versions. For this reason, make sure to keep your firmware and software versions as up to date as possible.

Depending on the version of the software application and supported FIPS 140-2 Level 3 firmware, the upgrade path through prior versions may be required. The Thales HSM documentation prescribes the correct upgrade path. As of this writing, the path to 7.3.1 is through 7.3.0. In other words, update to version 7.3.0 before updating to version 7.3.1.

For security best practice, your HSMs should run in FIPS mode. This allows your HSM to create FIPS-compliant keys. To learn how check the current policy setting, check out hsm showpolicies. Enable non-FIPS algorithms should be Disallowed.

The brochure for Thales Luna HSMs can be found here.

Network connectivity between Key Protect and HSM (recommended) 

The best practice network configuration is to use 10Gb links for cryptographic traffic between Key Protect and your HSMs and a bond of 2Gb links for management and administration traffic. Key Protect requires TCP connectivity to HSM on port 1792 for NTLS protocol. To check the connectivity, issue a netcat command on the worker nodes which would be assigned to Key Protect:

nc -vz <HSM-ipaddr> 1792

Where HSM-ipaddr is the IP address of your HSM.

Bonding provides standby fault tolerance reliability, but does not provide load balancing.

Partitions and partition types

If you have new or factory-reset HSMs, you must create an application partition to work with the Key Protect service. Follow the instructions in your HSM provider to create a partition, keeping in mind that your partition label and partition crypto officer password must be the same for the partition in both HSMs that will be connected to Key Protect. This is because the partition crypto officer password is consumed by Key Protect as part of the PKCS#11 session API login process.

The Thales SafeNet Luna Network HSM uses two types of partitions:

  • Administrative partitions: This is where HSM-wide policies are set and changed, application partitions are created or destroyed, HSM firmware and capabilities are updated, and so on.
  • Application partition: This is where cryptographic operations are performed by user applications.   While it is only possible to have only one administrative partition in a given HSM, it is possible to have multiple application partitions to address multi-tenancy configurations. This is achieved by partitioning the key storage space into multiple application partitions, with the ability to set the size of each partition. A user of a tenant has no way to see the other application partitions. Each application partition is also encrypted using partition-specific encryption keys.

The A750 appliance supports by default the creation of up to five application partitions, and therefore the management of up to five different tenants. This can be increased for the A750 model up to 20 partitions by purchasing additional partition licenses.

Configuring your HSM to produce the keys Key Protect needs

For Key Protect to work with an HSM, several different keys must be created on the HSM and stored as persistent token objects in the partition memory. Each of these keys must be given a label, and these labels must be provided when deploying Key Protect on Satellite. These keys are:

Key type Key role
Master Key Encryption Key (MKEK) (256bit AES key) A root level encryption key for wrapping and unwrapping instance keys in Key Protect.
Signing key (SKEY) (256bitsAES key) Used for signing and verification of instance and user keys in Key Protect.
Import Key (IKEY) (192bit DES3 key) Used to encrypt and unwrap the user's key materials be imported into Key Protect.
Transit Key Encryption Keys (TKEKs) 10 pairs of RSA asymmetric key pairs, which are used to securely Bring Your Own Keys (BYOK) into Key Protect.

The specific parameters that must be set to produce the correct keys can be acquired by opening an IBM Cloud service ticket indicating your desire to purchase Key Protect on Satellite. A Key Protect representative will contact you and initiate the process for you to acquire the necessary configuration information.

Many different tools can be used to create these keys. Consult with Thales technical support to find a secure way to create these keys based on your organization's security policy and compliance requirements.

Gather the information needed to connect the HSM with the Key Protect console

In order to deploy Key Protect, you must provide the information to connect to the HSM and to perform the kinds of privileged actions on the HSM that are necessary for Key Protect to function as part of your interactions with your service representative.

You must provide this information for both HSMs.

  • HSM IP address: The IP address of your HSM. This is needed in order to connect to the worker nodes that you assigned to Key Protect.
  • HSM server certificate: The NTLS communications used by the Thales HSM requires certificate exchanges between the HSM and Key Protect. You must create a TLS certificate in your HSM and provide the certificate Key Protect will use to verify communications from the HSM.
  • Partition label: The name of the partition that you created for Key Protect to use.
  • Partition crypto officer password: The credential Key Protect needs to login to the relevant partition on the HSM to perform key operations.
  • Master key label: Key Protect uses a Master Key Encryption Key in your partition. A label or name is assigned to this key and is used by Key Protect in PKCS#11 API to refer to the master key.
  • Signing key label: A label or name for a key in a partition, which is used for data authentication such as data signing and verification.
  • Import key label: Key Protect supports importing Bring Your Own Key (BYOK) by a DES3 encryption Key. A label or name is assigned to this key.
  • Secure import key label prefix (TKEK): Key Protect supports a secure mechanism to Bring Your Own Key (BYOK) into an HSM. The prefix used by the HSM for these keys must be known to Key Protect.
  • Activity Tracker ingestion key: To receive audit logs, you must create an IBM Cloud Activity Tracker instance and an ingestion key.

There are two additional credentials you must share before your service can be deployed, the HSM client cert and the HSM client key. These credentials enable NTLS communications used by the Thales HSM for exchanges between the HSM and Key Protect running on your worker node. You must create and register with the HSM a TLS certificate for the worker node (client) that will connect to the HSM and provide the client certificate and key that Key Protect uses to communicate with the HSM. The exact instructions to share these credentials are communicated as part of your conversations with your service representative.

Make a note of these values for both HSMs before attempting to deploy Key Protect.