9
Java 2 Security

This chapter discusses Java 2 Security features. It contains the following sections:

Introduction

The Java 2 Security Model is fundamental to the JAAS Provider. The Java 2 Security Model enables configuration of security at all levels of restriction. This provides developers and administrators with increased control over many aspects of enterprise applet, component, servlet, and application security.

See Also:

For a tutorial on Java 2 Security, see http://java.sun.com/docs/books/tutorial/security1.2/index.html. For full information on Java 2 Security, see http://java.sun.com/security.

Permissions

Permissions are the basis of the Java 2 Security Model. All Java classes (whether run locally or downloaded remotely) are subject to a configured security policy that defines the set of permissions available for those classes. Each permission represents a specific access to a particular resource. Table 9-1 identifies the elements that comprise a Java permission instance.

Table 9-1 Java Permission Instance Elements

Element	Description	Example
Class name	The permission class	`java.io.FilePermission`
Target	The target name (resource) to which this permission applies	Directory `/home/*`
Actions	The actions associated with this target	Read, write, and execute permissions on directory `/home/*`

Protection Domains

Each Java class, when loaded, is associated with a protection domain. Protection domains can be configured for all levels of restriction (from complete restriction on resources to full access to all resources). Each protection domain is assigned a group of permissions based on a configured security policy at Java virtual machine (JVM) startup.

At runtime, the authorization check is done by stack introspection. This consists of reviewing the runtime stack and checking permissions based on the protection domains associated with the classes on the stack. This is typically triggered by a call to either:

SecurityManager.checkPermission()
AccessController.checkPermission()

The permission set in effect is defined as the intersection of all permission sets assigned to protection domains at the moment of the security check.

Figure 9-1 shows the basic model for authorization checking at runtime.

Figure 9-1 Java 2 Security Model

Text description of the illustration jaz005.gif

See Also:

Chapter 4, "JAAS Provider Administration Tasks"
Sun Java documentation at the URL
```
http://java.sun.com/security/
```

JAAS Provider Permission Classes

Table 9-2 lists the permission classes furnished by the JAAS Provider. These classes allow applications to control access to resources. For information about the classes discussed, see the JAAS Provider Javadoc.

Table 9-2 JAAS Provider Permission Classes

Permission	Part of Package	Description
`AdminPermission`	`oracle.security.jazn.policy`	Represents the right to administer a permission (that is, grant or revoke another user's permission assignment).
`RoleAdminPermission`	`oracle.security.jazn.policy`	The grantee of this permission is granted the right to further grant/revoke the target role.
`JAZNPermission`	`oracle.security.jazn`	For authorization permissions. `JAZNPermission` contains a name (also called a target name), but no actions list; you either have or do not have the named permission.
`RealmPermission`	`oracle.security.jazn`.`realm`	Represents permission actions for a realm (such as `createRealm`, `dropRealm`, and so on). `RealmPermission` extends from `java.security.Permission`, and is used like any regular Java permission.

Creating a Java 2 Policy File

The Java 2 policy file grants permissions to trusted code or applications that you run. This enables code or applications to access Oracle support for JAAS or JDK APIs requiring specific access privileges.

A preconfigured Java 2 policy (java2.policy) is provided in
ORACLE_HOME/j2ee/home/config.

You need to modify the Java 2 policy file to grant permissions to trusted code or applications.

For example, the following section of a java2.policy file grants java.security.AllPermission to the trusted jazn.jar.

/* grant the JAZN library AllPermission */ 
grant codebase "file:${oracle.home}/j2ee/home/jazn.jar" { 
    permission java.security.AllPermission; 
};

The following example grants specific permissions to all applications running in the $ORACLE_HOME/appdemo directory.

/* Assuming you are running your application demo in $ORACLE_HOME/appdemo/, */ 
/* Grant JAZN permissions to the demo to run JAZN APIs*/ 
grant codebase "file:/${oracle.ons.oraclehome}/appdemo/-" {  
   permission oracle.security.jazn.JAZNPermission "getPolicy"; 
   permission oracle.security.jazn.JAZNPermission "getRealmManager"; 
   permission oracle.security.jazn.policy.AdminPermission  
"oracle.security.jazn.realm.RealmPermission$*$createRealm,dropRealm,
  createRole, dropRole,modifyRealmMetaData";

The Java 2 Security Manager

The JAAS Provider checks permissions only when a SecurityManager has been installed. You specify a SecurityManager in one of two ways:

Calling System.setSecurityManager()
Setting the system property java.security.manager when starting OC4J

You can use either mechanism to install either the default SecurityManager or a custom UserManager.

Note:

You set system properties by using the -D command-line option in Enterprise Manager; see the Advanced Configuration chapter in the fOracle Application Server Containers for J2EE User's Guide for details.

The permissions granted to particular classes by the default SecurityManager are determined by reading a policy file. The default policy file is supplied as part of J2EE. You can specify a policy file explicitly using the system property java.security.policy, as in

    -Djava.security.policy=policyfilepath

Within an Oracle9i Application Server installation, OC4J instances run by default with no SecurityManager. If you choose to install a SecurityManager, you must specify one that does not interfere with normal OC4J functions. You can find a sample policy file at ORACLE_HOME/j2ee/home/config/java2.policy. The sample file grants "AllPermission" to most OC4J JARs. A typical block in this file looks like:

    grant codebase "file:${oracle.home}/j2ee/home/ejb.jar" {
       permission java.security.AllPermission;
    };

Note the use of "${oracle.home}" to specify the location of ORACLE_HOME. You can set oracle.home by specifying the system property:

    -Doracle.home=oraclehomepathname

Path canonicalization follows the rules of java.io.File. On UNIX, the path cannot contain any symbolic links. If you do not specify a canonical path, then the default SecurityManager will not apply the codebase specification in the policy file.

You may need to grant additional permissions to your application code and to classes generated by OC4J. The sample java2.policy file contains at the bottom a block that was required to run a demo with Java 2 security enabled. The required permissions will depend on the details of your application and the required codebase will depend on the details of your installation.

Using PrintingSecurityManager To Debug Java 2 Policy

In order to simplify the determination of what permissions need to be granted, Oracle supplies a custom SecurityManager, PrintingSecurityManager, that never throws a SecurityException. Instead, whenever a security exception would normally be thrown, PrintingSecurityManager prints messages specifying what exceptions the default SecurityManager would have thrown. To determine what permissions must be granted to your application, start OC4J using PrintingSecurityManager and execute your application.

When you run an application with the default SecurityManager, the application terminates when the first SecurityException is thrown; after you correct the first problem, you must execute the application again and again to track down all the causes of the exception. By using PrintingSecurityManager, you can create one large list of all the SecurityExceptions.

To install the PrintingSecurityManager, you must specify it on the command line that starts OC4J, as in

    -Djava.security.manager=oracle.oc4j.security.PrintingSecurityManager
    -Djava.security.policy=yourpolicypath

You must grant sufficient permissions (normally java.security.AllPermission)to oc4j.jar, which contains PrintingSecurityManager. If you have granted insufficient permissions, PrintingSecurityManager goes into an infinite loop as certain operations it performs triggers permission checks that fail. This eventually causes a StackOverflowError.

PrintingSecurityManager prints two kinds of messages on System.out. The first is

    SecurityManager would throw java.security.AccessControlException: access denied
      (java.io.FilePermission path read)

where path is the actual path of your class. This message means that the default SecurityManager would have thrown the specified exception. Whenever the PrintingSecurityManager generates such a message, it tries to determine what codesource would need to be granted the indicated Permission. If the PrintingSecurityManager succeeds in determining the needed permission, it prints a diagnostic message that looks like:

(file:path/yourclass) needs (java.io.FilePermission path read)

PrintingSecurityManager cannot completely reproduce the actions of the default SecurityManager; this means that in some cases this message is an incorrect guess.

9 Java 2 Security