Using the External Keystore Feature
Learn how to enable your own hardware security module (HSM) as an external keystore for storing and managing Policy Manager PKI keys and certificates.Managing Keys Identity Categories
Supported Platforms: 7.1, 7.2
Table of Contents
- Step 1: Prerequisites - HSM Device
- Step 2: Prerequisites - Platform Installation
- Step 3: Create Policy Manager / Network Director Containers
- Step 4: Install External Keystore Feature
- Step 5: Install Policy Manager Features
- Step 6: Configure External Keystore Options
- Step 7: Verify External Keystore Installation
- Step 8: Assign Keys for Administrator Account
- Step 9: Configure Network Director
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 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.
Some important points to note:
- Policy Manager and Network Director must be installed in separate containers.
- The External Keystore Feature must be installed in each of these containers.
- Policy Manager and Network Director containers can be stored on the same hardware device (if you are using a simple USB version of HSM).
- It is also possible to use different HSM devices (i.e., different external keystore) for Policy Manager, Network Director, and Agent containers. In this case, the key / aliases must be synced between each HSM device.
Note: This topic provides a simple use case for a Policy Manager / Network Director installation where both products are installed on the same hardware device. Policy Manager and Network Director are installed in separate containers, the External Keystore Feature is installed on each container, and are both referencing the same keystore.
Additional use cases will be published in forthcoming releases of this document. If you are using a more complex use case than the one covered here, or have questions about your particular external keystore use case requirement, contact Akana Customer Support.
Here's how it works:
- First you perform a list of prerequisite steps to configure your HSM (see Step 1: Prerequisites - HSM Device) and for the Platform (see Step 2: Prerequisites - Platform Installation).
- 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 with your own HSM, you must install and configure the External Keystore Feature prior to installing the Policy Manager Console and Policy Manager Services features and configure a series of external keystore options (Provider Name, Key Store Type, Keystore Location, and Keystore Password) to integrate your HSM with Policy Manager. You obtain the external keystore information for your HSM as part of the prerequisite steps.
- After the feature is installed, all key management tasks performed using the Manage PKI Keys Wizard for any identity will be stored in the designated external keystore.
Step 1: Prerequisites - HSM Device
HSM modules come in different forms including (i.e., plug-in card, external device attached to computer or server, networked HSM, etc.). Each module requires setup instructions that are unique to the device but generally the tasks are similar. The following list represents a list of general configuration tasks that should be completed on your HSM prior to installing the External Keystore Feature.
Note: Steps marked with * represent input required to configure the External Keystore or java.security file.
- Install Options - Represents the initial installation tasks for the HSM device or encryption engine software.
- Configure Service Ports - Configure private and non-private ports.
- Initialize Device - Generates secrets that protect operator cards and keys.
- Select FIPS Service Level - The External Keystore Feature supports FIPS Service Level II and III. See the FIPS 140-2 Wiki for more information. FIPS Support for importing external private keys: FIPS 140-2 level II allows import of external private keys. You cannot import external private keys into an HSM that is FIPS-140-2 level III compliant.
- Configure Operator Card Set - Cards that authorized personal are issued to operate the HSM device.
- Start System Services - This represents service startup tasks for the device.
- Obtain HSM Security Provider .jar file* - This file must be copied in the Policy Manager lib/ext folder as part of the security.provider configuration task (covered in Prerequisites - Platform Installation)
- Obtain HSM Provider Name* - Obtain the official "Provider Name" from the HSM vendor. This name must be supplied when configuring the External Keystore Feature.
- Obtain HSM Security Provider Name* - Obtain the official "Security Provider" name of the HSM. This name will be added to the java.security file in the Akana Platform installation directory.
- Obtain HSM Key Store Type* - Obtain the "Key Store Type" from the HSM vendor. This name must be supplied when configuring the External Keystore Feature.
Step 2: Prerequisites - Platform Installation
- Copy HSM .jar File - Copy the HSM security.provider .jar file from the java\classes directory of your HSM to the \sm70\jre\lib\extlib\ext folder of your Platform installation directory.
- Add HSM Security Provider to java.security file - Go to sm70\jre\lib\security of the Platform installation directory, load the java.security file into a text editor and add your HSM security provider. Note that provider order must be lower than SunJCE provider.
Figure. Example of adding security provider to java.security
- Launch the Configure Container Instance Wizard and define container for Policy Manager and Network Director, then follow the configuration instructions for each container (below). For more information on configuring the container, refer to the installation documentation for your version: Policy Manager Installation Guide 7.2 or Installing Policy Manager 8.x.
- Launch the Administration Console (http://<hostname:<port>/admin/).
- On the Installed Features screen, select Plug-in from the Filter menu.
- Select the External Keystore Feature and click Install Feature.
- After the installation is complete, click Close. Do not select Configure.
Step 5: Install Policy Manager Features
- On the Available Features screen, select Product Feature from the Filter menu.
- Install the Policy Manager features (Policy Manager Services and Policy Manager Console).
- When the installation is complete, click Configure. The External Keystore Options screen displays.
Step 6: Configure External Keystore Options
- On the External Keystore Options screen, specify the Provider Name and Key Store Type (you obtained as part of the HSM Device prerequisite tasks), enter a Key Store Location, and assign a Key Store Password.
- You must also set the Encyrption option.
- If Encrypted=True, Policy Manager will attach the alias, and Network Director will obtain the private key directly from external keystore using the alias provided by Policy Manager.
- If Encrypted=False, Policy Manager will attach the encrypted private key directly to WSDL. If you are using an HSM external keystore, the "Encryption" option must by checked.
- If you are using another type of encryption engine (e.g., Sun JCE) encryption can be checked or unchecked.
- After completing your entries, click Finish, then complete the remainder of the Policy Manager configuration (see Policy Manager Installation Guide 7.2 or Installing Policy Manager 8.x).
- Restart the container as prompted by the configuration.
Step 7: Verify External Keystore Installation
- After the system has restarted, verify that the PKI keys are not stored in the Database. Policy Manager only stores the alias and encrypted password for external keystore entries.
- 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.
Step 8: Assign Keys for 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), so you must generate them.
Note: This same process is performed for key management performed on service, organization, container, or user identities. Refer to Key Management for a list of Manage PKI Key Wizard options available for each identity type.
- Launch the Policy Manager Management Console and go to Security > Users. Select the Administrator user account, and click Manage PKI Keys. Select a Key Management option based on your requirements.
- If you select the Generate PKI Keys and X.509 Certificate option you can configure a new alias to assign keys. This alias will then be stored in your external keystore.
- You can also select an existing alias that is already defined in the keystore to assign the keys too on the Assign Keys from External Keystore screen. You can get to this screen by clicking Next on the Generate PKI Keys and X.509 Certificate screen without specifying a new alias.
- When you've completed your entries click Finish.
Step 9: Configure Network Director
- Launch the Administration Console (http://<hostname:<port>/admin/) for the Network Director container instance.
- On the Available Features screen, select Network Director and External Keystore features, and click Install Features.
- When the installation is complete, click Configure. The External Keystore Options screen displays.
- Specify the Provider Name and Key Store Type (you obtained as part of the HSM Device prerequisite tasks), enter a Key Store Location, and assign a Key Store Password.
If you are using one external keystore for all container instances, enter the same values 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 to learn how to reference an alias in the Network Director keystore using the Manage PKI Keys Wizard.
- Click Finish and complete the remainder of the Network Director configuration.
- Register Network Director with Policy Manager using the Add Container Wizard.
- Configure a contract, physical and virtual services, and host on Network Director.
- Send requests to Network Director and verify 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. Refer to Managing Keys for Manage PKI Key Wizard available options for each identity type.