Root of Trust Hardware Security Module

Note

This feature is not included in Community Edition and requires a valid Virtual CipherTrust Manager license. To activate your instance with a trial evaluation, or a term or perpetual license, see Licensing.

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 setup, the CipherTrust Manager uses a set of keys on the HSM partition that protect the KEKs chain and become the root of trust. In most cases, setting up an HSM generates new root of trust keys. If there are keys already present on the HSM with the correct attributes, those keys become root-of-trust keys.

Warning

As a security best practice, we strongly recommend dedicating CipherTrust Manager root of trust keys to that purpose, and not granting access to these keys to any other application or for any other purpose.

• Luna Network HSM: Do not use a Luna HSM partition containing the CipherTrust Manager root of trust key with CipherTrust Cloud Key Management (CCKM) or HSM-anchored domains. Do not create a connection to a Luna HSM root of trust partition with Connection Manager.

• Google Cloud HSM: Do not manage the Google key ring containing the root of trust key with CCKM. Do not create a Google connection on Connection Manager with a service account key file that grants permission to root of trust keys.

If multiple CipherTrust Manager instances are configured to use the same HSM partition they end up using shared 'root of trust' keys.

After setting up an HSM to allow CipherTrust Manager to connect as a client, you can configure an HSM as the root-of-trust using the CipherTrust Manager GUI. This can also be done using the API or the CLI toolkit ksctl, as shown below. It is assumed that you have added a CipherTrust Manager user and URL to the ksctl configuration file. Root-of-Trust HSM configuration requires you to login to the root domain as admin or another Application Administrator.

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.

Note

Using the cloud-init method to set up a root-of-trust is not recommended because it exposes sensitive information, such as the partition password, that can be viewed by anyone with access to the associated cloud console.

Note

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 7. See Luna Network HSM supported versions and configurations 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) Luna Cloud HSM Service

• IBM Hyper Protect Cloud Services (HPCS)

• TCT k160 High Assurance HSM

• TCT k160 Standard HSM

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

• nShield Connect HSM

  The supported firmware version is 13.4.5.

• ProtectServer 3 PCIe HSM (Network Mode Only)

  The supported firmware version is 7.01.00 and supported software version is 7.2.0.

• Google Cloud HSM

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.

Supplying Existing Root of Trust Keys

By default, setting up an HSM automatically generates new root of trust keys. You can optionally create these keys directly on the HSM beforesetting up the HSM with CipherTrust Manager. When the HSM is later setup with CipherTrust Manager, the keys are automatically recognized and used to protect the KEK chain.

Caution

Do not manually create root of trust keys directly on the HSM after the HSM is set up on CipherTrust Manager. Instead, use the CipherTrust Manager functions to rotate root of trust key to generate new root-of-trust keys.

Manually creating root of trust keys directly on the HSM after CipherTrust Manager setup can result in the CipherTrust Manager application becoming unavailable after reboot, requiring customer support to recover.

You can supply existing root of trust key for any generally supported HSM type. For the embedded Luna PCIe HSM in the Thales CipherTrust Manager k570 appliance, existing keys can come from restoring from a Luna Backup HSM.

Required Root of Trust Key Configuration

There are two keys required, an encryption key and an HMAC key for integrity validation.

Caution

In addition to the required characteristics, we strongly recommend to generate the keys with the non-exportable flag to ensure they never leave the boundary of the HSM.

The encryption key must have the following characteristics:

• AES-256 key algorithm.

• Permissions to encrypt and decrypt.

• The key name must be DARKSTAR-encryption-key or <some_other_prefix>-encryption-key.

  

  Note

  An encryption key named DARKSTAR-encryption-key immediately becomes the active root of trust key for CipherTrust Manager on HSM setup. An encryption key named with a different prefix must be rotated to become active.

The HMAC key must have the following characteristics:

• HMAC-256 key algorithm.

• Permissions to sign and verify.

• The key name must be DARKSTAR-mac-key or <some_other_prefix>-mac-key.

  

  Note

  The HMAC key's prefix must match the encryption key's prefix.

Example Root of Trust Key PKCS#11 Configuration

This is an example of the recommended PKCS#11 attributes and values for the encryption key:

This is an example of the recommended PCKS#11 attributes and values for the HMAC key:

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 Luna Network 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 Luna Cloud HSM Service,

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

• "k160" for TCT k160 HSM, both the High Assurance and Standard models

• "nshield" for nShield Connect HSM

• "protectserver" for ProtectServer 3 PCIe HSM

• "gcp-cloud-hsm" for Google Cloud HSM

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.

Note

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

Caution

Be aware that performing a reset is destructive; it deletes all data in the CipherTrust Manager and so must be used with great care. You must backup all information you wish to retain.
This backup is particularly important if you created users and keys before setting up an HSM. For example, you might create users and keys without an HSM as part of the Community Edition before applying a Virtual CipherTrust Manager license or starting a trial evaluation. If you wish to retain those objects, you must back them up before setting up an HSM root of trust.

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

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 TCT Luna T-Series Network HSM, 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

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

• - reset: Reset the CipherTrust Manager instance as part of operation

As well, you are required to provide some certificates and other parameters to establish trust with the connection. The parameters depend on whether you are setting up a Network Trust Link (NTLS) or a Secure Trusted Channel (STC) between CipherTrust Manager and the HSM partition.

Note

You provide certificates generated on an external Luna HSM Client. To ensure compatibility with this CipherTrust Manager version, we strongly recommend generating certificates on Luna HSM Client version 10.7 only.

Parameters for Luna Network HSM NTLS Connection or TCT Luna T-Series Network HSM Connection

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

  

  Note

  For Luna Network HSM, you can supply a server certificate signed by a trusted certificate authority (CA) external to the Luna Network HSM. For this type of server certificate, append all the certificates in the signing chain to the certificate file.

  Externally signed server certificates are not supported for TCT Luna T-Series Network HSMs.

• - client-cert-file: File containing client certificate in PEM format. This is the client certificate that was used to register the client on the Luna Network HSM with the lunash:> client register command.

  

  Note

  Both self-signed and externally signed certificates are accepted. In either case, you need only provide the client certificate and client private key to CipherTrust Manager. For externally signed client certificates, the CA certificates must have been provided to the Luna Network HSM with the lunash:> client addCA externalCA command.

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

Parameters for Luna Network STC Connection

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

  

  Note

  You must provide a self-signed certificate.

• -partition-identity-file: File containing the partition identity. This file is obtained as part of a sequence on the Luna Network HSM to prepare the STC connection.

Note

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 Luna Network HSM setup command using the NTLS connection:

$ 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 and Configurations

We have tested specific combinations of Luna 7.x firmware and Luna 7.x software. Consult Luna Network HSM Customer Release Notes for the current FIPS certified Luna firmware versions.

CipherTrust Manager is not compatible with Functionality Module (FM) configuration on the Luna Network HSM.

• CipherTrust Manager k570 has been tested with following the Luna Network HSM versions:

  Appliance Software	HSM firmware
  7.2	7.0.1
  7.2	7.3.3
  7.7	7.0.1
  7.7	7.3.3
  7.8.4	7.8.4

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

  Appliance Software	HSM firmware
  7.2	7.2.0
  7.2	7.0.3
  7.3	7.3.3
  7.4	7.4.0
  7.4	7.3.3
  7.7.0	7.7.0
  7.7.0	7.3.3
  7.7.1	7.7.1
  7.8.4	7.8.4

Note

The above compatibilities apply for connections using the default Network Trust Link (NTLS) between the CipherTrust Manager and the Luna Network HSM. Secure Trusted Channel (STC) connections are only supported for HSM firmware version 7.7.0. or higher.

Caution

Make sure to upgrade to CipherTrust Manager 2.17 or higher before attempting to root of trust configuration with a Luna Network HSM running 7.8.4 firmware. 7.8.4 is incompatible with lower CipherTrust Manager versions. The root of trust configuration is lost and the CipherTrust Manager becomes unavailable if you attempt to configure Luna Network HSM 7.8.4 with incompatible CipherTrust Manager software.

Using Externally Signed Certificates for Luna Network HSM NTLS Connection

Note

Externally signed certificates are not supported for TCT Luna T-Series Network HSMs or for the STC connection type.

You can choose to provide both server and client certificates which are signed by a trusted CA, external to the Luna Network HSM and CipherTrust Manager, instead of self-signed certificates.

• Server certificate: Provide the full certificate chain in a file with the server-cert-file parameter when setting up the first Luna Network HSM with CipherTrust Manager. You cannot provide CA certificates when adding an additional HSM.

• Client certificate: As part of the client registration on the Luna Network HSM, the CA certificates must have been provided to the Luna Network HSM with the lunash:> client addCA externalCA command. You do not provide the CA certificates to CipherTrust Manager, only the client certificate itself and the client private key.

Set up a Secure Trusted Channel Connection

1. Create the STC connection to the Luna Network HSM. As part of that process, you create a Luna partition with the LunaSH CLI, and initialize a Luna partition for STC with a Luna Client. Be sure to retain the Partition SO password.

   

   Note

   The partition size must be at least 1536 bytes to accommodate two client registrations and the CipherTrust Manager root keys. If you plan to rotate the root keys, make the partition large enough to accommodate 512 more bytes storage per rotation.

   You can alternatively convert an existing NTLS partition to use STC.

2. On CipherTrust Manager, obtain the client identity file needed to register CipherTrust Manager as an additional client.

   ksctl hsm clients stcidentity download [--outputfile <download-filename>]

   Copy

   Alternatively, use GET /v1/system/hsm/clients/stcidentity/download/in the REST API.

3. Use the client identity file to connect CipherTrust Manager to the STC partition as an additional client. More details are available in Luna documentation about the Partition SO's actions to allow an additional client access to the STC partition.

   1. Login to the initial client as the Partition SO.

   2. Supply the client identity file as part of the LunaCM command stcconfig clientregister -label <client_label> -file <path/client_ID_file>.

      

      Note

      Transfer the downloaded client identity file through SCP or other means. Do not copy and paste its contents to another file, and use this second file to execute stcconfig clientregister -label <client_label> -file <path/client_ID_file>. Client registration fails in this case.

   3. Export the partition identity public key using the LunaCM command stcconfig partitionidexport.

   4. Obtain the HSM server certificate, located in <Lunaclient_install_directory>/cert/server/<hostname/IP>Cert.pem

4. On CipherTrust Manager, register the partition.

   ksctl hsm setup luna --reset --partition-name <partition-name> --partition-password <Crypto_Officer_role_password_or_challenge_secret> --hsm-host <HSM_host_IP> --serial <partition_serial_number> --server-cert-file <HSM_server_certificate> --partition-identity-file <partition_identity_filepath>

   Copy

   For example:

   $ 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 --partition-identity-file 1234.pid

   Copy

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

Note

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.

Caution

If you intend to restore master keys from a Backup HSM, restore the keys before performing root of trust configuration.

Configuring Luna PCIe HSM as the root of trust and then restoring master keys can result in the CipherTrust Manager application becoming unavailable after reboot, requiring customer support to recover.

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 CipherTrust Manager 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”

The ksadmin system administrator can upgrade firmware for Luna PCIe HSM to take advantage of performance and security fixes for the root of trust keys.

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.

• Be sure that the AWS CloudHSM is accessible to the CipherTrust Manager through the network. To achieve this for a Virtual CipherTrust Manager deployed on an AWS EC2 instance, attach the cluster security group to the EC2 instance as described in AWS documentation. Check the hardening guidelines for more deployments and details.

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. This 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 CipherTrust Manager 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) Luna Cloud HSM service (hsm type: dpod)

The CipherTrust Manager integration with Luna Cloud HSM service uses JWT-based authentication, which has been required for all clients to this service since December 31, 2021.

Note

The older authentication based on the CVAppSpecificData is no longer available on CipherTrust Manager.

You must provide the AuthTokenConfigURI, AuthTokenClientId, and the AuthTokenClientSecret values from the service client package's Chrystoki.conf file.

Prerequisites:

• You have installed a service client and provisioned the Luna Cloud HSM Service.

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

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

For DPoD, the required parameters for initial configuration are:

• --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 CipherTrust Manager instance as part of operation

The following is a full example for a DPoD Luna Cloud HSM setup command:

$ 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"

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>

   Copy

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>

TCT k160 HSM (hsm type: k160)

For the CipherTrust Manager TCT k160 High Assurance HSM and CipherTrust Manager TCT k160 Standard HSM models, the required parameters for initial configuration are:

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

• reset: Reset CipherTrust Manager instance as part of operation

You must also specify whether the model is High Assurance or Standard.

• ha: Specifies the High Assurance version of the k160 model.

• std: Specifies the Standard version of the k160 model.

Following is a full example for a k160 HA HSM setup command:

ksctl --configfile <k160>.yaml hsm setup k160 --reset --ha

Following is a full example for a k160 Standard HSM setup command:

ksctl --configfile <k160>.yaml hsm setup k160 --reset --std

Note

The process may take longer than the default 30 seconds timeout, so extending the timeout value in the yaml config file will help with the command response. Setting the “KSCTL_TIMEOUT:” value to 180 seconds is recommended.

Note

If you attempt to log in on the GUI, you will see various messages about services starting up and it will take over 10 minutes to complete the start-up process.

Once the CipherTrust Manager TCT k160 HSM is added, you can register additional Token HSMs.

nShield Connect HSM

Before setting up an nShield Connect HSM as a root of trust to CipherTrust Manager, you must perform the following configuration in nShield utilities, as described in nShield documentation:

1. On the nShield Connect HSM, add the CipherTrust Manager IP address as a client. Apply the following settings:

   • Set up an unprivileged connection, as is default

   • Enroll the client without secure authentication

2. Configure the Remote File System (RFS) to accept access by the CipherTrust Manager as a cooperating client.

   

   Note

   You do not need to install or use nShield client software on CipherTrust Manager.

3. Create a new Security World if it doesn't exist yet.

4. Copy or note down the values for the following nShield HSM attributes:

   • Electronic Serial Number (ESN)

   • HKNETI (Hash of KNETI key)

   • nShield HSM IP address

   • RFS IP address

   • nShield HSM port, if different than the default 9004 value.

   • RFS port, if different than the default 9004 value.

   If you want to use an existing softcard for CipherTrust Manager, copy or note down its name and pass phrase.

To set up an nShield Connect HSM as root of trust on the CipherTrust Manager web console:

1. Login to the root domain as admin.

2. Navigate to Admin Settings>Root of Trust.

3. Click Yes, configure an HSM.

4. Select nShield HSM and click Next.

5. Provide a Softcard Name and Softcard Password.

   You can either provide these values for an existing softcard in the Security World, or you can enter new values to create a new softcard in the Security World.

6. Provide values obtained from the nShield HSM:

   • ESN (Electronic Serial Number)

   • IP of nShield Connect

   • HKNETI

   • RFS Host, meaning the IP address.

   If the nShield port or RFS port are different than the default value of 9004, you must provide the port number(s) as well.

7. Click Next.

8. Confirm loss of key material and system restart to set up the nShield HSM.

ProtectServer 3 PCIe HSM

The following prerequisite configuration must have taken place on the ProtectServer HSM:

• Initial Configuration including creation and initialization of at least one user slot and token.

• A Certificate trust chain must be established for the ProtectServer HSM.

• Compatible security flags must be set for the HSM. CipherTrust Manager requires the following security flags:

  • Auth Protection

  • FIPS Algorithms only

  • Mode Locked

  • No Clear PINs

  • No Public Crypto

  • Tamper Before Upgrade

  You can set all these flags with the command ctconf -fualnct.

To obtain values needed to set up ProtectServer 3 PCIe HSM as a root of trust to CipherTrust Manager:

1. Install the ProtectToolkit-C 7 software, including the C SDK.

2. Import the ProtectServer server certificate to the client. The directory location of the ProtectServer Identity Cert (PIC) is displayed.

3. Copy the certificate from the directory, or note the file location, as you need to provide the server certificate file for CipherTrust Manager configuration.

4. Obtain the token serial number and User PIN values for the user slot, with the label listed as HSMToken. The User PIN was set at token initialization. The token serial number can be obtained with the following command:

   ctstat -s <user_slot_number>

   Copy

To set up a ProtectServer 3 PCIe HSM as a root of trust on CipherTrust Manager, the required parameters are:

• - hsm-host: The IP address or hostname of the server containing the ProtectServer PCIe HSM.

• - port: The port of the ProtectServer PCIe HSM

• - token-serial: The user token serial number

• - token-password: The user PIN for the token.

• - server-cert-file: Path to ProtectServer HSM server certificate file in PEM format.

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

• - reset: Reset CipherTrust Manager instance as part of operation

The following is a full example for a ProtectServer setup command:

$ ksctl hsm setup hsm setup protectserver --reset --hsm-host <protectserver_ip_address_or_hostname> --port <protectserver_port> --token-serial <token_serial_number> --token-password <user_pin> --server-cert-file <path_to_server_certificate_file>

Google Cloud HSM

CipherTrust Manager can use the Cloud HSM available in Google Cloud Platform (GCP) as a root of trust.

Note

You can only rotate the root of trust key on CipherTrust Manager. You cannot rotate the root of trust key on Google Cloud Platform, as CipherTrust Manager only recognizes the first version of a Google Cloud key.

Prerequisites

On Google Cloud Platform, you require the following Google Cloud objects:

• a service account

• a private key file for the service account. This file contains the service account private key in JSON format, along with other values associated with the service account. Consult Google Cloud documentation to generate this file.

• a key ring in a Google location that supports Google Cloud HSM.

The key ring and service account can be in the same or in separate projects.

The service account requires the following Identity and Access Management (IAM) permissions:

• cloudkms.keyRings.get for the location of the key ring.

• cloudkms.locations.generateRandomBytes for the location of the key ring.

• cloudkms.cryptoKeys.list for the key ring.

• cloudkms.cryptoKeyVersions.list for the key ring.

• cloudkms.cryptoKeyVersions.manageRawAesCbcKeys for the key ring.

• cloudkms.cryptoKeyVersions.useToDecrypt for the key ring.

• cloudkms.cryptoKeyVersions.useToEncrypt for the key ring.

• cloudkms.cryptoKeyVersions.useToSign for the key ring.

• cloudkms.cryptoKeyVersions.useToVerify for the key ring.

• cloudkms.cryptoKeys.create for the key ring.

• cloudkms.cryptoKeyVersions.destroy for the key ring.

Setup on CipherTrust Manager Web Console UI

1. Login to the root domain as admin.

2. Navigate to Admin Settings>Root of Trust.

3. Click Yes, configure an HSM.

4. Select Google Cloud HSM and click Next.

5. Provide the following required values:

   • Location: The Google Cloud location associated with the key ring. The location must support Cloud HSM.

   • Key Ring: The name of the key ring associated with the Google Cloud HSM.

6. Provide the private key file values associated with the service account. Consult Google Cloud documentation to generate this file. You can either upload the file itself or paste the file contents into the text field.

   • Select File Upload and click Upload Key File.

   or

   • Select Text and paste in the content of the private key file.

7. If your key ring is in a different project than your service account, specify the Project ID. By default, CipherTrust Manager uses the project ID associated with the service account and included in the service account key file.

8. Click Next.

9. Confirm loss of key material and system restart to set up the HSM.

Parameters for ksctl CLI setup

To setup a Google Cloud HSM in the CLI, the required parameters are:

• location: The Google Cloud location associated with the key ring. The location must support Cloud HSM.

• keyring: The name of the key ring associated with the Google Cloud HSM.

• service-account-key-file: A file containing the service account private key in JSON format, along with other values associated with the service account. Consult Google Cloud documentation to generate this file.

• reset: Reset CipherTrust Manager instance as part of operation

Optional parameters are:

• delay: Delay in seconds before reset. Defaults to 5 seconds

• project-id: ID of the Google Project which contains the key ring. Specify this value if your key ring is in a different project than your service account. Defaults to the project ID associated with the service account and included in the service account key file.

The following is a full example for a Google Cloud HSM setup command:

$ ksctl hsm setup hsm setup gcp-cloud-hsm --reset --location <key_ring_location> --keyring <key_ring_name> --service-account-key-file <path_to_service_account_key_file>

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

For supported HSMs, you can add additional HSMs of the same type as the initial HSM to provide redundancy for the root of trust keys.

This operation is only supported by the Luna Network HSM, Luna T-Series HSM, and nShield Connect HSM.

Note

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

Adding an Additional nShield Connect HSM

This operation is only available in ksctl and the REST API. nShield Connect HSMs must already share the same Security World and RFS before you add the HSM to CipherTrust Manager, so that the root of trust keys can successfully replicate between all the root of trust HSMs.

Adding an additional nShield Connect HSM requires that you supply the configuration information.

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

• host

• port

• serial, meaning the ESN

• hkneti

Adding an Additional Luna Network HSM partition or Luna T-Series HSM partition

Adding subsequent HSM partitions to a CipherTrust Manager inserts them into the HA group. The first hsm servers add command that you do automatically creates an HA group.

If you are adding multiple HSM partitions from the same Luna Network HSM, they must all use the same type of network channel, NTLS or STC. That means if your initial root-of-trust connection uses NTLS, you can only add partitions that use NTLS from the same HSM. Similarly, if your initial root-of-trust connection uses STC, you can only add partitions that use STC from the same HSM.

STC Prerequisites

More prerequisites are required to add a Luna Network HSM partition with an STC connection:

• You must obtain the CipherTrust Manager client identity file

  ksctl hsm clients stcidentity download [--outputfile <download-filename>]

  Copy

  Alternatively, use GET /v1/system/hsm/clients/stcidentity/download/in the REST API.

• As the Partition SO, supply the client identity file to the partition as part of the LunaCM command stcconfig clientregister -label <client_label> -file <path/client_ID_file>.

  

  Note

  Transfer the downloaded client identity file through SCP or other means. Do not copy and paste its contents to another file, and use this second file to execute stcconfig clientregister -label <client_label> -file <path/client_ID_file>. Client registration fails in this case.

• Obtain the partition identity file using the LunaCM command stcconfig partitionidexport.

More details are available in Luna documentation about the Partition SO's actions to allow an additional client access to the STC partition.

Parameters to Add a Luna HSM

Adding a Luna HSM requires that you supply the configuration information.

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

• host

• serial

• server-cert

  

  Note

  For Luna Network HSM, you can provide a server certificate signed by a trusted CA external to the Luna Network HSM. For CipherTrust Manager to accept an externally signed server certificate, you must have supplied the full certificate chain when you setup the first HSM for CipherTrust Manager. You cannot provide CA certificates when adding an additional HSM.

  Externally signed server certificates are not supported for TCT Luna T-Series Network HSMs.

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

• partition-identity-file

  For adding an additional STC connection only. See STC prerequisites for additional required steps to add an HSM partition with an STC connection.

Following is a full command example for adding a 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-----" }'

Warning

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.

Note

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.

Warning

Performing a CipherTrust Manager 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

Register an Additional Token HSM for TCT k160

The CipherTrust TCT k160 allows for additional Token HSMs to be initialized.

Keeping the first token inserted into the k160, insert another token into an open USB slot on the back of the k160 device and issue the following command:

ksctl –-configfile <k160>.yaml hsm tokens reg

Once the command completes, remove the additional token from the back of the k160.

Note

Removing the token from the front of the k160 will cause a system restart.

Rotating the Root of Trust Key

Application administrators logged into the root domain can rotate the active root of trust (RoT) key stored on the HSM. Periodic rotation is a best security practice. As well, rotation also allows your organization to recover in case the RoT key is compromised. You can also rotate the Master Key Encryption Key (MKEK) which is below the RoT key in the key hierarchy.

One RoT key can be active at a time, but CipherTrust Manager retains older RoT keys, which can be made active again. The CLI and API allow you to list all RoT keys, view details for a given RoT key, rotate the active RoT key, and delete a given RoT key.

System backups that are tied to an HSM use the HSM RoT key to encrypt the backup file. This means that to decrypt and restore a backup that has been tied to an HSM, the CipherTrust Manager must have the encrypting RoT key set to active.

View Root of Trust Keys

Use ksctl rot-keys list to return a list of all RoT keys, including IDs, creation dates, and a boolean is_active_key indicating which key is the active key.

Use ksctl rot-keys get -id <key_id> to return this information about a particular key.

Rotate Active Root of Trust Key

Use ksctl rot-keys rotate to rotate the active key to a new or existing key. Pass in an --id flag for an existing RoT key to make that key active. Omit the --id flag to create a new RoT key with a randomly generated name. If a key with the specified id does not exist, CipherTrust Manager creates a new RoT key.

If you are creating a cluster sharing the same HSM partition, we recommend setting the RoT key to be the same on every node before joining nodes together. This way, CipherTrust Manager secrets and master keys can be protected by an HSM-secured RoT key during the join process, when these objects are transferred between nodes for the first time.

Note

For the k160 model, rotating the RoT key is not supported.

Delete a Root of Trust Key

Use ksctl rot-keys delete --id <key_id> to delete a RoT key. If there is only one RoT key, you must also supply a --force flag to force the operation. You can also use the --force flag to clean up any leftover RoT keys in the HSM which are not visible with ksctl rot-keys list.

Warning

Deleting the last root of trust key makes the CipherTrust Manager unusable, and any keys on the device irrecoverable. Deleting the last RoT key is only for the purpose of decommissioning a CipherTrust Manager and freeing storage space on the HSM.

Warning

Do not delete an RoT key if there are any system backups associated with the RoT key. If a system backup was taken with the --tied-to-hsm option, the backup file was encrypted with the active HSM RoT key. If you delete the RoT key which encrypted the backup file, the backup becomes permanently unusable, and cannot be decrypted and restored.

Upgrade Luna PCIe HSM Firmware for CipherTrust Manager k570 Appliances

You can update firmware for the Luna PCIe HSM embedded in CipherTrust Manager k570 models. The update steps vary for Thales CipherTrust Manager k570 and Trusted Cyber Technologies(TCT) CipherTrust Manager k570 appliances.

Update PCIe Firmware for Thales CipherTrust Manager k570

We have tested HSM firmware upgrade to 7.8.4, which is the FIPS-validated firmware recommended by Thales.

Caution

Make sure to upgrade to CipherTrust Manager 2.17 or higher before upgrading the PCIe HSM to 7.8.4. 7.8.4 firmware is incompatible with lower CipherTrust Manager versions. The root of trust configuration is lost and the CipherTrust Manager becomes unavailable if you upgrade the PCIe HSM to 7.8.4 with incompatible CipherTrust Manager software.

The supported starting versions are:

• 7.0.1 - The version installed on CipherTrust Manager PCIe HSM at the factory.

• 7.7.0 - A previously recommended upgrade version.

  

  Caution

  Due to an Out of Memory error, we no longer recommend upgrading any CipherTrust Manager device's PCIe HSM to the 7.7.0 HSM firmware version.

• 7.7.1-20 - A previously recommended upgrade version.

Note

If you do not know the current version of the embedded PCIe HSM, as the System Administrator (ksadmin) SSH in to the appliance (or connect via serial port using your password) and execute "/usr/safenet/lunaclient/bin/lunacm" utility. A Firmware Version is listed.

Updating the firmware ensures that the HSM has more up-to-date performance and security fixes.

For more detailed information on firmware upgrade, consult Luna PCIe Documentation.

To update the firmware:

1. If your appliance is PED-authenticated, ensure you have compatible PED firmware before upgrade.

   

   Caution

   Luna PED firmware versions are backwards-compatible with older Luna HSM firmware, but a Luna HSM with firmware 7.7.0 or newer will refuse connection to a Luna PED with older firmware, with the error (LUNA_RET_PED_UNSUPPORTED_PROTOCOL error).

2. Obtain the 7.8.4 firmware update file (<filename>.fuf) and authentication code file (<filename>.txt). As ksadmin, transfer these files into the /home/ksadmin/ directory of the appliance.

3. Take a system backup of all the CipherTrust Manager objects.

4. As the System Administrator (ksadmin) SSH in to the appliance (or connect via serial port using your password) and execute "/usr/safenet/lunaclient/bin/lunacm" utility.

5. Make sure an HSM admin slot is selected.

   To see the available slots, enter:

   lunacm:> slot list

   Copy

   Look for a slot with description "Admin Token Slot".

   To select the active slot, enter:

   lunacm:> slot set -slot <number>

   Copy

6. Login as the HSM Security Officer (SO). For PED-authenticated devices, you are prompted to insert the blue PED key. For password-authenticated devices, you are prompted for the HSM SO password.

   lunacm:> role login -name so

   Copy

7. Update the HSM with the 7.8.4 firmware upgrade file and authcode. You are prompted to confirm.

   lunacm:>hsm updatefw -fuf /home/ksadmin/<7.8.4_fuf_filename> -authcode /home/ksadmin/<7.8.4_authcode_filename>
   
       You are about to update the firmware.
       The HSM will be reset.
       Are you sure you wish to continue?
   
       Type 'proceed' to continue, or 'quit' to quit now ->proceed
   
       Updating firmware.  This may take several minutes.
   
       Firmware update passed.  Resetting HSM.

   Copy

   The update is applied and the HSM is restarted.

8. If you plan to use a Luna Backup HSM to backup root of trust keys, make sure the Backup HSM has a version compatible with HSM firmware 7.7.0 or higher.

Update PCIe Firmware for TCT CipherTrust Manager k570

To update the firmware:

1. If your appliance is PED-authenticated, ensure you have compatible PED firmware.

2. Obtain the firmware update file (<filename>.fuf) and authentication code file (<filename>.txt). As ksadmin, transfer these files into the /home/ksadmin/ directory of the appliance.

3. Take a system backup of all the CipherTrust Manager objects.

4. As the System Administrator (ksadmin) SSH in to the appliance (or connect via serial port using your password) and execute "/usr/safenet/lunaclient/bin/lunacm" utility.

5. Make sure an HSM admin slot is selected.

   To see the available slots, enter:

   lunacm:> slot list

   Copy

   Look for a slot with description "Admin Token Slot".

   To select the active slot, enter:

   lunacm:> slot set -slot <number>

   Copy

6. Login as the HSM Security Officer (SO). For PED-authenticated devices, you are prompted to insert the blue PED key. For password-authenticated devices, you are prompted for the HSM SO password.

   lunacm:> hsm login

   Copy

7. Update the HSM with the firmware upgrade file and authcode. You are prompted to confirm.

   lunacm:>hsm updatefw -fuf /home/ksadmin/<firmware_update_file>.fuf -authcode /home/ksadmin/<authcode_file>
   
       You are about to update the firmware.
       The HSM will be reset.
       Are you sure you wish to continue?
   
       Type 'proceed' to continue, or 'quit' to quit now ->proceed
   
       Updating firmware.  This may take several minutes.
   
       Firmware update passed.  Resetting HSM.

   Copy

   The update is applied and the HSM is restarted.

   

   Note

   Firmware upgrade can take a long time, depending on the number of objects stored on the HSM (a few minutes to several hours). Ensure that you can leave the update operation uninterrupted for this amount of time. Do not interrupt the procedure even if the operation appears to have stalled.