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 the User Guide.
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 to9001
. -
nonpriv_port
(the port on which the hardserver listens for local nonprivileged TCP connections) is set to9000
.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 the User Guide for your HSM.
-
-
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) 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 theJAVA_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 yourPATH
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 the unlimited strength 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
andUS_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
andUS_export_policy.jar
into the security directory for your local Java Virtual Machine (JVM) installation: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
In these paths,
%JAVA_HOME%
(Windows) and$JAVA_HOME
(Linux) are the home directory of the Java installation (commonly specified in theJAVA_HOME
environment variable).Copying the files local_policy.jar
andUS_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
, bothcom.ncipher.provider.km.nCipherKM
and another provider). If you add the nCipherKM provider assecurity.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 the User Guide.
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 the User Guide.
-
Check that you have created a Security World. If you have not created a Security World, create a Security World. For more information, see the User Guide.
-
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:
In Linux:
java --module-path /opt/nfast/java/classes com.ncipher.provider.InstallationTest
In 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:
In Linux:
java --class-path /opt/nfast/java/classes/nCipherKM.jar com.ncipher.provider.InstallationTest
In Windows:
java --class-path %NFAST_HOME%\java\classes\nCipherKM.jar com.ncipher.provider.InstallationTest