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

   The nCipher software installs files in the /opt/nfast directory on Linux and in the C:\nfast directory on Windows. 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 the other Identity Servers in the cluster.

3. At the netHSM server, configure the server to allow the 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 the 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:

      Linux: /opt/nfast/bin/anonkneti <IP_address>

      Windows: C:\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:

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

      Windows: C:\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 the Identity Server and the Administration Console are installed on the same machine, modify the 9000 and 9001 TCP ports:

   1. In a text editor, open the sc.conf file located in the following directory:

      Linux: /opt/novell/devman/share/conf

      Windows Server 2003: \Program Files\Novell\Tomcat\webapps\roma\WEB-INF\conf

      Windows Server 2008: \Program Files (x86)\Novell\Tomcat\webapps\roma\ WEB-INF\conf

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

      The lines should look similar to the following:

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

   3. Save the changes.

   4. Restart Tomcat:

      Linux: Enter the following command:

      /etc/init.d/novell-tomcat5 restart

      Windows: Enter the following commands:

      net stop Tomcat5

      net start Tomcat5

   5. (Conditional) If other Identity Servers in the cluster contain an Administration Console, repeat Step 6.

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

   1. Enter the following command:

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

      Windows: C:\nfast\bin>config-serverstartup -sp

   2. To restart the nfast client:

      Linux: Enter the following command:

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

      Windows: Enter the following commands:

      C:\nfast\bin>net stop "nfast server"

      C:\nfast\bin>net start "nfast server"

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 the 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 the Identity Server.

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

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

      Windows: C:\nfast\bin>rfs-sync --setup --no-authenticate <address>

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

   3. At the Identity Server, initialize synchronization with the remote file system server.

      Linux: Enter the following commands:

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

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

      Windows: Enter the following commands:

      C:\nfast\bin>rfs-sync --update

      C:\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 on Linux and the C:\nfast\kmdata\local directory on Windows. 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\jdk1.5.0_14\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, enter the following command to create a new key in a keystore:

   "c:\Program Files\Java\jdk1.5.0_14\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
   

   Enter your 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 the java.security file 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\jdk1.5.0_14\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
   

   Enter your 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\jdk1.5.0_14\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
   

   Enter your 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 configuration, 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\jdk1.5.0_14\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
   

   Enter your 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, enter the following command:

    "c:\Program Files\Java\jdk1.5.0_14\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 the Identity Server.

    Linux: /opt/novell/devman/jcc/certs/idp

    Windows Server 2003: \Program Files\Novell\devman\jcc\certs\idp

    Windows Server 2008: \Program Files (x86)\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. Synchronize the Identity Server with the remote file system server.

    Linux: Enter the following commands:

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

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

    Windows: Enter the following commands:

    C:\nfast\bin>rfs-sync --update

    C:\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:

       Linux: /opt/novell/devman/jcc/certs/idp

       Windows Server 2003: \Program Files\Novell\devman\jcc\certs\idp

       Windows Server 2008: \Program Files (x86)\Novell\devman\jcc\certs\idp

    2. Make sure 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

       Windows: Enter the following commands:

       C:\nfast\bin>rfs-sync --update

       C:\nfast\bin>rfs-sync --commit

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

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 the 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 the 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. There is a known issue with this feature and the Apache libraries in a multi-provider environment. Because of this issue, netHSM is not compatible with encrypting the resource IDs.

   1. In the Administration Console, click Devices > Identity Servers > Edit > Liberty > Web Service Provider.

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

   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:

   Linux: /opt/nfast/log

   Windows: C:\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 on how to change the port, see Step 6. For other errors, consult the netHSM documentation.

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

   The following error occurred during the 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 the following command:

      /etc/init.d/novell-tomcat5 stop
      

   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 the following command

      /etc/init.d/novell-tomcat5 start
      

   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. In the Administration Console, 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 the Identity Server.

   4. Delete the current catalina.out file in the /var/opt/novell/tomcat5/logs directory.

   5. Restart Tomcat by entering the following command:

      /etc/init.d/novell-tomcat5 restart
      

   6. To tail the catalina.out file, enter the following command:

      tail -f /var/opt/novell/tomcat5/logs/catalina.out 
      

   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-1, 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 the Identity Server. If the status is red, use the error message to resolve the issue.

      • Make sure the novlwww user has read rights to the keystore.

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

      • Verify that the tomcat5.conf file is configured correctly. See Step 4.

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. To the tomcat5.conf file in the /var/opt/novell/tomcat5/conf directory, add the following line:

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

   2. Restart Tomcat by entering the following command:

      /etc/init.d/novell-tomcat5 restart
      

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