JavaTM Cryptography Extension (JCE) 1.2.1

Installation Instructions

####

Download JCE 1.2.1. You can save the downloaded file anywhere on your local disk.

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

####

Uncompress and extract the downloaded file. This will create a directory named `jce1.2.1`, with two subdirectories named `doc` and `lib`.

####

The JCE 1.2.1 framework and the "SunJCE" provider are supplied as extensions (also known as "optional packages") to the Java 2 platform.

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 JavaTM 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 JavaTM 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";
>       };

####

Register the "SunJCE" provider.

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 JavaTM 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.