Configuring Identity Server for netHSM

1. At Identity Server, log in as the root or administrator user and install the netHSM client.

   The nCipher software installs files in the /opt/nfast directory. It creates an nfast user and group. Check your netHSM documentation for the specific steps.

2. (Conditional) If your Identity Server cluster configuration contains more than one Identity Server, install the netHSM client software on other Identity Servers in the cluster.

3. At the netHSM server, configure the server to allow Identity Server to be a client.

   Check your netHSM documentation for the specific steps.

4. (Conditional) If your Identity Server cluster configuration contains more than one Identity Server, configure the netHSM server to allow the other Identity Servers in the cluster to be a client.

5. At Identity Server, enroll the client to use the server:

   1. To get the ESN and hash numbers for the enroll command, enter the following command:

      /opt/nfast/bin/anonkneti <IP_address>

      Replace <IP_address> with the IP address of the netHSM server.

   2. To enroll the client, enter the following command:

      /opt/nfast/bin/nethsmenroll -p <IP_address> <ESN> <hash>

      Replace <IP_address> with the IP address of the netHSM server. Replace <ESN> and <hash> with the values copied from the anonkneti command.

6. (Conditional) If Identity Server and Administration Console are installed on the same machine, modify TCP ports 9000 and 9001:

   1. Modify the sc.conf file.

      For information about how to modify a file, see Modifying Configurations.

   2. Change the ports from 9000 and 9001 to another value, such as 9010 and 9011 as follows:

      <stringParam name="ExecutorPort" value="9010" />
      <stringParam name="SchedulerPort" value="9011" />

7. At Identity Server, enable the netHSM client so that it uses TCP:

   1. Run the following command:

      /opt/nfast/bin/config-serverstartup -sp

   2. To restart the nfast client, run the following command:

      /opt/nfast/sbin/init.d-nfast restart

8. Configure communication to the remote file system server. In this sample configuration, the remote file system is installed on a Windows machine.

   1. At the remote file system server, enable communication with Identity Server. For a Windows machine, enter the following command:

      C:\nfast\bin\rfs-setup.exe --gang-client --write-noauth <address>

      Replace <address> with the IP address of Identity Server.

   2. At Identity Server, enable communication with the remote file system server. For nCipher, enter the following command:

      /opt/nfast/bin/rfs-sync --setup --no-authenticate <address>

      Replace <address> with the IP address of the remote file system server.

   3. At Identity Server, run the following commands to initialize synchronization with the remote file system server.

      /opt/nfast/bin/rfs-sync –-update

      /opt/nfast/bin/rfs-sync –-commit

      The first command reads updates from the remote file system server and downloads files to the /opt/nfast/kmdata/local directory. The second command writes local changes to the remote file system server.

9. Continue with Creating the nCipher Signing Key Pair.

To create a new key pair for nCipher:

1. On a netHSM client, add the nCipher provider to the provider list of the java.security file:

   1. In a text editor, open the C:\Program Files\Java\<jdk version>\jre\lib\ security\java.security file.

   2. Add the following lines to the top of the list of providers:

      security.provider.1=com.ncipher.fixup.provider.nCipherRSAPrivateEncrypt
      security.provider.2=com.ncipher.provider.km.nCipherKM

      The provider section should look similar to the following:

      # 
      # List of providers and their preference orders (see above):
      # 
      security.provider.1=com.ncipher.fixup.provider.nCipherRSAPrivateEncrypt 
      security.provider.2=com.ncipher.provider.km.nCipherKM 
      security.provider.3=sun.security.provider.Sun 
      security.provider.4=sun.security.rsa.SunRsaSign 
      security.provider.5=com.sun.net.ssl.internal.ssl.Provider 
      security.provider.6=com.sun.crypto.provider.SunJCE 
      security.provider.7=sun.security.jgss.SunProvider 
      security.provider.8=com.sun.security.sasl.Provider 

   3. Save your changes.

2. Add the nfast libraries to the CLASSPATH for Java:

   For a Windows client, add the following paths:

   c:\nfast\java\classes\keysafe.jar;c:\nfast\java\classes\nfjava.jar
   ;c:\nfast\java\classes\kmjava.jar;c:\nfast\java\classes\kmcsp.jar;
   c:\nfast\java\classes\jutils.jar;c:\nfast\java\classes\jcetools.
   jar;c:\nfast\java\classes\spp.jar;c:\nfast\java\classes\rsaprivenc
   .jar;

   For a Linux client, add the following paths and export them:

   /opt/nfast/java/classes/nfjava.jar:/opt/nfast/java/classes/
   kmjava.jar:/opt/nfast/java/classes/kmcsp.jar:/opt/nfast/java/
   classes/spp.jar:/opt/nfast/java/classes/rsaprivenc.jar:/opt/nfast/
   java/classes/jutils.jar:/opt/nfast/java/classes/jcetools.jar:/opt/
   nfast/java/classes/keysafe.jar

3. Create a directory for the keystore and change to that directory.

4. On a Windows client, run the following command to create a new key in a keystore:

   "c:\Program Files\Java\<jdk version>\jre\bin\java" -Dprotect=module 
   -DignorePassphrase=true sun.security.tools.KeyTool -genkey -v 
   -alias od93 -keyalg RSA -keystore AMstore.jks -storetype 
   nCipher.sworld -provider com.ncipher.provider.km.nCipherKM

   Specify the values for the following parameters:

   Parameter	Description
   -Dprotect=module	Required if you want the keystore to be module protected.
   -DignorePassphrase=true	Required if you want the keystore to be module protected.
   sun.security.tools.KeyTool	The name of the keytool command
   -alias	A name that helps you identify the key. In this sample configuration, the name is od93.
   -keyalg	The security algorithm.
   -keystore	A name for the keystore. In this sample configuration, the name is AMstore.jks.
   -storetype	The type of keystore. For nCipher, this must be set to nCipher.sworld.
   -provider	The name of the providerClass and providerName. This is the provider that you added to java.security in Step 1.

   The tool prompts you for a password for the keypass and the storepass. They must be the same password if you are going to use card set protection rather than module protection.

   The tool also prompts you for the certificate subject name (first name, last name, organization, organizational unit, locality, state or providence, and country).

5. To generate a certificate request from a key in the keystore, enter the following command:

   "c:\Program Files\Java\<jdk version>\jre\bin\java" -Dprotect=module
   -DignorePassphrase=true sun.security.tools.KeyTool -certreq -alias
   od93 -file cert.csr -keypass mypwd -keystore AMstore.jks -storepass 
   mypwd -storetype nCipher.sworld -provider 
   com.ncipher.provider.km.nCipherKM

   Specify values for the following parameters:

   Parameter	Description
   -Dprotect=module	Required if you want the keystore to be module protected.
   -DignorePassphrase=true	Required if you want the keystore to be module protected.
   sun.security.tools.KeyTool	The name of the keytool command
   -certreq	The parameter that makes this a certificate request.
   -alias	A name that helps you identify the certificate request. In this sample configuration, the name is od93.
   -file	The name to be given to the certificate signing request file. In this sample configuration, the name is cert.csr.
   -keypass	The password for the key. In this sample configuration, the password is mypwd.
   -keystore	A name for the keystore. In this sample configuration, the name is AMstore.jks.
   -storepass	The password for the keystore. In this sample configuration, the password is mypwd.
   -storetype	The type of keystore. For nCipher, this must be set to nCipher.sworld.
   -provider	The name of the providerClass and providerName.

6. Take the CSR created in Step 5 to a certificate authority. The CA needs to send you a DER-encoded public certificate. The CA also needs to send you the public certificate that it used to create the certificate and the public certificates for any CAs in the chain.

7. Load the public certificate of the CA into the keystore by entering the following command:

   "c:\Program Files\Java\<jdk version>\jre\bin\java" -Dprotect=module
   -DignorePassphrase=true sun.security.tools.KeyTool -import -alias 
   publicca –file certca.cer -keystore Amstore.jks -storetype 
   nCipher.sworld -provider com.ncipher.provider.km.nCipherKM

   Specify values for the following parameters:

   Parameter	Description
   -Dprotect=module	Required if you want the keystore to be module protected.
   -DignorePassphrase=true	Required if you want the keystore to be module protected.
   sun.security.tools.KeyTool	The name of the keytool command
   -import	The parameter that makes this an import request.
   -alias	A name that helps you identify that this is the public certificate from the CA. In this sample, the name is publicca.
   -file	The name of the CA certificate file. In this sample configuration, the name is certca.cer.
   -keystore	A name for the keystore. In this sample configuration, the name is AMstore.jks.
   -storetype	The type of keystore. For nCipher, this must be set to nCipher.sworld.
   -provider	The name of the providerClass and providerName.

   The tool prompts you for the keystore password and asks whether you want to trust the certificate.

8. (Conditional) Repeat Step 7 for each CA in the chain, giving each CA a unique alias.

9. Import the signed certificated received from the CA by entering the following command:

   "c:\Program Files\Java\<jdk version>\jre\bin\java" -Dprotect=module 
   -DignorePassphrase=true sun.security.tools.KeyTool -import -alias 
   od93 –file signcert.der -keystore AMstore.jks -storepass mypwd 
   -storetype nCipher.sworld -provider 
   com.ncipher.provider.km.nCipherKM

   Specify values for the following parameters:

   Parameter	Description
   -Dprotect=module	Required if you want the keystore to be module protected.
   -DignorePassphrase=true	Required if you want the keystore to be module protected.
   sun.security.tools.KeyTool	The name of the keytool command
   -import	The parameter that makes this an import request.
   -alias	A name that helps you identify that this is the signing key pair from the CA. It needs to be the same alias you specified when you created the keystore in Step 4. In this sample configuration, the name is od93.
   -file	The name of the signing certificate file from the CA. In this sample configuration, the name is signcert.der.
   -keystore	A name for the keystore. In this sample configuration, the name is AMstore.jks.
   -storepass	The password for the keystore. In this sample configuration, the password is mypwd.
   -storetype	The type of keystore. For nCipher, this must be set to nCipher.sworld.
   -provider	The name of the providerClass and providerName.

10. (Optional) To verify that the certificates have been added to the keystore, run the following command:

    "c:\Program Files\Java\<jdk version>\jre\bin\java" -Dprotect=module 
    -DignorePassphrase=true sun.security.tools.KeyTool -list -v 
    -keystore AMstore.jks -storetype nCipher.sworld -provider 
    com.ncipher.provider.km.nCipherKM

    The keystore should contain at least two certificates. The certificate that you created should now be issued by the CA you used, and the public certificate of the CA should be there as the owner and the issuer.

11. Copy the keystore to the idp directory on Identity Server.

    /opt/novell/devman/jcc/certs/idp

    The keystore is found on the netHSM client in the directory specified by the -keystore parameter when you created the keystore. See Step 4.

12. Run the following commands to synchronize Identity Server with the remote file system server.

    /opt/nfast/bin/rfs-sync –-update

    /opt/nfast/bin/rfs-sync –-commit

13. (Conditional) If the cluster configuration contains more than one Identity Server, complete the following steps for each cluster member:

    1. Copy the keystore to the cluster member. Copy it to the following directory:

       /opt/novell/devman/jcc/certs/idp

    2. Ensure that the novlwww user has at least read rights.

    3. Use the netHSM client to synchronize the cluster member with the remote file system server.

       Linux: Enter the following commands:

       /opt/nfast/bin/rfs-sync –-update

       /opt/nfast/bin/rfs-sync –-commit

14. Continue with Configuring Identity Server to Use the netHSM Certificate.

1. Add the nfast jar files to the classpath.

   1. In the dtomcat9 file, modify the classpath for Tomcat as Identity Server runs as a Tomcat service. For information about how to modify a file, see Modifying Configurations.

   2. To the CLASSPATH="$JAVA_HOME"/lib/tools.jar line, add the following classes from the /opt/nfast/java/classes directory:

      nfjava.jar
      kmjava.jar
      kmcsp.jar
      spp.jar
      rsaprivenc.jar
      jutils.jar:
      jcetools.jar
      keysafe.jar

      Your line should look similar to the following:

      CLASSPATH="$JAVA_HOME"/lib/tools.jar:/opt/nfast/java/classes/
      nfjava.jar:/opt/nfast/java/classes/kmjava.jar:/opt/nfast/java/
      classes/kmcsp.jar:/opt/nfast/java/classes/spp.jar:/opt/nfast/
      java/classes/rsaprivenc.jar:/opt/nfast/java/classes/
      jutils.jar:/opt/nfast/java/classes/jcetools.jar:/opt/nfast/
      java/classes/keysafe.jar

2. Add the novlwww user to the nfast group by running the usermod novlwww -G nfast command.

3. Add the following netHSM certificate configuration lines to Identity Server’s tomcat.conf file:

   For information about how to modify a file, see Modifying Configurations.

   JAVA_OPTS="${JAVA_OPTS} -Dcom.novell.nidp.extern.config.file=
   /opt/novell/nids/lib/webapp/WEB-INF/classes
   externKeystore.properties"
   
   JAVA_OPTS="${JAVA_OPTS} -Dprotect=module 
   -DignorePassphrase=true"

   The first line specifies the location of the properties file. You can specify another location.

   The second line is required only if you want the keystore to be module protected rather than card protected.

4. Modify the externKeystore.properties file to use the nCipher key and keystore:

   For information about how to modify a file, see Modifying Configurations.

   1. Add the following lines:

      com.novell.nidp.extern.signing.providerClass=com.ncipher.provider.km.nCipherKM
      com.novell.nidp.extern.signing.providerName=nCipherKM
      com.novell.nidp.extern.signing.keystoreType=nCipher.sworld
      com.novell.nidp.extern.signing.keystoreName=/opt/novell/devman/jcc/certs/idp/AMstore.jks
      com.novell.nidp.extern.signing.keystorePwd=mypwd
      com.novell.nidp.extern.signing.alias=od93
      com.novell.nidp.extern.signing.keyPwd=mypwd

      Specify values for the following variables:

      Variable	Value
      <provider_class>	The name of the providerClass. For nCipher, this must be set to com.ncipher.provider.km.nCipherKM.
      <provider_name>	The name of the provider. For nCipher, this must be set to nCipherKM.
      <keystore_type>	The type of keystore. For nCipher, this must be set to nCipher.sworld.
      <keystore_name>	The name you specified when you created the keystore. In this sample configuration, the name is AMstore.jks.
      <keystore_pwd>	When you use module-protected keys, the keystore password must be null. For example: com.novell.nidp.extern.signing.keystorePwd=
      <key_alias>	The alias you created for the key when you created the key. In this sample configuration, the name is od93.
      <key_pwd>	When you use module-protected keys, the key password must be null. For example: com.novell.nidp.extern.signing.keyPwd=

5. Continue with Verifying the Use of the nCipher Key Pair.

1. In a browser, enter the following URL:

   http://<DNS_name>:8080/nidp/idff/metadata

   Replace <DNS_name> with the DNS name of your Identity Server.

2. Search for the following string:

   <md:KeyDescriptor use="signing">

3. Copy the certificate text between the <ds:X509Certificate> and the </ds:X509Certificate> tags

4. Paste the text into a text editor.

5. Delete the <ds:X509Certificate> tag and replace it with the following text:

   -----BEGIN CERTIFICATE-----

6. Delete the </ds:X509Certificate> tag and replace it with the following text:

   -----END CERTIFICATE-----

7. Save the file as a text file with a .cer extension.

8. Open the file in Internet Explorer.

9. View the certificate details.

   If Identity Server is using the nCipher signing certificate, the certificate is issued by your CA and the name the certificate is issued to is the name you specified for the certificate.

   If Identity Server is using the Access Manager certificate, the certificate is issued by the Organizational CA and the certificate name is test-signing. For troubleshooting information, see Troubleshooting the netHSM Configuration.

1. Verify that you have not enabled the data encryption of resource IDs. A known issue exists with this feature and Apache libraries in a multi-provider environment. Because of this issue, netHSM is not compatible with encrypting the resource IDs.

   1. Click Devices > Identity Servers > Edit > Liberty > Web Service Provider.

   2. Click a profile, then select the setting for Have Discovery Encrypt This Service’s Resource Ids.

   3. If the option is selected, deselect it, then click OK.

   4. Verify that all profiles have been configured so that they do not encrypt the resource IDs.

2. View the nfast log files: /opt/nfast/log

   When there is a port conflict, logfile contains entries similar to the following:

   nFast server: Notice: Using tcp socket local:9000
   nFast server: Fatal error during startup: Operating system call failed: bind tcp socket, Address already in use 

   For information about how to change the port, see Step 6. For other errors, consult the netHSM documentation.

3. If the novlwww user does not have rights to the cmdadp.log and cmdadp-debug.log files, Identity Server is halted because it cannot read the keystore. The Health page of Identity Server displays the following error:

   The following error occurred during Identity Server configuration. Unable to read keystore: /opt/novell/devman/jcc/certs/idp/AMstore45.jks

   To correct the error:

   1. View the rights for the nfast log files with the following command:

      ll /opt/nfast/log

      Your listing should look similar to the following:

      -rw-r--r-- 1 novlwww nfast    0 Apr 11 11:50 cmdadp-debug.log
      -rw-r--r-- 1 novlwww nfast  134 Apr 11 11:50 cmdadp.log
      -rw-r----- 1 root    nfast   43 Apr 11 11:49 debug
      -rw-r----- 1 nfast   nfast    5 Apr 11 11:49 hardserver.pid
      -rw-r----- 1 nfast   nfast 3057 Apr 11 11:50 logfile

      If novlwww is not listed as the owner of the cmdadp.log and cmdadp-debug.log files, continue with Step 3.b.

      If novlwww is listed as the owner of the files with rw permissions, log file ownership is not the source of your problem. Continue with Step 4.

   2. Stop Tomcat with one of the following commands:

      /etc/init.d/novell-idp stop

      systemctl stop novell-ac.service

      For the Docker deployment, perform the following steps:

      1. Run the kubectl get pods command to view the Access Manager pods.

      2. Go to the Identity Server pod by running the kubectl exec --namespace <name-of-the-namespace> -it pod/<name-of-the-identity-server-pod> -- sh command.

      3. Run the /etc/init.d/novell-idp stop orsystemctl stop novell-idp.service command.

   3. Stop nfast with the following command:

      /opt/nfast/sbin/init.d-nfast stop

   4. Delete all the log files in the /opt/nfast/log directory.

   5. Start nfast with the following command:

      /opt/nfast/sbin/init.d-nfast start

   6. Start Tomcat with one of the following commands:

      /etc/init.d/novell-idp start

      systemctl start novell-idp.service

      For the Docker deployment, perform the following steps:

      1. Run the kubectl get pods command to view the Access Manager pods.

      2. Go to the Identity Server pod by running the kubectl exec --namespace <name-of-the-namespace> -it pod/<name-of-the-identity-server-pod> -- sh command.

      3. Run the /etc/init.d/novell-idp start or systemctl start novell-idp.service command.

   7. Wait a minute, then list the files in the /opt/nfast/log directory.

      The nfast client creates the log files and assigns the correct owners and rights.

4. Enable Identity Server logging and view the catalina.out file.

   1. Click Devices > Identity Servers > Edit > Logging.

   2. Configure the following options:

      File Logging: Specify enabled.

      Echo to Console: Select this option.

      Component File Logger Levels: Set Application to debug.

   3. Click OK, then update Identity Server.

   4. Delete the current catalina.out file in /var/opt/novell/nam/logs/idp/tomcat.

   5. Restart Tomcat by entering one the following commands:

      /etc/init.d/novell-idp restart

      systemctl restart novell-idp.service

      For the Docker deployment, perform the following steps:

      1. Run the kubectl get pods command to view the Access Manager pods.

      2. Go to the Identity Server pod by running the kubectl exec --namespace <name-of-the-namespace> -it pod/<name-of-the-identity-server-pod> -- sh command.

      3. Run the /etc/init.d/novell-idp restart or systemctl restart novell-idp.service command.

   6. To tail the catalina.out file, run the tail -f /var/opt/novell/nam/logs/idp/tomcat/catalina.out command.

   7. Search for a list of providers. When nCipher is working, the file contains entries similar to the following nCipher entries:

      Security Providers: 
           SUN: 1.42 
              SUN (DSA key/parameter generation; DSA signing; SHA-2, MD5 digests; SecureRandom; X.509 certificates; JKS keystore; PKIX CertPathValidator; PKIX CertPathBuilder; LDAP, Collection CertStores)
           SunJSSE: 1.42
              Sun JSSE provider(implements RSA Signatures, PKCS12, SunX509 key/trust factories, SSLv3, TLSv1)
           SunRsaSign: 1.42
              SUN's provider for RSA signatures
           SunJCE: 1.42
              SunJCE Provider (implements DES, Triple DES, AES, Blowfish, PBE, Diffie-Hellman, HMAC-MD5, HMAC-SHA1)
           SunJGSS: 1.0
              Sun (Kerberos v5)
           nCipherRSAPrivateEncrypt: 1.008004
              RSA private key encrypt handling provider
           nCipherKM: 1.008004
              nCipher Secure Key Management
           BC: 1.28
              BouncyCastle Security Provider v1.28
           SAML: 1.0
              SAML SASL Mechanism 

   8. (Conditional) If the catalina.out file does not contain any entries for providers, check for the following errors:

      • Check the Health of Identity Server. If the status is red, use the error message to resolve the issue.

      • Ensure that the novlwww user has read rights to the keystore.

      • Verify that the externKeystore.properties file has all required lines with valid values. See Step 4.

      • Verify that the tomcat7.conf file is configured correctly. See Step 3.

5. Enable netHSM logging.

   This logging feature is very verbose. It should be turned on only while you are debugging a problem. If it is left on, your machine can quickly run out of disk space.

   1. Add the following lines in tomcat.conf:

      For information about how to modify a file, see Modifying Configurations.

      JAVA_OPTS="${JAVA_OPTS} -DJCECSP_DEBUG=255 -DJCECSP_DEBUGFILE=/opt/novell/nam/idp/logs/nCipher_jcecsp.debug"

   2. Look for clues in the nCipher_jcecsp.debug file.