---
title: Integrating with Entrust nShield Connect HSM
description: PingFederate supports multiple hardware security modules (HSMs), including Entrust nShield Connect HSM.
component: pingfederate
version: 13.1
page_id: pingfederate:getting_started_with_pingfederate:pf_integra_entrus_nshield_connec_hsm
canonical_url: https://docs.pingidentity.com/pingfederate/13.1/getting_started_with_pingfederate/pf_integra_entrus_nshield_connec_hsm.html
llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: January 12, 2024
section_ids:
  steps: Steps
---

# Integrating with Entrust nShield Connect HSM

PingFederate supports multiple hardware security modules (HSMs), including Entrust nShield Connect HSM.

## Steps

1. Ensure the PingFederate server has a supported Java virtual machine (JVM) installed.

   For more information, see [Installing Java](../installing_and_uninstalling_pingfederate/pf_install_java.html).

2. Install and configure your Entrust nShield Connect HSM client software.

   As part of the installation, install the optional Java Support (including KeySafe) and nCipherKM JCA/JCE provider classes components.

3. After installation, see the HSM documentation from Entrust to make your PingFederate server a client of an HSM server.

   |   |                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
   | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | PingFederate supports both Operator Card Set (OCS) protected keys and module-protected keys.For OCS, note the password. You need the password for your installation of PingFederate.For module-protected keys, edit the `pingfederate/server/default/data/config-store/com.pingidentity.crypto.NCipherSettings.xml` file to add the following entries:```
   <con:item name="protect">module</con:item>
   <con:item name="ignorePassphrase">true</con:item>
   ``` |

4. To enable the Java interface, copy the `NFAST_HOME/java/classes/nCipherKM.jar` file to the `<pf_install>/pingfederate/startup` directory.

5. If you're upgrading from PingFederate 11.1 or earlier, revert any previous changes to the `JAVA_HOME/jre/lib/security/java.security` file and remove the `nCipherKM.jar` file previously copied to `JAVA_HOME/jre/lib/ext`.

6. Set up a new PingFederate installation on the network interconnected to the HSM.

   |   |                                                                                         |
   | - | --------------------------------------------------------------------------------------- |
   |   | Skip to the next step to integrate an existing PingFederate installation with your HSM. |

7. Edit the `<pf_install>/pingfederate/server/default/conf/service-points.conf` file.

   1. Go to the `# Crypto provider services` section.

   2. Change the `jce.manager` and `certificate.service` service endpoints to the following:

      ```
      ...
      jce.manager=com.pingidentity.crypto.NcipherJCEManager
      ...
      certificate.service=com.pingidentity.crypto.NcipherCertificateServiceImpl
      ...
      ```

      |   |                                                                                                                                                                                    |
      | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      |   | In clustered PingFederate environments, you must manually edit the `service-points.conf` file on each node because cluster replication can't replicate this change to other nodes. |

8. Update the `<pf_install>/pingfederate/bin/run.properties` file.

   1. Change the value of `pf.hsm.mode` from `OFF` to `NCIPHER`.

   2. If you are configuring a new PingFederate installation, set the value of `pf.hsm.hybrid` to `false` to store newly created or imported certificates on your HSM.

   3. If you are configuring an existing PingFederate installation, set the value to `true`, which provides the flexibility to store each relevant key and certificate on the HSM or the local trust store. This capability allows you to transition the storage of keys and certificates to your HSM without the need to deploy a new PingFederate environment and to mirror the setup. For more information, see [Transitioning to an HSM](../administrators_reference_guide/pf_transition_to_hsm.html).

9. From the `<pf_install>/pingfederate/bin` directory, run the `hsmpass.bat` batch file for Windows or the `hsmpass.sh` script for Linux.

   Enter the Operator Card Set password when prompted. See [\[step2\]](#step2).

   This procedure securely stores the password for communication to the HSM from PingFederate.

10. If you're not using the default slot for OCS protection, specify the slot in `<pf_install>/pingfederate/server/default/data/config-store/com.pingidentity.crypto.NCipherSettings.xml`.

11. If you are setting up a new or configuring an existing PingFederate cluster, repeat these steps on each node.

    When finished, use the following steps to replicate nShield data to the connected nodes in the cluster.

    1. On the console node, go to the `<pf_install>/pingfederate/server/default/data` directory and create a sub directory named `ncipher-kmdata-local`.

    2. Copy to the `ncipher-kmdata-local` directory all files from the `NFAST_KMDATA\local` directory, where `NFAST_KMDATA` is an environment variable created during the nShield Connect installation.

    For example, `NFAST_KMDATA` could be set to `C:\ProgramData\nCipher\Key Management Data`.

    1. Create a new environment variable named `NFAST_KMLOCAL` and set it to `<pf_install>/pingfederate/server/default/data/ncipher-kmdata-local`.

       |   |                                                                              |
       | - | ---------------------------------------------------------------------------- |
       |   | You must define this environment variable on all servers within the cluster. |

    2. Restart the nShield Connect hardserver on all PingFederate servers in the cluster. For instructions on restarting the hardserver, see the HSM documentation from Entrust.

    3. Sign on to the PingFederate administrative console and go to **System > Server > Cluster Management**.

    4. To push the configuration changes, including the nShield data, to the engine nodes, click **Replicate Configuration**.

12. Start the new PingFederate server or restart the existing PingFederate server.