Key Store Management

• 1: Support Matrix
• 2: Configuring the ESA with HSMs supporting PKCS#11 Interface
• 3: Configuring the ESA with the Thales Luna HSM
• 4: Configuring the ESA with Thales Data Protection on Demand (DPoD) HSM
• 5: Configuring the ESA with AWS Key Management System (KMS)
• 6: Configuring the ESA with Google Cloud KMS
• 7: Configuring the ESA with Azure Key Vault Managed HSM
• 8: Switching Key Stores
• 9: Troubleshooting
• 10: TAC Replication of Key Store-specific Files and Certificates

1 - Support Matrix

Support Matrix for HSM

The following table for the support matrix describes the hardware requirements, software requirements, and the compatibility information of the Enterprise Security Administrator (ESA) and the Hardware Security Module (HSM).

Support Matrix for Cloud Platforms

The following table provides compatibility information of the cloud platforms, such as Amazon Web Services (AWS), Azure, and Google Cloud Platform (GCP) with the Protegrity ESA appliance.

2 - Configuring the ESA with HSMs supporting PKCS#11 Interface

Verifying the Prerequisites

Ensure that the following prerequisites are met:

1. Ensure that you have downloaded HSM Client on your local machine.

2. Ensure that the HSM partition is initialized.

3. Ensure that you have downloaded the required libraries, configuration files, and certificates required for connecting to the HSM. The certificates can include the server certificate of the HSM, the client certificate for the ESA appliance, and the CA certificate.
   For more information required about the files required for connecting to the HSM, refer the documentation for the corresponding HSM.

Configuring Connection with HSM

To configure a connection with an HSM:

1. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

2. Click New Key Store.

   The Create New Key Store screen appears.

3. In the Key Store Information section, enter the following details.

   • Name: Type a unique name for HSM. The name that you type will update the Key Store installation path field.
   • Type: Select PKCS #11.

4. In the PKCS#11 details section, enter the following details:

   • User pin: Specify the user pin for the given slot ID of the HSM.
   • Slot: Enter the slot ID for the HSM.

5. Perform the following steps to add the environment variables.
   To configure the PKCS #11 connection, you need to override the default location of the HSM configuration file. You can do this by setting the environment variable for the HSM-specific library.

   1. In the Key Store files and environment variables > Key Store environment variables section, click Add environment variable.
      The Add Key Store environment variable dialog box appears.

   2. Enter the following details:

   • Environment variable name: Specify the environment variable name for the HSM.
     For example, specify the ChrystokiConfigurationPath for Thales Luna HSM.
   • Environment variable value: Specify the value for the environment variable.
     For example, specify /opt/protegrity/keystore/<Keystore_name>, which is the value of the Key Store installation path field, for the Thales Luna HSM.
     If you want to mask the value of the variable in the UI, then click the Sensitive toggle to the on position. This ensures that the variable value is hidden while typing and is replaced with asterisks of a fixed-length in the list of environment variables.
   3. Click Save.

6. In the Key Store files and environment variables > Key Store files section, click Add File.
   The Add Key Store File dialog box appears.

7. Select the specific file type from the drop-down menu. The following table provides more detail on each selectable type. Note that only one type of file can be selected at a time.

8. Click Add File to add the file to the Key Store files section.

9. Repeat steps 7 to 8 till you have added all the files required to connect to the Key Store.

10. Perform the following steps to edit the configuration file.
    a. Click the Edit icon next to the configuration file.
    The Edit Key Store File screen appears.

    b. Update the path of the required configuration parameters to match the path displayed in the Key Store installation path field.

    c. Click Save.
    The Edit Key Store File screen closes.

11. Click Save.
    The Key Store saved successfully message appears.

12. Click Test to test the Key Store connection.
    The Test Key Store Connection dialog box appears.

13. Click OK to close the Test Key Store Connection dialog box.

14. Click Set As Active to activate the Key Store.

3 - Configuring the ESA with the Thales Luna HSM

Verifying the Prerequisites

Ensure that the following prerequisites are met:

1. Ensure that the HSM partition is initialized.

2. Ensure that you have downloaded the required libraries, configuration files, and certificates required for connecting to the HSM. The certificates can include the server certificate of the Thales Luna HSM, the client certificate for the ESA appliance, and the CA certificate.
   For more information required about the files required for connecting to the Thales Luna HSM, refer to the Thales Luna documentation.

3. Ensure that the following roles on the Thales Luna HSM are granted read and write permissions:

   • Partition Officer (PO) / Security Officer (SO)
   • Crypto Officer (CO)
   • Crypto User (CU)

   It is recommended to configure the Thales Luna HSM client library to authenticate using the Crypto User (CU). The following setting in the Miscellaneous section of the Chrystoki.conf configuration file configures the role to use for the challenge request status.

   ProtectedAuthenticationPathFlagStatus = 2
   

   Note: The Crypto User (CU) must be initialized on the Thales Luna HSM by using methods, such as, setting a PIN for the Crypto User (CU).
   For more information about initializing the Crypto User (CU), refer to the documentation of the HSM vendor.

Configuring Connection with Thales Luna HSM

To configure a connection with Thales Luna HSM:

1. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

2. Click New Key Store.

   The Create New Key Store screen appears.

3. In the Key Store Information section, enter the following details.

   • Name: Type a unique name for HSM. For example, type Thales_Luna_HSM. The name that you type will update the Key Store installation path field.
   • Type: Select PKCS #11.

4. In the PKCS#11 details section, enter the following details:

   • User pin: Specify the user pin for the given slot ID of the Thales Luna HSM.
   • Slot: Enter the slot ID for the Thales Luna HSM.

5. In the Key Store files and environment variables > Key Store environment variables section, click Add environment variable.
   The Add Key Store environment variable dialog box appears.

6. Enter the following details, and then click Save:

   • Environment variable name: Specify ChrystokiConfigurationPath as the environment variable name for the Thales Luna HSM.
   • Environment variable value: Specify the value for the environment variable.
     For example, specify /opt/protegrity/keystore/<Keystore_name>, which is the value of the Key Store installation path field, for the Thales Luna HSM.
     If you want to mask the value of the variable in the UI, then click the Sensitive toggle to the on position. This ensures that the variable value is hidden while typing and is replaced with asterisks of a fixed-length in the list of environment variables.

7. In the Key Store files and environment variables > Key Store files section, click Add File.
   The Add Key Store File dialog box appears.

8. Enter the following details.

   File Type	File
   Library	Select the libCryptoki2_64.so HSM library file from your local machine.
   Configuration	Select the Chrystoki.conf HSM configuration file from your local machine.
   Other	Select the Thales Luna HSM client certificate, client key, and server certificate from your local machine.

Note: You can select only one file at a time.

9. Click Add File to add the file to the Key Store files section.

10. Repeat steps 7 to 9 till you have added all the files required to connect to the Key Store.

11. Perform the following steps to edit the configuration file.
    a. Click the Edit icon next to the configuration file.
    The Edit Key Store File screen appears.

    b. Update the path of the required configuration parameters to match the path displayed in the Key Store installation path field.

    c. Click Save.
    The Edit Key Store File screen closes.

12. Click Save.
    The Key Store saved successfully message appears.

13. Click Test to test the Key Store connection.
    The Test Key Store Connection dialog box appears.

14. Click OK to close the Test Key Store Connection dialog box.

15. Click Set As Active to activate the Key Store.
    > Note: If you are using the Thales Luna HSM on an external network, then the policy management services might have a longer start-up time due to network latency.

4 - Configuring the ESA with Thales Data Protection on Demand (DPoD) HSM

Verifying the Prerequisites

Ensure that the following prerequisites are met:

1. Ensure that the HSM partition is initialized.

2. Ensure that you have downloaded the required libraries, configuration files, and certificates required for connecting to the HSM. The certificates can include the server certificate of the Thales DPoD HSM, the client certificate for the ESA appliance, and the CA certificate.
   For more information required about the files required for connecting to the Thales DPoD HSM, refer to the Thales DPoD documentation.

3. Ensure that the following roles on the Thales DPoD HSM are granted read and write permissions:

   • Partition Officer (PO) / Security Officer (SO)
   • Crypto Officer (CO)
   • Crypto User (CU)

Configuring Connection with Thales DPoD HSM

To configure connection with Thales DPoD HSM:

1. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

2. Click New Key Store.

   The Create New Key Store screen appears.

3. In the Key Store Information section, enter the following details.

   • Name: Type a unique name for HSM. For example, type Thales_DPoD_HSM. The name that you type will update the Key Store installation path field.
   • Type: Select PKCS #11.

4. In the PKCS#11 details section, enter the following details:

   • User pin: Specify the user pin for the given slot ID of the Thales DPoD HSM.
   • Slot: Enter the slot ID for the Thales DPoD HSM.

5. In the Key Store files and environment variables > Key Store environment variables section, click Add environment variable.
   The Add Key Store environment variable dialog box appears.

6. Enter the following details, and then click Save:

   • Environment variable name: Specify ChrystokiConfigurationPath as the environment variable name for the Thales DPoD HSM.
   • Environment variable value: Specify the value for the environment variable.
     For example, specify /opt/protegrity/keystore/<Keystore_name>, which is the value of the Key Store installation path field, for the Thales DPoD HSM.
     If you want to mask the value of the variable in the UI, then click the Sensitive toggle to the on position. This ensures that the variable value is hidden while typing and is replaced with asterisks of a fixed-length in the list of environment variables.

7. In the Key Store files and environment variables > Key Store files section, click Add File.
   The Add Key Store File dialog box appears.

8. Enter the following details.

   File Type	File
   Library	Select the libCryptoki2_64.so HSM library file from your local machine.
   Configuration	Select the Chrystoki.conf HSM configuration file from your local machine.

Note: You can select only one file at a time.

9. Click Add File to add the file to the Key Store files section.

10. Repeat steps 7 to 9 till you have added all the files required to connect to the Key Store.

11. Perform the following steps to edit the configuration file.
    a. Click the Edit icon next to the configuration file.
    The Edit Key Store File screen appears.

    b. Update the path of the required configuration parameters to match the path displayed in the Key Store installation path field.

    c. Click Save.
    The Edit Key Store File screen closes.

12. Click Save.
    The Key Store saved successfully message appears.

13. Click Test to test the Key Store connection.
    The Test Key Store Connection dialog box appears.

14. Click OK to close the Test Key Store Connection dialog box.

15. Click Set As Active to activate the Key Store.

Note: If you are using the Thales DPOD HSM on an external network, then the policy management services might have a longer start-up time due to network latency.

5 - Configuring the ESA with AWS Key Management System (KMS)

Verifying the Prerequisites

Ensure that the following prerequisites are met before configuring the ESA with the AWS Key Store.

Authorization

The Amazon Web Services Key Management Service (AWS KMS) allows you to enable the creation of the data encryption key (DEK). Additionally, you can also encrypt and decrypt the data, and generate random bytes of data using the Key Management Gateway (KMGW) in the ESA.

To use the AWS KMS as a key store, the following permissions are required by the AWS user or role:

Table: Permissions for accessing AWS KMS user or role

Authentication

Authentication methods depend on if using AWS or On Premise.

On AWS

If the ESA EC2 instance is running on the AWS and an IAM role is setup, then the IAM role gets linked to the ESA EC2 instance. Further, the SDK automatically gets the credentials to perform authenticated calls to the AWS.

On Premise

If the ESA is running on any other environment, then ensure to set up the environment by generating the long-term credentials on the AWS. The following environment variables are used to set the long-term credentials:

Table: List of Environments Variables to set the long-term credentials

Note: Ensure that the environments marked with * are set when they are not running on the EC2 instance.

Configuring Connection with AWS KMS with the AWS Customer Managed Keys

The Key Store with the AWS customer managed keys is configured by using one of the following methods:

• Setting the environment variables.
• Using the roles that are set in the AWS KMS environment.

Configuring the AWS Key Store using the Environment Variables

To configure connection with AWS KMS using the environment variables:

1. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

2. Click New Key Store.

   The Create New Key Store screen appears.

3. In the Key Store Information section, enter the following details.

   • Name: Type a unique name for AWS KMS. For example, type AWS_KMS. The name that you type will update the Key Store installation path field.
   • Type: Select AWS KMS.

4. In the Key Store files and environment variables > Key Store environment variables section, click Add environment variable.
   The Add Key Store environment variable dialog box appears.

5. Enter the following details, and then click Save:

   • Environment variable name: Specify the environment variable name for the AWS KMS. For example, specify the following entries:
     • AWS_ACCESS_KEY_ID
     • AWS_SECRET_ACCESS_KEY
     • AWS_REGION
   • Environment variable value: Specify the value for the corresponding environment variable.
     If you want to mask the value of the variable in the UI, then click the Sensitive toggle to the on position. This ensures that the variable value is hidden while typing and is replaced with asterisks of a fixed-length in the list of environment variables.

6. Click Save.
   The Key Store saved successfully message appears.

7. Click Test to test the Key Store connection.
   The Test Key Store Connection dialog box appears.

8. Click OK to close the Test Key Store Connection dialog box.

9. Click Set As Active to activate the Key Store.
   The AWS Key Store is set as active.

Note: You should verify that the master key is generated by the AWS Key Store.

Configuring the AWS Key Store using the Authorized IAM Role

Before you begin: Ensure that an ESA instance is created in the AWS.

To configure the AWS Key Store by using the authorized IAM role:

1. In the AWS screen, navigate to AWS > EC2.

2. Select the required instance.

3. Navigate to Actions > Security > Modify IAM.

4. Select the role with the AWS KMS permissions.

   The IAM role is modified for the instance.

5. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

6. Click New Key Store.

   The Create New Key Store screen appears.

7. In the Key Store Information section, enter the following details.

   • Name: Type a unique name for AWS KMS. For example, type AWS_KMS.
   • Type: Select AWS KMS.

8. Click Save.
   The Key Store saved successfully message appears.

9. Click Test to test the Key Store connection.
   The Test Key Store Connection dialog box appears.

10. Click OK to close the Test Key Store Connection dialog box.

11. Click Set As Active to activate the Key Store.
    The AWS Key Store is set as active.

Note: You should verify that the master key is generated by the AWS Key Store.

Keys in AWS KMS

The AWS KMS keys are tagged with the following two tags:

• Owner: Protegrity
• Service: KMGW

These tags are used to search or filter keys which are created by the KMGW.

6 - Configuring the ESA with Google Cloud KMS

Verifying the Prerequisites

Ensure that the following prerequisites are met before configuring the ESA with the Google Cloud KMS.

Authorization

The resources are organized into a hierarchy in the GCP Key Store. This hierarchy helps to manage and grant access to the resources at various levels of granularity. The scope of the role depends on the level of the resource hierarchy, where the role is granted to access the Google Cloud resources.

The user or service account attached to the ESA requires the following permissions:

Table: Permissions for accessing Google Cloud KMS

Creating a Key Ring

The Enterprise Security Administrator (ESA) appliances needs a Key ring to store Key Encryption Keys (KEK).

1. Navigate to the Key Management screen in the Google Cloud console.

2. Click Create key ring.

3. In the Key ring name field, enter the required name for the key ring.

4. From the Key ring location drop-down list, select a location.

   Note: The Key ring must be created in a location where Hardware Security Module (HSM) support is enabled. For more information on supported locations refer to https://cloud.google.com/kms/docs/locations.

5. Click Create. Key rings are created for the selected region.

Configuring Connection with Google Cloud KMS

To configure a connection with Google Cloud KMS:

1. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

2. Click New Key Store.

   The Create New Key Store screen appears.

3. In the Key Store Information section, enter the following details.

   • Name: Type a unique name for Google Cloud KMS. For example, Google_Cloud_KMS. The name that you type will update the Key Store installation path field.
   • Type: Select Google Cloud KMS.

4. In the Google Cloud KMS details section, enter the following details:

   • Project
   • Key Ring
   • Location

5. In the Key Store files and environment variables > Key Store environment variables section, click Add environment variable.
   The Add Key Store environment variable dialog box appears.

6. Enter the following details, and then click Save:

   • Environment variable name: Specify the environment variable name for the Google Cloud KMS. For example, specify GOOGLE_APPLICATION_CREDENTIALS.
   • Environment variable value: Specify the value for the corresponding environment variable. For example, specify /opt/protegrity/keystore/Google_Cloud_KMS/credentials.json.
     If you want to mask the value of the variable in the UI, then click the Sensitive toggle to the on position. This ensures that the variable value is hidden while typing and is replaced with asterisks of a fixed-length in the list of environment variables.

7. In the Key Store files and environment variables > Key Store files section, click Add File.
   The Add Key Store File dialog box appears.

8. Enter the following details.

   File Type	File
   Other	Select the Application Credentials JSON file for the Google Cloud KMS from your local machine.

9. Click Add File to add the file to the Key Store files section.

10. Click Save.
    The Key Store saved successfully message appears.

11. Click Test to test the Key Store connection.
    The Test Key Store Connection dialog box appears.

12. Click OK to close the Test Key Store Connection dialog box.

13. Click Set As Active to activate the Key Store.
    The Google Cloud KMS is set as active.

Note: You should verify that the master key is generated by the Google Cloud KMS.

Viewing Keys under the Key Ring

After activating the Google Cloud KMS, a new Master Key is created under the configured key ring.

To view keys under the Key Ring:

1. Navigate to the GCP Console > Key management > Key_ring_name > Keys.

2. Verify that the master key UID and key under the Key ring location is the same.

   Note: The keys in the Key ring must not be rotated on GCP, as the ESA will not register it. Also, when a key is rotated on the ESA, a new key will be created in the Key ring and it will not create a new version of the key in GCP.

7 - Configuring the ESA with Azure Key Vault Managed HSM

Verifying the Prerequisites

Ensure that the following prerequisites are met before configuring the ESA with the Azure Key Vault Managed HSM.

Configuring the Managed HSM

Protegrity supports the Managed HSM Key Vault type due to the presence of Get Random Bytes functionality, which is not available in the standard Key Vault.

Ensure that the Azure Managed HSM is already set up and activated on your system.

For more information about setting up an Azure Managed HSM, refer to Quickstart: Provision and activate a Managed HSM using Azure CLI.

Authentication Components for Azure

You can choose one of the following authentication methods.

Service Principal

When you register a new application in Microsoft Entra ID, a Service Principal is automatically created. This Service Principal acts as the application identity within the Microsoft Entra tenant and controls access to resources based on the roles assigned to it.

Ensure that the Service Principal is created with access to the Key Vault. For more information about Service Principal using the CLI, refer to Create an Azure service principal with Azure CLI.

For more information about Service Principal using the Web UI, refer to Register a Microsoft Entra app and create a service principal.

When you create the Service Principal, the AZURE_CLIENT_SECRET and AZURE_CLIENT_ID values are generated.

The Service Principal is added to the Local RBAC of the Azure Managed HSM. The Service Principal is assigned the Managed HSM Crypto User role.

If you have the Azure CLI installed, then you can perform this operation with the help of the following command.

az keyvault role assignment create --hsm-name [NAME of key vault] --role "Managed HSM Crypto User" --assignee [ID of service principal] --scope /

System Managed Identity

Some Azure resources, such as virtual machines, allow you to enable a System Managed Identity directly on the resource. The System Managed Identity exists only as long as the underlying resource remains active. The name of the System Managed Identity is the same as the Azure resource it’s created for.

For more information about enabling the system managed identity, refer to Managed identities for Azure resources documentation.

The System Managed Identity is added to the Local RBAC of the Azure Managed HSM. The System Managed Identity is assigned the Managed HSM Crypto User role.

If you have the Azure CLI installed, then you can perform this operation with help of the following command.

az keyvault role assignment create --hsm-name [NAME of key vault] --role "Managed HSM Crypto User" --assignee [ID of system managed identity] --scope /

Configuring Connection with Azure Key Vault Managed HSM

To configure connection with Azure Key Vault Managed HSM:

1. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

2. Click New Key Store.

   The Create New Key Store screen appears.

3. In the Key Store Information section, enter the following details.

   • Name: Type a unique name for Azure KMS. For example, Azure_KMS. The name that you type will update the Key Store installation path field.
   • Type: Select Azure Key Vault Managed HSM.

4. In the Azure Key Vault Managed HSM details section, specify the URI of the Azure Vault in the Azure Vault URI field.
   For example, specify https://<Vault_Name>.managedhsm.azure.net as the URI.

5. In the Key Store files and environment variables > Key Store environment variables section, click Add environment variable.
   The Add Key Store environment variable dialog box appears.

6. Enter the following details, and then click Save:

   • Environment variable name: Specify the environment variable name for the Azure KMS. For example, specify the following entries:
     • AZURE_TENANT_ID
     • AZURE_SUBSCRIPTION_ID
     • AZURE_CLIENT_ID
     • AZURE_CLIENT_SECRET
   • Environment variable value: Specify the value for the corresponding environment variable.
     If you want to mask the value of the variable in the UI, then click the Sensitive toggle to the on position. This ensures that the variable value is hidden while typing and is replaced with asterisks of a fixed-length in the list of environment variables.

7. Click Save.
   The Key Store saved successfully message appears.

8. Click Test to test the Key Store connection.
   The Test Key Store Connection dialog box appears.

9. Click OK to close the Test Key Store Connection dialog box.

10. Click Set As Active to activate the Key Store.
    The Azure Key Store is activated successfully.

Verify that the master key is generated successfully by the Azure Key Store by navigating to Key Management > Master Keys.

8 - Switching Key Stores

Verify individual vendor’s requirement

When using a Key Store (HSM) provided by a specific vendor, consult the vendor to ensure that the infrastructure in place can handle any issues with the Key Store. Issues can include data loss or breakdowns. With the required measures in place, minimal impact to the business critical data and the involved processes can be ensured. Ensure that you follow the best practices specified by the vendor for business continuity.

Before you begin

If you are switching between Key Stores, then ensure that you take a backup of the policy management-related data.
For more information about backup and restore of Policy Management, refer to the section Working with Backup and restore. If you encounter failures when working with the new Key Store, then you can switch to the previous Key Store by following the guidelines specified by the corresponding vendor.

Note: It is recommended that before switching to a Key Store, you test it.

To switch Key Stores:

1. On the ESA Web UI, navigate to Key Management > Key Stores.

   The Key Stores screen appears.

2. In the Action column, click Set As Active next to the Key Store that you want to activate.
   The corresponding Key Store is activated. For an active Key Store, the Set As Active button is grayed out.

3. To verify that the Key Store has been activated, navigate to Key Management > Master Keys.
   In the Current key info section, the Generated By field displays the name of the Key Store that has generated the Master Key.

9 - Troubleshooting

The following section provides information about errors that are related to HSM integration with the ESA and the steps to resolve the errors.

• Known Error or Problem: When you try to switch to an HSM, the switch fails.

  This may happen because:

  The HSM does not support or allow the type of key that is used.

  Recovery:

  Verify that the HSM supports creating secret keys with the following attributes:

  • CKA_PRIVATE: TRUE
  • CKA_SENSITIVE: TRUE
  • CKA_EXTRACTABLE: FALSE
  • CKA_ENCRYPT: TRUE
  • CKA_DECRYPT: TRUE
  • CKA_MODIFIABLE: FALSE
  • CKA_WRAP: TRUE
  • CKA_UNWRAP: TRUE
  • CKA_DERIVE: FALSE
  • CKA_SIGN: FALSE
  • CKA_VERIFY: FALSE

• Known Error or Problem: In a TAC, the source ESA is configured with the Key Store and the target ESA is configured with the Protegrity Soft HSM. Export the policy management settings from the source ESA to the target ESA with the Backup Policy-Management for Trusted Appliances Cluster without Key Store option selected. The HubController service on the target ESA stops with the following error:
  [SEVERE ] Failed to start HubController [Caused by: Failed to start Key verticle: Failed to decrypt key: "..."

  Recovery:

  The following steps must be performed on the target ESA to address this issue.

  1. On the target ESA, configure the Key Store with the same name as that of the Key Store on the source ESA.
  2. Enter the same user pin that you have specified for the Key Store in the source ESA.
  3. Test the Key Store connection.

• Known Error or Problem: When you log in to the ESA instance in either AWS or GCP, the following error appears.
  WARNING: Failed to find a usable hardware address from the network interfaces; using random bytes: 1b:1f:ff:64:9b:b6:ea:ce

  This may happen because:

  The licenses generated are not locked to the MAC address of the ESA machine.

  Recovery:

  You must contact Protegrity support to generate a license file that is linked to the MAC address of the ESA machine.

• Known Error or Problem: The changed HSM PIN does not match the Key Store PIN on the primary ESA. In this case, restarting the HubController on the primary ESA may lead to one of the following issues:

  • A broken connection with the secondary ESA.
  • The secondary ESA being restored without the Key Store.

  This may happen because:

  If you change the PIN of the HSM but not on the primary ESA and then restart the HubController on the primary ESA.

  Recovery:

  Update the Key Store PIN on the primary ESA to match the one on the HSM, if you can access the Key Store. If the Key Store or Policy Management is inaccessible, then contact Protegrity Support.
  Important: Do not restart or stop the HubController while updating the Key Store PIN on the primary ESA to match the one on the HSM.
  For more information about this recovery method, contact Protegrity Support.

• Known Error or Problem: Key Store connection fails. This error can be identified when one of the following scenario occurs:

  • Key rotation, data store creation, or encryption key creation fails.
  • Key store test connection displays an error.

  This may happen because:

  • Credentials are changed or expired.
  • Certificates are changed or expired.
  • The ESA time is not synchronized with the NTP server. For more information about synchronizing the ESA time with the NTP server, refer to the section Setting Date and Time.

  Recovery:

  Do not restart the HubController on the ESA. Instead, perform the following steps:

  1. Test the Key Store connection. Review the error message for guidance.
  2. Check the HubController and the Key Management Gateway (KMGW) logs in the troubleshooting index in the Audit Store dashboard. For more information about the Audit Store dashboard, refer to the section Viewing the dashboards.
  3. Fix the issues based on the information available in the logs. Update any changed fields with accurate information.
  4. Retest the Key Store connection after making the changes.
  5. If the issues persist, contact Protegrity Support.

• Known Error or Problem: When you configure an HSM on the primary ESA and do not import the Key Store configuration to the secondary ESA, the HubController service cannot be started on the secondary ESA.

  This may happen because:

  You set up the secondary node via the Trusted Appliance Cluster (TAC), or performed a backup and restore of the primary ESA on the ESA Web UI by selecting Backup and Restore > Backup Policy-Management for Trusted Appliances Cluster without Key Store. You then ran the task from the Task Scheduler on the primary ESA to restore the backed up files on the secondary ESA.
  For more information about TAC Replication of HSM, refer to TAC Replication of Key Store-specific Files and Certificates.

  Recovery:

  The following steps must be performed on the target ESA to address this issue.

  1. On the target ESA, configure the Key Store with the same name as that of the Key Store on the primary ESA.
  2. Enter the same user pin that you have specified for the Key Store in the primary ESA.
  3. Test the Key Store connection.

10 - TAC Replication of Key Store-specific Files and Certificates

A Trusted Appliances cluster (TAC) is a tool, where appliances such as the ESA replicate and maintain information. A trusted channel is created to transfer data between the appliances in a cluster. This section describes the steps that must be followed for replication of the Key Store-specific files and certificates in a TAC. In addition, it also explains the measures you must take while performing a replication without the Key Store files and certificates.

For more information about TAC, refer to the section Trusted Appliances Cluster (TAC).

A Key Store can be configured to accept either of the following:

• Same certificate from all the clients. In this scenario, select the Backup Policy-Management for Trusted Appliances Cluster option from the System > Backup & Restore > Export screen.
• Client-specific certificates. In this case, the TAC replication must not include Key Store files and certificates. In addition, all the nodes in the cluster must be configured to connect to the same Key Store host and Key Store slot. In this scenario, select the Backup Policy-Management for Trusted Appliances Cluster without Key Store option from the System > Backup & Restore > Export screen.

Replicating the Key Store-specific Files and Certificates in a TAC

This section explains the steps that must be followed to ensure replication of the Key Store files and certificates in a Trusted Appliances Cluster (TAC).

1. On the source ESA, switch from Protegrity Soft HSM to Key Store.
   For more information about switching from Protegrity Soft HSM to Key Store, refer to section Switching Key Stores.

2. Create a TAC between the source and the target ESA.
   For more information about creating a TAC, refer to the section Trusted Appliances Cluster (TAC).

3. On the source ESA, navigate to the ESA Web UI > System > Backup & Restore.

4. Select Cluster Export.

5. Select Backup Policy-Management for Trusted Appliances Cluster.
   This option exports the policy management configurations and data from the source ESA to a specific target ESA node in a Trusted Appliances Cluster. The data includes the Key Store specific files and certificates.

Excluding the Key Store-specific Files and Certificates in a TAC Replication

This section explains the measures you must take while performing a TAC replication without the Key Store files and certificates.

Caution: This section must be followed only when you have a Key Store configured with client-specific certificates on the target ESA nodes, but the Key Store is not in Active state.

If you are using the Backup Policy-Management Trusted Appliances Cluster option by navigating to the ESA Web UI > System > Backup & Restore, then the TAC replication process replaces the Key Store specific files and certificates on the target ESA with the files and certificates from the source ESA. If you want to retain client-specific Key Store files and certificates on the target ESA during TAC replication, then ensure that you select the Backup Policy-Management for Trusted Appliances Cluster without Key Store option.

The following steps must be performed to ensure that the initial TAC replication setup is completed successfully with the client-specific Key Store files and certificates for the source ESA and the target ESA.

1. On the source ESA, switch from Protegrity Soft HSM to Key Store.
   For more information about switching from Protegrity Soft HSM to Key Store, refer to section Switching Key Stores.

2. On the target ESA, configure the Key Store with the same name as that of the Key Store on the source ESA.

Important: Do not activate the Key Store on the target ESA.

3. Create a TAC between the source and the target ESA.
   For more information about creating a TAC, refer to the section Trusted Appliances Cluster (TAC).

4. On the source ESA, navigate to the ESA Web UI > System > Backup & Restore.

5. Select Cluster Export.

6. Select Backup Policy-Management for Trusted Appliances Cluster without Key Store.
   This option exports the policy management configurations and data excluding the Key Store files and certificates to a specific cluster node in a Trusted Appliances Cluster.