Installing the nCipherKM JCA/JCE CSP

Prerequisites

To use the nCipherKM JCA/JCE CSP, you must install the nShield Java package which includes the nShield Java jars and Keysafe.

For more information about the bundles and components supplied on your Security World Software installation media, see Software packages on the installation media.

The following versions of Java have been tested to work with, and are supported by, your nShield Security World Software:

Java 8 (or Java 1.8x)
Java 11
Java 17

We recommend that you ensure Java is installed before you install the Security World Software. The Java executable must be on your system path.

If you can do so, please use the latest Java version currently supported by Entrust that is compatible with your requirements. Java versions before those shown are no longer supported. If you are maintaining older Java versions for legacy reasons, and need compatibility with current nShield software, please contact Entrust nShield Support: https://nshieldsupport.entrust.com.

To install Java you may need installation packages specific to your operating system, which may depend on other pre-installed packages to be able to work.

Suggested links from which you may download Java software as appropriate for your operating system:

Detailed documentation for the JCE interface can be found on the Oracle Technology web page here.

Softcards are not supported for use with the nCipherKM JCA/JCE CSP in Security Worlds that are compliant with FIPS 140 Level 3.

Installing the nCipherKM JCA/JCE CSP

To install the nCipherKM JCA/JCE CSP:

In the hardserver configuration file, ensure that:
- priv_port (the port on which the hardserver listens for local privileged TCP connections) is set to 9001.
- nonpriv_port (the port on which the hardserver listens for local nonprivileged TCP connections) is set to 9000.
  
  If you need to change either or both of these port settings, restart the hardserver before continuing the nCipherKM JCA/JCE CSP installation process. For more information, see Client software and module configuration: network-attached HSMs or Client software and module configuration: PCIe and USB HSMs.

For Java 8 only. Copy the nCipherKM.jar file to the extensions folder of your local Java Virtual Machine installation from the following directory:

%NFAST_HOME%\java\classes (Windows)
/opt/nfast/java/classes (Linux)

The location of the extensions folder depends on the type of your local Java Virtual Machine (JVM) installation:

JVM type Extensions folder (Windows) Extensions folder (Linux)

JVM type	Extensions folder (Windows)	Extensions folder (Linux)
Java Developer Kit (JDK)	`%JAVA_HOME%\jre\lib\ext`	`$JAVA_HOME/jre/lib/ext`
Java Runtime Environment (JRE)	`%JAVA_HOME%\lib\ext`	`$JAVA_HOME_/lib/ext`

Java Developer Kit (JDK)

%JAVA_HOME%\jre\lib\ext

$JAVA_HOME/jre/lib/ext

Java Runtime Environment (JRE)

%JAVA_HOME%\lib\ext

$JAVA_HOME_/lib/ext

In these paths, %JAVA_HOME% (Windows) and $JAVA_HOME (Linux) are the home directory of the Java installation (commonly specified in the JAVA_HOME environment variable).

If you are using Java 11 or Java 17 you do not need to copy the jar file.

Add %JAVA_HOME%\bin (Windows) or $JAVA_HOME/bin (Linux) to your PATH system variable.

For Java 8 only. Install the unlimited strength JCE jurisdiction policy files that are appropriate to your version of Java. JDK 9 and later ship with, and use by default, the unlimited policy files.

The Java Virtual Machine imposes limits on the cryptographic strength that may be used by default with JCE providers. Replace the default policy configuration files with unlimited strength policy files.

To install the unlimited strength JCE jurisdiction policy files:

If necessary, download the archive containing the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from your Java Virtual Machine vendor’s Web site. Be sure to download a file appropriate for your version of Java.

The Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files are covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. We recommend that you take legal advice before downloading these files from your Java Virtual Machine vendor.

Extract the files local_policy.jar and US_export_policy.jar from Java Virtual Machine vendor’s Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy File archive.

Copy the extracted files local_policy.jar and US_export_policy.jar into the security directory for your local Java Virtual Machine (JVM) installation:

JVM type Extensions folder (Windows) Extensions folder (Linux)

JVM type	Extensions folder (Windows)	Extensions folder (Linux)
Java Developer Kit (JDK)	`%JAVA_HOME%\jre\lib\security`	`$JAVA_HOME/jre/lib/security`
Java Runtime Environment (JRE)	`%JAVA_HOME%\lib\security`	`$JAVA_HOME_/lib/security`

Java Developer Kit (JDK)

%JAVA_HOME%\jre\lib\security

$JAVA_HOME/jre/lib/security

Java Runtime Environment (JRE)

%JAVA_HOME%\lib\security

$JAVA_HOME_/lib/security

In these paths, %JAVA_HOME% (Windows) and $JAVA_HOME (Linux) are the home directory of the Java installation (commonly specified in the JAVA_HOME environment variable).

Copying the files local_policy.jar and US_export_policy.jar into the appropriate folder must overwrite any existing files with the same names.

Add the nCipherKM provider to the java.security file located in the security directory for your local Java Virtual Machine (JVM) installation: security.provider.<n>=com.ncipher.provider.km.nCipherKM, where <n> is the position in the list of providers, for example:

security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
security.provider.6=com.sun.security.sasl.Provider
security.provider.7=com.ncipher.provider.km.nCipherKM

For Java 11 and Java 17 you do not need to specify the fully qualified class name for the provider. Instead you can just use the provider name: security.provider.<n>=nCipherKM.

The JVM uses this file to select the provider from which to request a mechanism instance. If your JCE application does not request the nCipherKM provider by name, or if it fails to load keys, you might need to move the nCipherKM provider to the top of the list: security.provider.1=com.ncipher.provider.km.nCipherKM. Do not change the relative order of the other providers in the list.

Ensure you do not list multiple providers with the same number (for example, ensure your list of providers does not include two instances of security.provider.1, both com.ncipher.provider.km.nCipherKM and another provider). If you add the nCipherKM provider as security.provider.1, ensure that the subsequent providers are re-numbered correctly.

Save your updates to the file java.security.

When you have installed the nCipherKM JCA/JCE CSP, you must have created a Security World before you can test or use it. For more information about creating a Security World, see Create a new Security World.

If you have a Java Enterprise Edition Application Server running, you must restart it before the installed nCipherKM provider is loaded into the Application Server virtual machine and ready for use.

Testing the nCipherKM JCA/JCE CSP installation

After installation, you can test that the nCipherKM JCA/JCE CSP is functioning correctly by running the command.

For Java 8:

java com.ncipher.provider.InstallationTest

For Java 11 and Java 17 (Windows):

java --module-path %NFAST_HOME%\java\classes com.ncipher.provider.InstallationTest

For Java 11 and Java 17 (Linux):

java --module-path /opt/nfast/java/classes com.ncipher.provider.InstallationTest

For these commands to work, you must have added %JAVA_HOME% (Windows) or $JAVA_HOME (Linux) to your PATH system variable.

If the nCipherKM JCA/JCE CSP is functioning correctly, output from this command has the following form:

Installed providers:
1: nCipherKM
2: SUN
3: SunRsaSign
4: SunJSSE
5: SunJCE
6: SunJGSS
7: SunSASL
Unlimited strength jurisdiction files are installed.
The nCipher provider is correctly installed.
nCipher JCE services:
Alg.Alias.Cipher.1.2.840.113549.1.1.1
Alg.Alias.Cipher.1.2.840.113549.3.4
Alg.Alias.Cipher.AES
Alg.Alias.Cipher.DES3

If the nCipherKM provider is installed but is not registered at the top of the providers list in the java.security file, the InstallationTest command produces output that includes the message:

The nCipher provider is installed, but is not registered at the top of the providers list in the java.security file.
See the user guide for more information about the recommended system configuration.

In such a case, edit the java.security file (located in the security directory for your local JVM installation) so that the nCipherKM provider is registered in the first position in that file’s list of providers. For more information about the java.security file, see Installing the nCipherKM JCA/JCE CSP.

If the nCipherKM provider is not installed at all, or you have not created a Security World, or if you have not configured ports correctly in the hardserver configuration file, the InstallationTest command produces output that includes the message:

The nCipher provider is not correctly installed.

In such case:

Check that you have configured ports correctly, as described in Installing the nCipherKM JCA/JCE CSP. For more information about hardserver configuration file settings, see HSM and client configuration files (network-attached HSMs) or Hardserver configuration files (PCIe and USB HSMs).
Check that you have created a Security World. If you have not created a Security World, create a Security World. For more information, see Create a new Security World
If you have already created a Security World, repeat the nCipherKM JCA/JCE CSP installation process as described in Installing the nCipherKM JCA/JCE CSP.

After making any changes to the nCipherKM JCA/JCE CSP installation, run the InstallationTest command again and check the output.

Whether or not the nCipherKM provider is correctly installed, if the unlimited strength jurisdiction files are not installed or (not correctly installed), the InstallationTest command produces output that includes the message:

Unlimited strength jurisdiction files are NOT installed.

The InstallationTest command can only detect this situation if you are using JRE/JDK version 1.6 or later.

This message means that, because the Java Virtual Machine imposes limits on the cryptographic strength that you can use by default with JCE providers, you must replace the default policy configuration files with the unlimited strength policy files. For information about how to install the unlimited strength jurisdiction files, see Installing the nCipherKM JCA/JCE CSP.

Named Modules in Java 11 and Java 17

The nCipherKM Provider has been implemented as a named module. This means that, for Java 11 and Java 17, if you have added the provider to your java.security file, then you can run your application with the nCipherKM.jar on the module-path and the Java ServiceLoader class will automatically find it, for example:

Linux

java --module-path /opt/nfast/java/classes com.ncipher.provider.InstallationTest

Windows

java --module-path %NFAST_HOME%\java\classes com.ncipher.provider.InstallationTest

Alternatively, you can specify the location of the nCipherKM jar on the classpath:

Linux

java --class-path /opt/nfast/java/classes/nCipherKM.jar com.ncipher.provider.InstallationTest

Windows

java --class-path %NFAST_HOME%\java\classes\nCipherKM.jar com.ncipher.provider.InstallationTest