Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

back

CipherTrust Manager Administration

Hardware Security Module

search

Please Note:

Hardware Security Module

A Hardware Security Module (HSM) is a physical device that provides more secure management of sensitive data, such as keys, inside CipherTrust Manager.

CipherTrust Manager internally uses a chain of key encryption keys (KEKs) to securely store and protect sensitive data such as user keys. When an HSM is used, the CipherTrust Manager generates and uses a set of keys on the HSM partition that protect the KEKs chain and become the root of trust. If multiple CipherTrust Manager instances are configured to use the same HSM partition they end up using shared 'root of trust' keys.

Configuring an HSM as the root-of-trust can be easily done using the GUI. This can also be done using the API or the CLI toolkit ksctl, as shown below. Using the cloud-init method is not recommended because it exposes sensitive information, such as the partition password, that can be viewed by anyone with access to the associated AWS console.

HSM setup might fail if time of the system is out of sync. It is recommended to set up time sync using NTP before continuing.

With the CipherTrust Manager API or CLI toolkit ksctl, it is possible to:

  • Setup HSMs

  • Get and List detailed information on existing HSMs

  • Add HSMs

  • Delete HSMs

Refer to the CipherTrust Manager API and CLI online documentation for more information.

Supported HSMs

The CipherTrust Manager supports the following HSMs:

  • Luna Network HSM (version 5, 6 and 7). See Luna Network HSM supported versions for more details.

  • TCT Luna T-Series Network HSM

  • TCT Luna PCIe HSM

  • Luna PCIe HSM

  • AWS CloudHSM (Cavium)

  • Thales Data Protection On Demand (DPoD) HSM On Demand Service

  • IBM Hyper Protect Cloud Services (HPCS)

  • Azure Dedicated HSM with a Virtual CipherTrust Manager which is also hosted on Microsoft Azure. This setup requires a specific deployment architecture.

Hybrid HSM

Since release 1.3.0, any CipherTrust Manager can be clustered with another CipherTrust Manager, regardless of the HSM partition it is using, or even if it is not using an HSM partition at all. This is different from prior releases that required all CipherTrust Manager's in a cluster to be connected to the same HSM partition. When cluster nodes have different HSMs, it is called a "Hybrid HSM" configuration. When cluster nodes share the same HSM partition, it is called a "Shared HSM" configuration. There are several implications to a "Hybrid HSM" configuration that should be taken into consideration when deploying a cluster.

  1. System Security: A system is only as secure as its weakest link. In a Hybrid HSM configuration, a CipherTrust Manager instance that is rooted in an HSM can be clustered with an instance that is not - this reduces the overall security of the system. The most secure configuration is to have all CipherTrust Manager instances use an HSM.

  2. Cluster Join Security: When a system is joined to a cluster, it must receive certain keys that allow it to join the cluster. A shared HSM partition can protect these keys from ever being exposed. In this scenario, the join operation should use the ksctl utility's --shared-hsm-partition flag for the best security.

  3. Backup Security: When a backup is created, there is a ksctl option called –-tied-to-hsm that can tie the backup to the HSM of the instance. This is the most secure backup, but also limits it to being restored on a system with access to that specific HSM partition. By default, a backup is not tied to a specific HSM partition and can be restored to any compatible CipherTrust Manager system.

Setting up an HSM

Creating the first HSM requires that you supply the hsm type and connection information (connInfo).

The general ksctl hsm setup command is:

$ ksctl hsm setup <hsm type> <config parameters>

The valid options for hsm type are:

  • "luna" for SafeNet Luna HSM,

  • "lunapci" for the embedded Luna PCIe HSM and TCT Luna PCIe HSM in CipherTrust Manager k570 models,

  • "lunatct" for TCT Luna T-Series Network HSM,

  • "aws" for AWS CloudHSM,

  • "dpod" for DPoD HSM on Demand Service

  • "ibm-hpcs" for IBM Hyper Protect Cloud Services (HPCS)

The configuration info (config parameter) depends on the hsm type and is described below. You must set up the HSM to allow CipherTrust Manager to connect as a client, including creating necessary passwords, certificates, and string values. For more detailed information on creating these HSM objects, refer to HSM product documentation.

A reset is performed after adding the HSM, with a delay in seconds (default: 5) specified before the reset is performed.

Be aware that performing a Reset is destructive; it deletes all information in the system and so must be used with great care. You must backup all information you wish to retain.

Luna Network HSM and TCT Luna T-Series Network HSM (hsm type: luna, lunatct)

At least one of the following TLS ciphers must be enabled on the Luna Network HSM to allow communication with CipherTrust Manager:
AES256-SHA
AES256-SHA256
AES256-GCM-SHA384
If you disable all of these TLS ciphers, CipherTrust Manager cannot add the Luna Network HSM as a root of trust, and receives a no shared ciphers error. By default, these TLS ciphers are enabled.

For the Luna Network HSM or TCT Luna T-Series Network HSM, the required parameters for initial configuration are:

  • - hsm-host: IP or hostname of the HSM

  • - partition-name: The name of the HSM partition to use

  • - partition-password: The password of the initial partition to use. For Luna 7 and most Luna 6, this is the Crypto Officer role password or challenge secret. For Luna 5, TCT Luna T-Series Network HSM, and some Luna 6, this is the partition password or challenge secret. This password will also be used if more servers and high-availability (HA) mode is used, in which case all HSM must have the same password.

  • - serial: Serial number of the partition to use

  • - server-cert-file: File containing server certificate in PEM format

  • - client-cert-file: File containing client certificate in PEM format

  • - client-cert-key-file: File containing client private key in PEM format

  • - delay: Delay in seconds before reset, defaults to 5 seconds

  • - reset: Reset instance as part of operation

The Luna Network HSM Documentation provides detailed information to configure values for hsm-host, partition-name, partition-password, serial, server-cert-file, client-cert-file, and client-cert-key-file.

Following is a full example for a SafeNet Luna Network HSM setup command:

$ ksctl hsm setup luna --reset --partition-name “partition name” --partition-password “sOmeP@ssword” -–hsm-host 192.168.0.1 –-serial 1234 -–server-cert-file server_cert.pem -–client-cert-file client_cert.pem –-client-cert-key-file client_cert_key.pem

Luna Network HSM Supported Versions

We support Luna firmware versions 5.x, 6.x, and 7.x.

We have tested specific combinations of Luna 7.x firmware and Luna 7.x software. Luna firmware versions 7.0.1 and 7.3.3 are validated with Federal Information Processing Standard (FIPS) level 140-2.

  • CipherTrust Manager k570 and Virtual CipherTrust Manager have been tested with following the Luna Network HSM versions:

    Appliance SoftwareHSM firmwareFIPS validated
    7.27.0.1yes
    7.27.3.3yes
    7.77.0.1yes
    7.77.3.3yes
  • CipherTrust Manager k470 has been tested with the following Luna Network HSM versions:

    Appliance SoftwareHSM firmwareFIPS validated
    7.27.2.0no
    7.27.0.3yes
    7.37.3.3yes
    7.47.4.0no
    7.47.3.3yes
    7.7.07.7.0no
    7.7.07.3.3yes

Embedded Luna PCIe HSM or TCT Luna PCIe HSM (hsm type: lunapci)

While the HSM type for both the Luna PCIe HSM or TCT Luna PCIe HSM is the same, the value required for the partition-name parameter is different. The Thales CipherTrust Manager k570 contains a Luna PCIe HSM, and the Trusted Cyber Technologies CipherTrust Manager k570 contains a TCT Luna PCIe HSM.

For the embedded Luna PCIe HSM in CipherTrust Manager k570 models, the required parameters for initial configuration are:

  • - partition-name: The name of the HSM partition to use. For TCT Luna PCIe HSM, this is the HSM label.

  • - partition-password: The password of the initial partition to use. For PED-authenticated HSMs, this is the challenge password.

  • - delay: Delay in seconds before reset, defaults to 5 seconds

  • - reset: Reset instance as part of operation

Following is a full example for a Luna PCIe HSM setup command:

$ ksctl hsm setup lunapci --reset --partition-name “partition name” --partition-password “sOmeP@ssword”

AWS CloudHSM (Cavium) (hsm type: aws)

Prerequisite - Prepare an instance of CloudHSM in AWS:

  • Prior to configuring CipherTrust Manager instance to use AWS CloudHSM service, an instance of CloudHSM must be prepared in AWS. Refer to AWS CloudHSM documentation to create, initialize and activate a CloudHSM cluster. This step involves running a separate AWS client instance to connect and setup HSM users as well as sign the cluster CSR of your cloudhsm cluster instance. Upon completion of this step you will have a cloudhsm cluster in "Active" state. See: https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html

  • Create a new cryptouser on your new cloudhsm instance. Similar to the cluster activation step when you reset the CO password, use the cloudhsm_mgmt_util utility on the AWS client instance to create a new user with cryptouser role (CU). CipherTrust Manager will communicate to the HSM instance on behalf of this CU user you setup.

For AWS CloudHSM (Cavium), the required parameters for initial configuration are:

  • - partition-name: (Optional) The name of the HSM partition to use for CloudHSM. Defaults to "cavium"

  • - cryptouser-password: Specify the credentials of a cryptouser in the form of "username:password"

  • - hsm-host: IP Address or host name of cloudhsm cluster

  • - server-cert-file: This is the CA public certificate that was used to sign the CloudHSM Cluster CSR during the cluster initialization. Restated, it is the certificate that signed the Cluster certificate. Refer to: https://docs.aws.amazon.com/cloudhsm/latest/userguide/initialize-cluster.html

  • - delay: Delay in seconds before reset, defaults to 5 seconds

  • - reset: Reset instance as part of operation

Following is a full example of an AWS CloudHSM setup command:

$ ksctl hsm setup aws-cloud-hsm --reset --cryptouser_password “sOmeP@ssword” -–hsm-host 192.168.0.1 -–server-cert-file server_cert.pem

Thales Data Protection On Demand (DPoD) HSM on Demand service (hsm type: dpod)

The required parameters for DPoD's HSM on Demand service depend on when you downloaded your service client. This is because clients downloaded after September 17 2020 use JWT based authentication. The newer, JWT-authenticated client displays lunacm (64-bit) v10.2.0 or higher on launching the lunacm utility. The older client displays lunacm (64-bit) v10.1.0 or lower on launching lunacm.

For JWT authenticated clients, you must provide the AuthTokenConfigURI, AuthTokenClientId, and the AuthTokenClientSecret values from the service client package's Chrystoki.conf file. For older clients, you must provide the CVAppSpecificData value from Chrystoki.conf.

Prerequisites:

  • You have installed a service client and provisioned the HSM on Demand Service.

  • The connection information (partition-name and co-password) is obtained while provisioning your HSM on Demand service.

  • The configuration information is obtained from the HSM client package. This includes certificate files, authentication values or CVAppSpecificData in the Chrystoki.conf file, and the cv-partition-data value from crystoki-template.ini or Chrystoki.conf.

    For the JWT-authenticated client, the cv-partition-data value can be obtained from crystoki-template.ini. For the older client this value is included in Chrystoki.conf as well.

For DPoD, the required parameters for initial configuration are:

Newer JWT-authenticated client

  • - partition-name: The name of the partition configured during partition initialization

  • - co-password: The password of the Crypto Officer

  • - server-cert-file: Path to server-certificate.pem file

  • - partition-cert-file: Path to partition-certificate.pem file

  • - partition-ca-cert-file: Path to partition-ca-certificate.pem file

  • - cv-partition-data: PartitionData00 value from crystoki-template.ini

  • - auth_token_config_uri: AuthTokenConfigURI value from Chrystoki.conf

  • - auth-token-client-id: AuthTokenClientId value from Chrystoki.conf

  • - auth-token-client-secret: AuthTokenClientSecret value from Chrystoki.conf

  • - delay: Delay in seconds before reset, defaults to 5 seconds

  • - reset: Reset instance as part of operation

The following is a full example for a DPoD HSM on Demand setup command for the JWT authenticated client:

$ ksctl hsm setup dpod --reset --partition-name “partition name” --co-password “sOmeP@ssword” -–server-cert-file "server-certificate.pem" -–partition-cert-file "partition-certificate.pem" –-partition-ca-cert-file "partition-ca-certificate.pem" --cv-partition-data "crystoki-template-PartitionData00" --auth-token-config-uri "https://111111.uaa.system.snakefly.dpsas.io/.well-known/openid-configuration" --auth-token-client-id "1111111-1111-1111-1111-111111111111" --auth-token-client-secret "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Older client

  • - partition-name: The name of the partition configured during partition initialization

  • - co-password: The password of the Crypto Officer

  • - server-cert-file: Path to server-certificate.pem file

  • - partition-cert-file: Path to partition-certificate.pem file

  • - partition-ca-cert-file: Path to partition-ca-certificate.pem file

  • - cv-app-specific-data: CVAppSpecificData value from Chrystoki.conf

  • - cv-partition-data: PartitionData00 value from Chrystoki.conf

  • - delay: Delay in seconds before reset, defaults to 5 seconds

  • - reset: Reset instance as part of operation

The following is a full example for a DPoD HSM on Demand setup command for the legacy client:

$ ksctl hsm setup dpod --reset --partition-name “partition name” --co-password “sOmeP@ssword” -–server-cert-file "server-certificate.pem" -–partition-cert-file "partition-certificate.pem" –-partition-ca-cert-file "partition-ca-certificate.pem" --cv-partition-data "Chrystoki-conf-PartitionData00" -–cv-app-specific-data “Chrystoki-conf-CVAppSpecificData”

IBM Cloud Hyper Protect Crypto Services

CipherTrust Manager is able to use IBM Cloud Hyper Protect Crypto Services (HPCS) as a root of trust through IBM Cloud HPCS's PKCS#11 API. To establish a connection between CipherTrust Manager and an HPCS PKCS#11 endpoint, you must perform the following configuration on IBM:

  1. Create PKCS#11 user roles. Following IBM best practices, CipherTrust Manager requires a Normal User API Key with Key operator privileges.

  2. Download the IBM PKCS#11 module and configure it. As part of this configuration, you create a private keystore, also called a tokenspace for CipherTrust Manager to access. Note the following values, as they need to be provided to CipherTrust Manager to access the HPCS instance:

    • instance_id

    • EP11_endpoint_URL CipherTrust Manager requires the public URL.

    • EP11_endpoint_port_number

    • private_key_store_spaceid

  3. Initialize the private keystore with the Security Officer(SO) user. The SO performs a C_InitToken operation. For example, to do this using the opensc pks11-tool:

    sudo apt install opensc
    pkcs11-tool --module=/usr/local/lib/pkcs11-grep11-amd64.so --init-token --label <you-can-choose> --so-pin=<your-so-api-key>
    

On CipherTrust Manager, you must provide the following configuration parameters:

  • host: The hostname part of the public URL for the Enterprise PKCS#11 endpoint, called EP11_endpoint_URL in HPCS.

  • port: The port for the Enterprise PKCS#11 endpoint, called EP11_endpoint_port_number in HPCS.

  • instance-id: The id for the HPCS instance. There multiple ways to retrieve this value in IBM Cloud.

  • api-key: The api key for the Normal User with Key operator privileges.

  • token-space-id: The 128-bit Universally Unique IDentifier (UUID) of the private key store accessible by the Normal User. This value is called private_key_store_spaceid in IBM HPCS.

The following is a full example for an IBM HPCS setup command:

$ ksctl hsm setup hsm setup ibm-hpcs --reset -m <EP11_endpoint_public_host> --port <EP11_endpoint_port> --instance-id <instance_id> --api-key <normal_user_api_key> --token-space-id <private_key_store_spaceid>

Getting and Listing HSMs

Get and List return detail information about the instance(s) added previously, Get returns a single instance and List returns an array of data.

Following is a full example of a HSM Servers List command:

$ ksctl hsm servers list

{
  "total": 2,
  "resources": [
    {
      "id": "2f81163b-f53d-45c1-b151-9bc333ce3a04",
      "type": "luna",
      "config": {
        "host": "192.168.0.1",
        "serial": "1234",
        "server-cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
      }
    },
    {
      "id": "be942b82-b00e-4f73-9081-28186e1580e6",
      "type": "luna",
      "config": {
        "host": "192.168.0.2",
        "serial": "4321",
        "server-cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
      }
    }
  ]
}

Adding an HSM

This operation is only supported by the SafeNet Luna Network HSM and Luna T-Series HSM.

Adding subsequent HSMs to a CipherTrust Manager inserts them into the HA group. The first hsm servers add command that you do automatically creates an HA group. Adding an HSM only requires that you supply the configuration information.

To add extra AWS CloudHSM instances to the existing HSM cluster, no change is required on CipherTrust Manager; consult AWS CloudHSM documentation.

The configuration information (config) is a JSON blob; it has the following keys:

  • host

  • serial

  • server-cert

  • forceClear (optional)

    When set to "true", forcefully clears all existing data on the partition of the joining node before adding it to the HA group. Make sure the existing objects are not used elsewhere. They cannot be recovered after the deletion. Use with caution.

  • forceCopy (optional)

    When set to "true", all existing objects on the joining partition are retained and propagated within the HA group. This option can be useful if the joining partition is shared among CipherTrust Manager instances that use the partition only as a member of a current HA group. This option can also be useful if the joining partition is shared among different applications other than CipherTrust Manager, and the goal is to retain the existing security objects.

    Do not use the forceCopy option if the joining partition was previously used as root of trust for other CipherTrust Manager instance(s) and that it was not part of the current HSM HA group. Using this option in such cases can break the existing CipherTrust Managers that use the HA group servers. Use with caution.

Following is a full command example for adding a SafeNet Luna Network HSM:

$ ksctl hsm servers add --config '{ "host": "192.168.0.2", "serial": "4321", "server-cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }'

If the joining HSM partition contains data, the operation will fail unless forceClear or forceCopy flags are specified. The following example command shows how to forcefully add a partition by first wiping all its data:

$ ksctl hsm servers add --config '{ "host": "192.168.0.2", "serial": "4321", "forceClear": "true", "server-cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }'

DO NOT use forceClear and forceCopy flags by default when adding a new HSM server. If the command fails indicating the joining node contains objects:
1. Manually log on to the partition.
2. Carefully investigate the use of existing objects.
3. Repeat the command with forceClear or forceCopy flag.

Deleting an HSM

Delete will remove the record for the "--id" provided, with optional parameters for reset and delay. Just as in the Setup function, deleting the last HSM requires a reset of the CipherTrust Manager. After the reset operation, newly encrypted data is longer rooted to an HSM.

Just as in the Setup function (see Setting up an HSM after deleting the last HSM, a reset of the CipherTrust Manager must be performed before the HSM is reused.

Performing a Reset is destructive; it deletes all information in the system and so must be used with great care. You must backup all information you wish to retain.

Following is a full example for the delete command:

$ ksctl hsm servers delete --id ce6da730-c266-44f8-a0f6-97e49c7596eb --reset