JCE 1.2.1 -- Installation Instructions

Java^TM Cryptography Extension (JCE) 1.2.1

Installation Instructions

Note that JCE 1.2.1 requires that you have Java^TM 2 SDK v 1.2.1 or later or Java^TM 2 Runtime Environment v 1.2.1 or later already installed.

jce1.2.1

doc

lib

The lib subdirectory extracted in the previous step contains the jce1_2_1.jar and sunjce_provider.jar files. The lib subdirectory should also contain JAR files for jurisdiction policy files: US_export_policy.jar and local_policy.jar.

Two types of installations are supported, described below. In both cases, the jurisdiction policy files must be installed in the same directory as that which contains the JCE 1.2.1 framework JAR file. In some cases, permissions must be granted to the JCE 1.2.1 framework and/or the "SunJCE" provider for when applets or applications using JCE are run while a security manager is installed. Note: There is typically a security manager installed whenever an applet is running, and a security manager may be installed for an application either via code in the application itself or via a command-line argument.

Installation Option 1: The JCE 1.2.1 framework is an "installed" extension. Providers are installed or bundled.

(Note: A package (or packages) housed in a JAR file is considered "installed" if the JAR file is stored in a particular directory established for all installed extensions, as described below.)
Pro: This is the most convenient type of installation. Permissions do not need to be granted to installed extensions, since the default system policy file grants all permissions to installed extensions.
Con: You must have access rights that allow you to write to the special directory that holds installed extensions.
Instructions: To make the JCE 1.2.1 framework an installed extension, move or copy the jce1_2_1.jar, US_export_policy.jar, and local_policy.jar files from the lib subdirectory extracted in the previous step to the standard place for the JAR files of an installed extension:
<java-home>\lib\ext         [Win32]
<java-home>/lib/ext         [Solaris]
Here <java-home> refers to the directory where the runtime software is installed, which is the top-level directory of the JRE or the jre directory in the Java^TM 2 SDK software. For example, if you have J2SDK v 1.2.2 installed on Solaris in a directory named jdk1.2.2, you need to install the JAR files in the following directory:
jdk1.2.2/jre/lib/ext
Similarly, if you have Java^TM 2 Runtime Environment v 1.2.2 installed on Solaris in a directory named jre1.2.2, you need to install the JAR files in the following directory:
jre1.2.2/lib/ext
To also make the "SunJCE" provider an "installed" extension, move or copy sunjce_provider.jar to that same directory for installed extensions. If you want to make the "SunJCE" provider a "bundled" extension, see Bundled Extensions.
Permissions: You will need to grant the "SunJCE" provider the permissions listed below if it is bundled and if a security manager is installed. You don't have to understand what the permissions mean, but you must grant them, for example, in a policy file, or the "SunJCE" provider won't work. Here are the permissions that must be granted:

java.io.FilePermission to read the jce1_2_1.jar file
java.lang.RuntimePermission to get class protection domains
java.security.SecurityPermission to put (set) provider properties.

A sample statement granting these permissions appears below. Such a statement could appear in a policy file. In this example, the JCE 1.2.1 framework is assumed to be an installed extension and the sunjce_provider.jar file is assumed to be in the /work directory.
  grant codeBase "file:/work/sunjce_provider.jar" {
    permission java.io.FilePermission
      "/jdk1.2.2/jre/lib/ext/jce1_2_1.jar", "read";
    permission java.lang.RuntimePermission 
      "getProtectionDomain";
    permission java.security.SecurityPermission
      "putProviderProperty.SunJCE";
  };
Once you have completed this type of installation, go on to the next step to register the "SunJCE" provider.

Installation Option 2: The JCE 1.2.1 framework and JCE providers are located on the class path (not installed extensions).

Pro: The JCE 1.2.1 framework and providers don't have to be put in a special directory. This is very useful if you share a Java 2 installation with other people and you don't have access rights allowing you to write to the directory for installed extensions.
Con: Permissions need to be granted to the JCE 1.2.1 framework and JCE providers for when applets or applications using JCE are run while a security manager is installed.
Instructions: Move or copy the JCE 1.2.1 framework file jce1_2_1.jar and jurisdiction policy files (US_export_policy.jar, and local_policy.jar) to a directory that will be listed on your class path. (Note: All these files must be in the same directory.) Move or copy the "SunJCE" provider file sunjce_provider.jar to another directory that will be listed on your class path. It can be the same as the directory containing the JCE 1.2.1 framework, or a different directory.
Be sure to set the class path to include the directories containing the JCE 1.2.1 framework and "SunJCE" provider JAR files.
Permissions: The following permission should be granted to the JCE 1.2.1 framework when a security manager is installed:
java.security.AllPermission
Below is a sample statement granting this permission. Such a statement could appear in a policy file. In this example, the JCE 1.2.1 framework is assumed to be in the /home/mydir directory.
  grant codeBase "file:/home/mydir/jce1_2_1.jar" {
    permission java.security.AllPermission;
  };
The following permissions should be granted to the "SunJCE" provider (and other JCE providers) when a security manager is installed::

java.io.FilePermission to read the jce1_2_1.jar file
java.lang.RuntimePermission to get class protection domains
java.security.SecurityPermission to put (set) provider properties.

A sample grant statement granting these permissions appears below. In this example, the JCE 1.2.1 framework is assumed to be in the /home/mydir directory and the sunjce_provider.jar file is assumed to be in the /work directory.
  grant codeBase "file:/work/sunjce_provider.jar" {
    permission java.io.FilePermission
      "/home/mydir/jce1_2_1.jar", "read";
    permission java.lang.RuntimePermission 
      "getProtectionDomain";
    permission java.security.SecurityPermission
      "putProviderProperty.SunJCE";
  };

Although the "SunJCE" provider is supplied with every JCE 1.2.1 installation, it still needs to be configured explicitly, either statically or dynamically, before its services can be accessed:

Static registration of SunJCE provider
Add the "SunJCE" provider to your list of approved providers. This is done statically by editing the security properties file
```
  [Win32]
    <java-home>\lib\security\java.security
  [Solaris]
    <java-home>/lib/security/java.security
```
Here, as in the previous step, <java-home> refers to the directory where the JRE was installed. For example, if you have J2SDK v 1.2.2 installed on Solaris in a directory named jdk1.2.2, you need to edit the following file:
```
jdk1.2.2/jre/lib/security/java.security
```
Similarly, if you have Java^TM 2 Runtime Environment v 1.2.2 installed on Solaris in a directory named jre1.2.2, you need to edit this file:
```
jre1.2.2/lib/security/java.security
```
One of the types of properties you can set in java.security is of the following form:
```
    security.provider.n=providerClassName
```
The java.security file should have a statement of that form for each provider to be registered statically. Each such statement declares a provider, and specifies its preference order n. The preference order is the order in which providers are searched for requested algorithms (when no specific provider is requested). The order is 1-based; 1 is the most preferred, followed by 2, and so on.
J2SE comes standard with a provider named "SUN", which is automatically configured as a static provider, as follows:
```
  security.provider.1=sun.security.provider.Sun
```
To configure other providers, follow this line with other lines of the proper format, replacing providerClassName with the fully qualified "master class name" you obtain from the provider vendor, and substituting n with the priority that you would like to assign to the provider.
For example, if you would like to configure "SunJCE" as your second preferred provider, add the following line to the java.security file after the line for the "Sun" provider:
```
  security.provider.2=com.sun.crypto.provider.SunJCE
```
Dynamic registration of SunJCE provider
To dynamically register the SunJCE provider (instead of statically), add the following lines of code at the beginning of your program:
```
    Security.addProvider(
       new com.sun.crypto.provider.SunJCE());
```
This type of registration is not persistent.