Pay close attention to the
alarm symbol and text in RED.
Platform specific notes are in GREEN.
Configuration II: Policy
Files
Utilities: KeyTool, JarSigner,
and PolicyTool
For example when using ksh,
export CLASSPATH=/usr/lpp/java/J1.1.8/lib/SecMA.jarwill 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).
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.
The files need to be in the "security" sub directory under "lib" ;
For OS/2 :
java.home\lib\security
java.home/lib/securityExample 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.SecurityManageris nullified if it looks like this:
//java.security.manager=java.lang.SecurityManageror this:
/*java.security.manager=java.lang.SecurityManager*/
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.
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:
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.
java.app.class.path=c:/applications;d:\\classes\\untrusted.jar
java.app.class.path=/usr/applications:/home/fred/classes/untrusted.jar
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.
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.
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
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
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
The following example show how to use the PolicyTool:
>java com.ibm.security12.sun.security.tools.PolicyTool -file c:\jdk1.1.8\lib\security\user.policy
>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:
>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:
It requires a com.ibm.security12.java.util.PropertyPermission("new.user.prop", "read") permission for successful execution. Otherwise an exception is thrown.
grant { permission java.util.PropertyPermission "new.user.prop", "read"; };
>java com.ibm.security12.sun.misc.Main PropPermThe grant block could have been more restrictive by specifying
grant codeBase "file:/home/perm_tests/apps.jar" {
In addition to the preceding scenario, it is also known that:
grant codeBase "file:/home/perm_tests/apps.jar", signedBy "moe, curly" { permission java.util.PropertyPermission "new.user.prop", "read"; };
>java com.ibm.security12.sun.misc.Main PropPerm
>java com.ibm.security12.sun.applet.AppletViewer file:applet.html
or
>java com.ibm.security12.sun.applet.AppletViewer http://us.ibm.com/applet.html
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:
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:
grant { permission java.io.FilePermission "i:/eta/gordita.txt", "read,write"; };
>java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html
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/ .
<APPLET> CODE=FilePerm.class ARCHIVE=apps.jar </APPLET>
grant codebase "file:/d:/perm_tests/apps.jar" { permission java.io.FilePermission "i:/eta/gordita.txt", "read,write"; };
>java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html
apps.jar now resides only at e:\different\drive\.
filePerm.html is still at d:\perm_tests\.
<APPLET> CODE=FilePerm.class CODEBASE=file:/e:/different/drive ARCHIVE=apps.jar </APPLET>
grant codeBase "file:/e:/different/drive/apps.jar", signedBy "moe, curly" { permission java.io.FilePermission "i:/eta/gordita.txt", "read,write"; };
>java com.ibm.security12.sun.applet.AppletViewer file:/d:/perm_tests/filePerm.html
It is 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 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.
<APPLET> CODE=FilePerm.class ARCHIVE=apps.jar </APPLET>
grant codeBase "http://us.ibm.com/-", signedBy "moe, larry, curly" { permission java.io.FilePermission "mookie.txt", "read,write,delete"; };
>java com.ibm.security12.sun.applet.AppletViewer http://us.ibm.com/filePerm.html
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:
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
java com.ibm.security12.sun.misc.Main %1 %2 %3 %4The batch file can take up to four arguments; more if you include more %'s. The new command is shortened to
>javam Foo
alias javam="java com.ibm.security12.sun.misc.Main "
and called in the same way.