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.