IBM Java Security

Configuration and Usage



Introduction

IBM's security migration aid lets you use security enhancements from Java(tm)2 (later referred to as 1.2) with a base 1.1.8 Developer Kit without you needing to modify your 1.1 application. Configuration and usage of the security enhancements requires knowledge of policy files and policy permissions that you can gain by reading this guide and also by following links to other helpful documentation.

Pay close attention to the alarm symbol and text in RED.

Platform specific notes are in GREEN.


Contents :


Configuration I: CLASSPATH

The system variable, CLASSPATH, has to include the aid's jar file (SecMA.jar).
 
For OS/2 :

Set CLASSPATH globally in config.sys (like any other environment variable) or locally in any DOS window. The later will affects only the system variable in that window.
 
For AIX and OS/390 :

You can set CLASSPATH on the command line like any other environment variable;

For example when using ksh,

will set CLASSPATH locally to the given shell (assuming the Java home directory is "/usr/lpp/java/J1.1.8"). You can also set CLASSPATH globally by adding the above line to your user or system login profile shell (".profile" for ksh).

CLASSPATH Format

The CLASSPATH variable should contain the aid's jar file before the 1.1.8 classes.zip file, if classes.zip is explicitly added to CLASSPATHCLASSPATH need not  include classes.zip as it will be automatically added when an executable such as java or javac, is used.

Placing the aid's jar file first in the class path, will ensure that the Java Virtual Machine(JVM) finds the aid's java.lang.Thread class before the 1.1.8 java.lang.Thread class.
 

Top of Page


Configuration II: Policy Files

Four security policy files must be configured on your system. They are:
OS/2 :

To accommodate FAT file systems, the policy file names on OS/2 have been shortened to java.sec, user.sec, java.pol and user.pol. Apart from this, their behavior is the same and therefore the following section remains applicable.
 

The files need to be in the "security" sub directory under "lib" ;
For OS/2 :

java.home\lib\security
For AIX and OS/390 :
java.home/lib/security
Example files are in this directory and must be renamed. If you are unsure of your java.home location, you can use the following Java program to get it:
import java.io.*;

public class JavaHome {
   public static void main(String[] args) throws IOException {
      File javaHome = new File(System.getProperty("java.home"));
      System.out.println("java.home = "+javaHome.getCanonicalPath());
   }
}
Two of the files must be placed in security directory: java.security and user.security. The other two files are more flexible in their placement and can be placed in any directory that the JVM can read. A more detailed explanation of each file follows.

Important: In the policy files and on the command line, URLs and file path names should use a single forward slash (/) for a path separator .

In the remainder of the document, there are directions to "comment out" or "nullify" a policy file property. Both are equivalent and involve turning the valid policy file line into a comment. To comment out a property, use standard Java (or C, C++) techniques.
For example:
// In user.security:

java.security.manager=java.lang.SecurityManager
is nullified if it looks like this:
//java.security.manager=java.lang.SecurityManager
or this:
/*java.security.manager=java.lang.SecurityManager*/

java.security

This is the main security properties file. The file may require some initial changes, but once configured it is generally left untouched. java.security sets the security properties for the security classes to use. The only fields a user might change would be the URLs of policy files. The policy file URLs in the default java.security refer to two policy files: java.policy, a system policy file, and user.policy, a user policy file. You can combine the two policy files  into one if desired.

You can change the following entries, including the file names, to suit the user:

policy.url.1=file:${java.home}/lib/security/java.policy
policy.url.2=file:${java.home}/lib/security/user.policy


If the preceding two URLs are used, place java.policy and user.policy in the same directory as java.security.

You can find more information about the default security files and their entries may be found at Sun's PolicyFile guide.

user.security

This file is for user defined system properties. Do not confuse properties with permissions. The 1.1 JVMs do not have all of the system properties that 1.2 JVMs use. user.security compensates for missing properties. There are too many new properties to use "-Dsome.jdk12.property=value" on the command line, but a property not defined in user.security can be supplied, on the command line, in this way.

After creating the file in the security directory THIS IS A REQUIREMENT ), you should modify the aid's system properties to suit the test environment. The six property keys in user.security are:

The user.security properties are not added to java.security because the two files are incompatible. user.security contains system properties that the java.lang.System class accesses, while java.security contains security properties that the com.ibm.security12.java.security.Security class accesses. 

java.policy

This is a base system policy file borrowed from 1.2, it can be the only policy file used (no policy.url.2 entry in java.security).

You can place the file anywhere in the file system and can renamed it as long as the policy.url.1 location is correct in java.security.
Otherwise, place it in the security directory with the other policy and security files.
It is customary to place java.policy in the default location and leave it unchanged. Permissions are then added and removed from an additional policy file such as user.policy

user.policy

This is the user policy file in which a user can set specific policy permissions. For more information on permissions and grant blocks, see PolicyTool in this guide or Sun's PolicyFile guide.

You can place the file anywhere in the file system and rename it as long as the policy.url.2 value is correct in java.security. Otherwise, place it in the default security directory with the other policy and security files.

The first uncommented line in this file is reserved for the keystore file created using KeyTool. The value of keystore can be the keystore filename, the filename coupled with a path relative to user.policy, or an explicit path and filename. The following three examples illustrate the possibilities:

keystore "keys.file" 

keystore "storage/keys.file"                                 (AIX or OS/390)

keystore "e:\\jdk1.1\\lib\\security\\storage\\keys.file"     (OS/2)


It is a good idea is to remove or comment out old and unused permissions. This eliminates the possibility of permissions corrupting application or applet results. To comment lines in this file, use standard Java comment techniques.

To ease eventual migration to 1.2, users do not need to include "com.ibm.security12." in front of any permission classes encountered in permission entries.

In other words, you can shorten the following permission entry inside a grant block:
 

permission com.ibm.security12.java.io.FilePermission "foo.txt", "read";
can be shortened to:
 
permission java.io.FilePermission "foo.txt", "read";
Top of Page

Utilities: Key Tool, JarSigner, and PolicyTool

The aid includes three security tools that were introduced in 1.2:

KeyTool

KeyTool manages private keys and imports, views and exports certificates. The output of KeyTool is a keystore file and its location is included in the policy file, user.policy. For an overview of KeyTool, see Sun's KeyTool guide.

Passwords for keystore files and key pair aliases must be unique and at least six characters long.

Note : passwords are echoed back on the command line. Do not enter passwords in an insecure setting.

Some example commands are:

Generate a key pair having the alias racerx in the keystore file /home/fred/keystore.file with alias password rexrex and keystore password racerr. If some options are left out, either default values are used or KeyTool prompts the user for the values. To add more aliases, change -alias, -dname and -keypass values, -storepass and -keystore will remain the same.

>java com.ibm.security12.sun.security.tools.KeyTool -genkey -alias racerx 
-dname "cn=Rex Racer, ou=RacerRacing, o=CART, l=Austin, s=Texas, c=US" 
-keypass rexrex -storepass racerr -keystore /home/fred/keystore.file -v


Lists the contents of the keystore entry that the alias racerx represents. The user is prompted for the alias password. A missing -alias option prints all aliases in the keystore.

>java com.ibm.security12.sun.security.tools.KeyTool -list -alias racerx 
-storepass racerr -keystore /home/fred/keystore.file -v


This changes the alias password from rexrex to trixie for the alias racerx.

>java com.ibm.security12.sun.security.tools.KeyTool -keypasswd -alias racerx 
-keypass rexrex -new trixie -keystore /home/fred/keystore.file -storepass racerr
 
Note: The preceding examples use a UNIX file name but the procedure is the same for OS/2.


JarSigner

JarSigner generates digital signatures for JAR files and verifies signed JAR files using entries in a keystore file. It is an easy tool to use, and you can find more information about it at Sun's PolicyTool guide. Before using JarSigner, a JAR file must have been created. The command jar is not part of the aid, but it is part of the 1.1.8 Developer Kit package. You can find more information on the jar command at Sun's Java Archive Tool guide.

Here is a typical jar command:

>jar cvf new_jarfile.jar *.class


JarSigner allows options in any order, but prefers the JAR file to appear last except when signing a JAR. In that case it prefers the JAR file to be followed by the alias that is digitally signing the JAR file.

Some example JarSigner commands follow:

Sign rich.jar with alias MrRich, creating the signed JAR brich.jar. Leaving out the password options requires JarSigner to prompt for them. Leaving out the -signedjar option replaces rich.jar with a signed version of it.

>java com.ibm.security12.sun.security.tools.JarSigner -keystore keystore.file
-storepass youdaman -keypass brucer -signedjar brich.jar rich.jar MrRich


Many aliases can sign a JAR file, but this is tricky. If you repeat the preceding command but with different aliases, this creates a signed JAR file signed only with the last alias used. The preceding command writes over any existing brich.jar files when repeated. The solution is to perform the preceding command once and then follow it with versions of this one:

>java com.ibm.security12.sun.security.tools.JarSigner -keystore keystore.file
-storepass youdaman -keypass newaliaspaswd brich.jar newalias


This command verifies a signed JAR file:

>java com.ibm.security12.sun.security.tools.JarSigner -verify
-keystore keystore.file brich.jar

PolicyTool

PolicyTool is a GUI-based tool that creates and modifies the policy configuration files that define your system's Java security policy. Because it is not a command-line tool, for information view Sun's PolicyTool guide.

The following example show how to use the PolicyTool:
 

For OS/2;
>java com.ibm.security12.sun.security.tools.PolicyTool
-file c:\jdk1.1.8\lib\security\user.policy
For AIX or OS/390;
>java com.ibm.security12.sun.security.tools.PolicyTool
-file /usr/local/J1.1.8/lib/security/user.policy


The -file flag is optional. Without it, PolicyTool will try to load the default policy file, user.home/.java.policy. Because the aid uses a different name and location for the user policy file compared to 1.2, you are strongly recommended to use the -flag option to ease eventual migration.

One limitation of the PolicyTool is that it removes all comments you enter into the policy file by hand.

For some users, it is easier to enter permissions by hand into a policy file.

No matter which way you enter permissions, knowledge of policy file entries is essential. See Sun's PolicyFile guide.

The following example dissects an AIX policy file grant block (the format is the same on other platforms except for file names):

grant signedBy "MrRich, MrSoper, MrNadalin", codeBase "file:/perms/apps/*" {
   permission java.lang.PropertyPermission "user.home", "read";
   permission java.io.FilePermssion "/home/foo/bar.txt", "read, write, delete";
};


Notice the set of curly braces defining the grant block. Also notice the presence of semicolons at the end of each line after the grant line.
The grant block defines two permissions:

You may wonder what code is granted the two permissions?
Any code that comes from a JAR file signed by (at least!) the three aliases MrRich, MrSoper, and MrNadalin (the signedBy field).
Also the JAR file must come from d:\perms\apps (the codeBase field).
The signedBy and codeBase fields are optional.

Top of Page


Usage I: Java Applications

To execute an application using the aid's security features, enter the following statement at a command prompt:
>java com.ibm.security12.sun.misc.Main app_name


For example:

>java com.ibm.security12.sun.misc.Main PropPerm


Invoking com.ibm.security12.sun.misc.Main instantiates the aid's version of the 1.2 sun.misc.Launcher class which then creates an instance of the security manager set in user.security. This also creates the security policy for the application created at this time.

Before executing a Java application, you must perform the following steps:

The files java.security and java.policy should not need to be changed. Here is a detailed UNIX (AIX and OS/390) example that runs an application using the aid: Execution 1:
  1. In user.security,
  2. In user.policy, add this grant block:
  3. grant {
       permission java.util.PropertyPermission "new.user.prop", "read"; 
    };
  4. Type at a command line:
  5. >java com.ibm.security12.sun.misc.Main PropPerm
    The grant block could have been more restrictive by specifying
      grant codeBase "file:/home/perm_tests/apps.jar" {
    on the grant line.
In addition to the preceding scenario, it is also known that:
Execution 2:
  1. In user.policy, change the grant block:
  2. grant codeBase "file:/home/perm_tests/apps.jar", signedBy "moe, curly" {
       permission java.util.PropertyPermission "new.user.prop", "read";
    };
  3. Type at a command line:
  4. >java com.ibm.security12.sun.misc.Main PropPerm
Note the reduction in steps since java.app.class.path, sun.boot.class.path, and java.security.manager were set in Execution 1. Also, only two aliases were included in the signedBy field.

Top of Page


Usage II: Java Applets

Applets usually run in a Java enabled browser. However, browsers are not yet capable of implementing the aid's security features. Meanwhile, users can call applets by using the aid's AppletViewer. Because an applet can reside locally or remotely, there are two ways to run applets at a command prompt:
>java com.ibm.security12.sun.applet.AppletViewer file:applet.html


or

>java com.ibm.security12.sun.applet.AppletViewer http://us.ibm.com/applet.html
 
OS/390 :

Due to OS/390 using EBCDIC character encoding the appletviewer switch "-encoding 8859_1"  is required for correct operation. This should be placed after the AppletViewer class name but before the HTML file name.

The applet.html is an HTML file with a CODE tag set to the applet class.
AppletViewer instantiates its own security manager so the security manager property in user.security must be nullified.

Before execution, you must:

java.security and java.policy should not need to be changed. Here's a detailed OS/2 example running a local applet. Execution 1:
  1. In user.security,
  2. In user.policy, add this grant block:
  3. grant {
       permission java.io.FilePermission "i:/eta/gordita.txt", "read,write";
    };
  4. Type at a command prompt:
  5. >java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html
  6. The grant block could have been more restrictive by specifying on the grant line:
  7. grant codeBase "file:/d:/perm_tests/" {
    In addition to the preceding scenario, it is also known that:

    apps.jar is a JAR file that resides in d:/perm_tests/ and contains the example applet.

    FilePerm.class has been removed from d:/perm_tests/ .

Execution 2:
  1. Change filePerm.html to include the ARCHIVE tag:
  2. <APPLET>
    CODE=FilePerm.class
    ARCHIVE=apps.jar
    </APPLET>
  3. In user.policy, change the grant block to be more restrictive:
  4. grant codebase "file:/d:/perm_tests/apps.jar" {
       permission java.io.FilePermission "i:/eta/gordita.txt", "read,write";
    };
  5. Type the same command:
  6. >java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html
  7. These are all the changes. The properties in user.security remain unchanged: there are no java.security.manager and vestigial values for java.app.class.path and sun.boot.class.path.
In addition to the scenario in Execution 2, it is also known that: Execution 3:
  1. Change filePerm.html to include the CODEBASE tag:
  2. <APPLET>
    CODE=FilePerm.class
    CODEBASE=file:/e:/different/drive
    ARCHIVE=apps.jar
    </APPLET>
  3. In user.policy, change the grant block:
  4. grant codeBase "file:/e:/different/drive/apps.jar", signedBy "moe, curly" {
       permission java.io.FilePermission "i:/eta/gordita.txt", "read,write";
    };
  5. Type the same command:
  6. >java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html
  7. Notice how the only changes occurred in the user.policy grant block and the HTML file.
Here is a detailed example running a remote applet using the aid.

It is known that:

Execution 4:
  1. Change filePerm.html to include the CODE and ARCHIVE tags:
  2. <APPLET>
    CODE=FilePerm.class
    ARCHIVE=apps.jar
    </APPLET>
  3. In user.security,
  4. These are the same settings used for running a local applet.
     
  5. In user.policy, add the most restrictive grant block:
  6. grant codeBase "http://us.ibm.com/-", signedBy "moe, larry, curly" {
       permission java.io.FilePermission "mookie.txt", "read,write,delete";
    };
  7. Type at a command prompt:
  8. >java com.ibm.security12.sun.applet.AppletViewer http://us.ibm.com/filePerm.html
If accessing remote applets, it is best to use a "-" in place of the HTML file when writing a codeBase field on a grant line.

Top of Page


Debugging and Trouble Shooting

Debugging

Implementing java.security.debug in user.security.
value action
all All debug values below. Expect a plethora of output.
access Print out access grants or denials from checkPermission calls.
jar Print out jar-related messages, such as verification.
policy Print out policy file loading and granting.
scl Print out permissions SecureClassLoader assigns.

Multiple debug values may exist for java.security.debug by separating them with any non-alphabetic character. Using commas or semicolons is recommended.

The most common errors encountered when using the aid:
 

OS/2 specifically;
AIX and OS/390 specifically;
General;

Trouble Shooting

When using the aid the majority of errors you encounter will relate to your application trying execute code or access system resources which it has not be granted access to. The generated error message will indicate the type of action which is not allowed and where it was called from, using this information you can define the required permissions in your policy file.

Some of the error messages, relating to use of the aid, are :
 

This error may occur  for a number of reasons that are not related to the aid. On occasion it is possible for an access violation raised in a static initializer to be reported simply as an ExceptionInInitializerError. If you believe that an error is the result of a failed security operation, use the java.security.debug property in the user.security file. This will generate a list of security operations, a success or failure flag, and a full stack trace of each location. From this it is possible to identify security failures in static initializers.
Top of Page

Tips

and called in the same way.
Top of Page


[ IBM home page | (C) | (TM) ]
 © IBM Corporation 1999. All Rights Reserved