Install the HSM as an External Keystore

Learn how to enable your own hardware security module (HSM) as an external keystore for storing and managing Policy Manager PKI keys and certificates.

Table of Contents

Introduction

Policy Manager provides an External Keystore Feature that allows you to enable a Hardware Security Module (HSM) security provider as your cryptography solution for storing and managing Policy Manager PKI keys and certificates. After the External Keystore feature is installed, all key management tasks performed using the Manage PKI Keys Wizard for each identity (service, organization, container, or user) will be stored in the designated external keystore.

To learn how the External Keystore feature is used, consider a use case with this basic configuration:

  • Policy Manager and Network Director are installed in separate containers.
  • The External Keystore is installed on each container.
  • Policy Manager and Network Director are referencing the same keystore.
  • It is also possible to use different HSM devices (that is, a different external keystore) for Policy Manager and Network Director containers. In this case, the keys and aliases must be synchronized between each HSM device.

Note: The Policy Manager and Network Director containers can be stored on the same hardware device if you are using a simple USB version of HSM.

To set up and use HSM in this environment, take the following steps:

  1. Perform a list of prerequisite steps to configure HSM (see, Step 1: Prerequisites-HSM) and for the Akana Platform (see, Step 2: Prerequisites-Akana Platform Installation).
  2. When Policy Manager is initially installed, it creates a default keystore where all the PKI keys and certificates are stored. To replace the Policy Manager keystore and allow an identity to use HSM as an external keystore, install and configure the External Keystore feature.
  3. Install the Policy Manager Console and Policy Manager Services features.
  4. Configure external keystore options (provider name, keystore type, keystore location, and keystore password) to integrate HSM as an external keystore with Policy Manager.

After the External Keystore feature is installed and the environment is configured, all key management tasks performed using the Manage PKI Keys wizard for any identity will be stored in the designated external keystore.

Note: Assigning a tenant theme certificate from Community Manager is not supported when using CloudHSM as an external keystore to store PKI keys and certificates. However, you can assign the tenant theme certificate using the Assign Tenant Theme PKI API.

Step 1: Prerequisites-HSM

The external keystore feature supports:

  • Physical HSM devices

    For information about installing and configuring a specific HSM device, refer to the product documentation for the device.

  • Amazon AWS CloudHSM (Akana Platform version: 2020.2.0 and later)

    For information about installing and configuring CloudHSM, refer to the Amazon CloudHSM Getting Started guide: Getting Started with AWS CloudHSM.

  • Entrust HSM

    For information about installing and configuring a specific Entrust HSM device, refer to the product documentation for the device.

  • The provider name, keystore type, keystore location, and keystore password.

Step 2: Prerequisites-Akana Platform Installation

HSM integration with the Akana Platform uses the respective JCE provider. The HSM client software must be configured to use this JCE provider on each of the machines that will be running the Akana Platform software and all connectivity between these machines and the HSM device must be configured.

The following basic steps are required to configure the external keystore for an HSM device:

  • Get the .jar file from the applicable HSM security provider and copy it into the $JAVA_HOME/jre/lib/ext folder of the container in which the Akana Platform is installed.
  • Update the java.security provider file, which is located at $JAVA_HOME/jre/lib/security/ with the HSM JCE provider.

Example .jar files for CloudHSM

The following example shows the .jar files for CloudHSM:

cloudhsm-3.4.4.jar
log4j-slf4j-impl-2.17.1.jar
log4j-over-slf4j-1.7.32.jar
log4j-core-2.17.1.jar
log4j-api-2.17.1.jar

Example java.security file for CloudHSM

The following example shows the properties in the java.security file and in the Akana Administration console for the Cavium JCE provider.

The java.security file including the Cavium JCE provider required for CloudHSM:

security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=sun.security.ec.SunEC
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=com.sun.security.sasl.Provider
security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.9=sun.security.smartcardio.SunPCSC
security.provider.10=com.cavium.provider.CaviumProvider
security.provider.11=org.bouncycastle.jce.provider.BouncyCastleProvider

The corresponding properties in the Akana Administration Console for the container:

Step 3: Create Policy Manager and Network Director Containers

Launch the Configure Container Instance Wizard and define containers for Policy Manager and Network Director. For installation instructions, go to Performing the installation section of Installing the Akana API Platform and complete steps 2-1 to 2-3 of the installation procedure and then use the following instructions for each container (Steps 4 - 10).

You can also add the environment variables for starting the Policy Manager and Network Director containers by using the following command:

./startup.sh eap-cloudhsm -DHSM_PARTITION=PARTITION_1 -DHSM_USER=cryptoUser -DHSM_PASSWORD=password -Djava.library.path=/opt/cloudhsm/lib

Note: Verify the logs to check for Cavium exceptions in the startup.log file.

Step 4: Install the External Keystore Feature

  1. Launch the Akana Administration Console (http://<hostname:<port>/admin/) or use an automation recipe to install an external keystore. For more information, see Using the External Keystore recipe under Automation Examples section.
  2. On the Available Features tab, select Plug-in from the dropdown list, and select the External Keystore checkbox.

  3. Click Install Feature. The required bundles are installed for the External Keystore feature.
  4. If If prompted, restart the container after installing the plug-in.

Step 5: Install the Policy Manager Features

  1. On the Available Features tab, from the Filter menu, select Feature.
  2. Install the Policy Manager features by selecting the Policy Manager Services and Policy Manager Console checkboxes.
  3. Click Install Feature. The required bundles are installed for the Policy Manager Services and Policy Manager Console.
  4. If prompted, restart the container after installing the Policy Manager features.

Step 6: Configure the External Keystore

  1. In the Akana Administration Console, on the Configuration tab, select Configuration Actions and Configure External Keystore. The External Keystore Options window is displayed or use an automation recipe to configure an external keystore, see Using the External Keystore recipe under Automation Examples section.

    External Keystore Options page

  2. Specify the provider name, keystore type, keystore location, and keystore password. See, HSM Device prerequisite tasks.
  3. Specify the encryption option:

    • If you select the Encrypted checkbox, Policy Manager will attach an alias and Network Director will obtain the private key directly from the external keystore by using the alias provided by Policy Manager.

    • If you do not select the Encrypted checkbox, Policy Manager will attach the encrypted private key directly to the WSDL.

    • If you are using another type of encryption engine, such as Sun JCE, the Encryption checkbox can be selected or cleared.

  4. To complete the configuration of the External Keystore feature, click Finish.

  5. If prompted, restart the container for the changes to take effect.

Step 7: Assign Keys from the External Keystore

  1. The key management option provides functions for performing key and certificate management for a container. To select the key management option, in the Akana Administration Console, click the Configuration tab. Then, select Configuration Actions and Manage PKI Keys. Under Assignment options, select Assign PKI Keys and X.509 Certificate from User Keystore option to assign PKI Keys and an X.509 Certificate from an external keystore to the current identity by selecting the keystore alias and password associated with the key that you want to assign. Click Next.

  2. Select the user keystore alias and specify the password associated with the key.

  3. Click Finish.

Step 8: Assign Keys to the Administrator Account

When you install the External Keystore feature, keys are not automatically assigned to the Policy Manager Administrator user account as they are when you are using the Policy Manager default keystore. For a list of Manage PKI Key Wizard options available for each identity type, see Key Management.

  1. Launch the Policy Manager Management Console and go to Security > Users. Select the Administrator user account and click Manage PKI Keys.
    • If you select the Generate PKI Keys and X.509 Certificate option, you can define an alias to assign to the PKI Keys and X.509 Certificate being generated. This alias will be stored in your external keystore.
    • You can also choose to assign the keys to an existing alias already defined in the keystore, on the Assign Keys from External Keystore page. The Assign Keys from External Keystore option allows you to assign keys stored in your external keystore to the current identity by selecting the keystore alias and password.
  2. Select the user keystore alias and specify the password associated with the key.

    Assign Keys from External Keystore page

  3. Click Finish.

Note: When performing key operations using CloudHSM, no alias password is required to perform key operations because the encrypted username and password are already passed when the container is started. The result is that any password provided as part of the payload is ignored, i.e., a wrong password would not cause the operation to fail.

Step 9: Configure Network Director

  1. Launch the Akana Administration Console for the Network Director container instance (http://<hostname:<port>/admin/).
  2. On the Available Features tab, select Network Director and External Keystore features, and then click Install Feature.
  3. When the installation is complete, on the Configuration tab, click Configuration Actions and Configure External Keystore. The External Keystore Options window is displayed.
  4. Specify the provider name and keystore type (you obtained these values as part of the HSM Device prerequisite tasks), enter a keystore location, and provide the keystore password.

    If you are using one external keystore for all container instances, enter the same values that you used to configure the external keystore on the Policy Manager container instance.

    If you are using a different external keystore for your Network Director container instance, enter the unique values for the external keystore. After completing the configuration, refer to the Generate Options > Generate PKI Keys and X.509 Certificate > External Keystore section of Managing Keys and Certificates to learn how to reference an alias in the Network Director keystore using the Manage PKI Keys wizard.

    External Keystore Options page

  5. Click Finish and then complete the remainder of the Network Director configuration.
  6. Register the Network Director with Policy Manager by using the container wizard. Click Add Container Wizard.

    Policy Manager: Add Container wizard

  7. Configure a contract, physical and virtual services, and host on Network Director.
  8. Send requests to Network Director and verify that they are processed successfully.

The configuration is now complete. All key management tasks performed by the Manage PKI Keys Wizard for each identity type will now be stored in the external keystore. For the Manage PKI Key Wizard options available for each identity type, see Managing Keys and Certificates.

Step 10: Verify the External Keystore Installation

  1. Restart the system.
  2. Optionally, verify that the PKI keys are not stored in the database. Policy Manager only stores the alias and encrypted password for external keystore entries.
  3.  You can also verify that the Policy Manager secret key is not being stored in the database. All the key and seed entries for the pmdomain user are null.

    Database view: key and seed entries for PM domain user are null