Integrating with Entrust nShield Connect HSM
PingFederate supports multiple hardware security modules (HSMs), including Entrust nShield Connect HSM.
Steps
-
Ensure the PingFederate server has Oracle Server JRE 8 installed.
For more information, see Installing Java.
-
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.
-
After your 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>
-
To enable the Java interface, copy the
NFAST_HOME/java/classes/nCipherKM.jar
file to theJAVA_HOME/jre/lib/ext
directory.Prior to installing PingFederate, Entrust offers sample Java applications to test that the Java HSM interface works. For more information, refer to the HSM documentation from Entrust.
-
Update the
JAVA_HOME/jre/lib/security/java.security
file in your Java environment and add thenCipherKM
line to the list of security providers, after thesun
providers.# List of providers and their preference orders (see above): 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=sun.security.mscapi.SunMSCAPI security.provider.11=com.ncipher.provider.km.nCipherKM
-
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.
-
Update the
hivemodule.xml
file.-
Edit the
<pf_install>/pingfederate/server/default/conf/META-INF/hivemodule.xml
file. -
Look for the
<!-- Crypto provider -→
section. -
Update the
class
attribute value of theconstruct
element for both theJCEManager
andCertificateService
service endpoint.... <!-- Crypto provider --> <service-point id="JCEManager" interface="com.pingidentity.crypto.JCEManager"> <invoke-factory> ... <construct class="com.pingidentity.crypto.NcipherJCEManager"/> </invoke-factory> </service-point> <service-point id="CertificateService" interface="com.pingidentity.crypto.CertificateService"> <invoke-factory> ... <construct class="com.pingidentity.crypto.NcipherCertificateServiceImpl"/> </invoke-factory> </service-point> ...
-
-
Update the
<pf_install>/pingfederate/bin/run.properties
file.-
Change the value of
pf.hsm.mode
fromOFF
toNCIPHER
. -
If you are configuring a new PingFederate installation, set the value of
pf.hsm.hybrid
tofalse
to store newly created or imported certificates on your HSM. -
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.
-
-
From the
<pf_install>/pingfederate/bin
directory, run thehsmpass.bat
batch file for Windows or thehsmpass.sh
script for Linux.Enter the Operator Card Set password when prompted. See [step2].
This procedure securely stores the password for communication to the HSM from PingFederate.
-
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.
-
On the console node, go to the
<pf_install>/pingfederate/server/default/data
directory and create a sub directory namedncipher-kmdata-local
. -
Copy to the
ncipher-kmdata-local
directory all files from theNFAST_KMDATA\local
directory, whereNFAST_KMDATA
is an environment variable created during the nShield Connect installation.For example,
NFAST_KMDATA
could be set toC:\ProgramData\nCipher\Key Management Data
. -
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.
-
Restart the nShield Connect hardserver on all PingFederate servers in the cluster. For instructions on restarting the hardserver, see the HSM documentation from Entrust.
-
Sign on to the PingFederate administrative console and go to System → Server → Cluster Management.
-
To push the configuration changes, including the nShield data, to the engine nodes, click Replicate Configuration.
-
-
Start the new PingFederate server or restart the existing PingFederate server.
Whenever you restart the nShield HSM, restart PingFederate and all server nodes in a cluster.