JavaTM Cryptography Extension (JCE) 1.2.2

Installation Instructions

---

Note: The current release, JCE 1.2.2, is a maintenance release of JCE 1.2.1. 

---

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

   Note that JCE 1.2.2 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. 

2. Uncompress and extract the downloaded file. This will create a directory named jce1.2.2, with two subdirectories named doc and lib. 
3. The JCE 1.2.2 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_2.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.2 framework JAR file. In some cases, permissions must be granted to the JCE 1.2.2 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.2 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.2 framework an installed extension, move or copy the jce1_2_2.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_2.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.2 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_2.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.2 framework and JCE providers are located on the class path (not installed extensions).

   Pro: The JCE 1.2.2 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.2 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.2 framework file jce1_2_2.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.2 framework, or a different directory. 

   Be sure to set the class path to include the directories containing the JCE 1.2.2 framework and "SunJCE" provider JAR files. 

   Permissions: The following permission should be granted to the JCE 1.2.2 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.2 framework is assumed to be in the /home/mydir directory. 

     grant codeBase "file:/home/mydir/jce1_2_2.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_2.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.2 framework and the policy files are 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_2.jar", "read";
       permission java.lang.RuntimePermission 
         "getProtectionDomain";
       permission java.security.SecurityPermission
         "putProviderProperty.SunJCE";
     };

4. Register the "SunJCE" provider. 

Although the "SunJCE" provider is supplied with every JCE 1.2.2 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 and requires security permissions "insertProvider.SunJCE" to be granted to your program if a security manager is installed.

Unless otherwise licensed, code in all technical manuals herein (including articles, FAQs, samples) is provided under this License.

Copyright © 1995-2002 Sun Microsystems, Inc. All Rights Reserved. Terms of Use. Privacy Policy.