# 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

Configuration II: Policy Files

Utilities: KeyTool, JarSigner, and PolicyTool

Usage I: Java Applications

Usage II: Java Applets

Debugging and Trouble Shooting

Tips

## 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,

    export CLASSPATH=/usr/lpp/java/J1.1.8/lib/SecMA.jar

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 CLASSPATH. CLASSPATH 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:

- java.security
- user.security
- java.policy
- user.policy

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:

java.app.class.path:
This is the location of application and other classes not found on the class path, java.class.path. Because classes on the class path are trusted and have special privileges, the aid uses java.app.class.path from 1.2 to specify the location of an untrusted application without using a "dot" (.) or explicit location in the class path.

Applets run with AppletViewer (see Usage II: Java Applets) do not have to implement java.app.class.path. You can set the key to NULL or leave it with a blank value.

Set this key to the directory containing the application.
If the target classes are contained in a JAR file, then java.app.class.path should include the JAR file.
Separate multiple directories and JAR files should be separated using the standard format for your platform: a semicolon (;) for OS/2 or a colon (:) for AIX and OS/390, just as with java.class.path.

OS/2 example;

    java.app.class.path=c:/applications;d:\\classes\\untrusted.jar

AIX or OS/390 example;

    java.app.class.path=/usr/applications:/home/fred/classes/untrusted.jar

sun.boot.class.path:
The purpose of this entry in 1.2 is to specify the location(s) of trusted classes. The aid currently does not use the value of this property, but you need to set this property to some value, even to blank (""). Commenting out sun.boot.class.path (prepending '//' to it) gives it a NULL value and the application will promptly exits before execution.

Applets run with AppletViewer (see Usage II: Java Applets) do not implement sun.boot.class.path. You can set the key to NULL or leave it with a blank value.

java.ext.dirs:
This is the location of extensions directory if the application employs extension classes. The default extension classes location is java.home\lib\ext, for OS/2 and java.home/lib/ext for AIX or OS/390.

java.security.manager:
This is the type of security manager the aid employs.

Comment out this property when running applets.
This property is used only with APPLICATIONS because APPLETVIEWER employs its own security manager.

If java.security.manager is set to blank, "default", "java.lang.SecurityManager", or "com.ibm.security12.java.lang.SecurityManager12", a com.ibm.security12.java.lang.SecurityManager12 object is instantiated.
Another possible value for this property is a custom security manager that extends SecurityManager12.

Note :
A NULL value for java.security.manager runs applications with security turned off (no security manager).

A single user.security file can be used for both applets and applications, while executing the applications with a security manager. To achieve this nullify the java.security.manager property in user.security and supply it on the command line. For example to execute the class "xxx" type;

    java -Djava.security.manager=default com.ibm.security12.sun.misc.Main xxx

java.security.policy:
This represents the location of the 1.1 identity database file. You can leave this blank unless using the -identitydb option of KeyTool is used when importing a 1.1 style identity database.

java.security.debug:
This sets a debug flag that prints out various security information. See Debugging for the debug values and what they printout.

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 for managing keys and certificates,
- JarSigner uses the keys and certificates to sign archived Java class files (JAR files), and
- PolicyTool can be used to set permissions on classes in signed JAR files (or any classes) that applications. use.

## 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:

- allow reading of the user.home system property
- allow read, writing and deletion, as required, of the file "c:/foo/bar.txt" .

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:

- In user.security:

1. Set java.app.class.path to the directory or JAR file containing app_name.class.
2. Set sun.boot.class.path to some non-NULL value.
3. Set java.security.manager.

- In user.policy:

1. Enter required permissions that the application dictates.

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:

The application, PropPerm.class resides in a jar file located at /home/perm_tests/.
Assume /home/perm_tests/apps.jar

It requires a com.ibm.security12.java.util.PropertyPermission("new.user.prop", "read") permission for successful execution. Otherwise an exception is thrown.

Execution 1:

1. In user.security,

- Set java.app.class.path=/home/perm_tests/apps.jar.
- Set sun.boot.class.path= (blank).
- Set java.security.manager= (blank, which implies SecurityManager12).

2. In user.policy, add this grant block:

    grant {
       permission java.util.PropertyPermission "new.user.prop", "read";
    };

3. Type at a command line:

    >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:

apps.jar is a digitally signed JAR file that has been signed by the aliases moe, larry, and curly which are all found in the keystore file already identified on the first line of user.policy.

Execution 2:

1. In user.policy, change the grant block:

    grant codeBase "file:/home/perm_tests/apps.jar", signedBy "moe, curly" {
       permission java.util.PropertyPermission "new.user.prop", "read";
    };

2. Type at a command line:

    >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:

- In user.security:

1. Set java.app.class.path to blank or NULL.
2. Set sun.boot.class.path to blank or NULL.
3. Set java.security.manager to NULL!

- In user.policy:

1. Enter required permissions that the applet dictates.

java.security and java.policy should not need to be changed. Here's a detailed OS/2 example running a local applet.

The applet, FilePerm.class resides in a directory located at d:\perm_tests\ .

For simplicity of this example, an HTML file, filePerm.html, resides in the same directory.
It includes this code:

    <APPLET>
    CODE=FilePerm.class
    </APPLET>

FilePerm.class requires a com.ibm.security12.java.io.FilePermission("i:/eta/gordita.txt", "read,write") permission to run successfully. Otherwise an exception is thrown.

Execution 1:

1. In user.security,

- Set java.app.class.path to NULL by prepending it with "//".
- Set sun.boot.class.path to NULL by prepending it with "//".
- Set java.security.manager to NULL by prepending it with "//".

2. In user.policy, add this grant block:

    grant {
       permission java.io.FilePermission "i:/eta/gordita.txt", "read,write";
    };

3. Type at a command prompt:

    >java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html

4. The grant block could have been more restrictive by specifying on the grant line:

    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:

    <APPLET>
    CODE=FilePerm.class
    ARCHIVE=apps.jar
    </APPLET>

2. In user.policy, change the grant block to be more restrictive:

    grant codebase "file:/d:/perm_tests/apps.jar" {
       permission java.io.FilePermission "i:/eta/gordita.txt", "read,write";
    };

3. Type the same command:

    >java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html

4. 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:

apps.jar is a digitally signed JAR file that has been signed by the aliases moe, larry, and curly which are all found in the keystore file already identified on the first line of user.policy.

apps.jar now resides only at e:\different\drive\.

filePerm.html is still at d:\perm_tests\.

Execution 3:

1. Change filePerm.html to include the CODEBASE tag:

    <APPLET>
    CODE=FilePerm.class
    CODEBASE=file:/e:/different/drive
    ARCHIVE=apps.jar
    </APPLET>

2. In user.policy, change the grant block:

    grant codeBase "file:/e:/different/drive/apps.jar", signedBy "moe, curly" {
       permission java.io.FilePermission "i:/eta/gordita.txt", "read,write";
    };

3. Type the same command:

    >java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html

4. 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:

FilePerm.class resides in a JAR file called apps.jar.

apps.jar is a digitally signed JAR file that has been signed by the aliases moe, larry, and curly which are all found in the keystore file already identified on the first line of user.policy.

apps.jar now resides at http://us.ibm.com/.

filePerm.html is also at http://us.ibm.com/.

FilePerm.class requires a com.ibm.security12.java.io.FilePermission("mookie.txt", "read,write,delete") permission for successful execution. Otherwise an exception is thrown.

Execution 4:

1. Change filePerm.html to include the CODE and ARCHIVE tags:

    <APPLET>
    CODE=FilePerm.class
    ARCHIVE=apps.jar
    </APPLET>

2. In user.security,

- Set java.app.class.path to NULL by prepending it with "//".
- Set sun.boot.class.path to NULL by prepending it with "//".
- Set java.security.manager to NULL by prepending it with "//".

These are the same settings used for running a local applet.
3. In user.policy, add the most restrictive grant block:

    grant codeBase "http://us.ibm.com/-", signedBy "moe, larry, curly" {
       permission java.io.FilePermission "mookie.txt", "read,write,delete";
    };

4. Type at a command prompt:

    >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;

Using a single backslash in a path.

This is ok only on the command line.
In policy files, use double backslashes (\\) or a single forward slash (/).

Errors involving CLASSPATH:

- Setting CLASSPATH using the Control Panel window and then using a previously opened DOS window. The change is reflected only in newly opened windows.
- Setting CLASSPATH in a DOS window and then opening a new DOS window. The properties do not migrate to other windows using the command method of setting CLASSPATH.
- Placing an untrusted Java application in the CLASSPATH. Doing so causes it to be trusted and overrides any security manager checks.
- Placing the aid's JAR file after the 1.1.8 classes.zip file in CLASSPATH.

Using incorrect protocol format in URL.

- "file://c:/ ..." is incorrect. ("http:// ..." is correct and "file:/c:/ ..." is always correct.)
- "file:c:/ ..." is incorrect if employed in a codebase statement within an <APPLET> tag.

AIX and OS/390 specifically;

Errors involving CLASSPATH:

- Setting CLASSPATH in one shell and then starting another session. The setting of the CLASSPATH property migrate to a new shell.
- Placing an untrusted Java application in the CLASSPATH. Doing so causes it to be trusted and overrides any security manager checks.
- Placing the aid's JAR file after the 1.1.8 classes.zip file in CLASSPATH.

Using incorrect protocol format in URL.

- "file:// ..." is incorrect. ("http:// ..." is correct and "file:/ ..." is also correct.)

General;

Trying to set a security manager when running applets with the AppletViewer class.

- AppletViewer instantiates its own security manager.

Using incorrect protections for remote applets.

- Applets accessed through HTTP need to have universal read permissions.
- The directories to applets need to have universal read and execute permissions.

Combining the java.security and user.security files into one policy file.

java.security contains Security properties while user.security contains System properties.

Errors involving policy files:

- Placing the java.security and user.security policy files anywhere except in the java.home/lib/security directory. Placing these files elsewhere is not an option.
- Trying to set a policy file property to NULL by leaving it blank. A blank is a value for an existing property. Commenting out the property makes it non-existent.
- Using incorrect case. Grant fields are case sensitive. Using "codebase" or "signedby" instead of "codeBase" or "signedBy" disqualifies the intended grant block, and no error message is given.
- Including JAR files only in the directory. JAR files must also be included in java.app.class.path.

Relying on default file locations when using KeyTool and PolicyTool.

It is recommended that you use the keystore and policy file flags because the default locations of the two files differ between 1.1 and 1.2. This is very important if you use a keystore file or policy file in an aid's environment and then in a 1.2 environment, or vice versa. See KeyTool and PolicyTool for examples.
- KeyTool: use "-keystore"
- PolicyTool: use "-file"

Erroneously signing a JAR file with more than one alias.

- After running the JarSigner utility with the desired aliases.

#### 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 :

- A java.lang.ClassCastException or java.lang.NoSuchFieldError thrown whilst in an AccessController method.

This exception will occur if the SecMA.jar file has been added to the CLASSPATH after classes.zip. SecMA.jar must come first so that the JVM picks up the aid's Thread class instead of the classes.zip Thread class. The aid's Thread class contains additional fields that are required by the security code.
- A java.lang.ExceptionInInitializerError

> 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

- Application Shortcut; if entering "java com.ibm.security12.sun.misc.Main Foo" on the command line is tiresome, then write a batch file (OS/2) or use an alias (AIX and OS/390).

OS/2;
The batch file could be called "javam.bat" and contain;

    java com.ibm.security12.sun.misc.Main %1 %2 %3 %4

The batch file can take up to four arguments; more if you include more %'s. The new command is shortened to

    >javam Foo

AIX and OS/390;
The same results can be obtained by defining,

    alias javam="java com.ibm.security12.sun.misc.Main "

> and called in the same way.

- Applet Shortcut; You can write a similar batch file or alias for applets and the AppletViewer class. "javav"?
- Forward slashes; On OS/2 consistently using UNIX style path separators (single forward slash) instead of double back slashes in policy files helps eliminate the error a single back slash may cause.
- Disablement; if you wish to disable the aid once configured, you will need to do two things;

1. Remove the file SecMA.jar from the class path,
2. Replace the aid's java.security file, in java.home/lib/security, with the original 1.1.8 java.security file.

Top of Page

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