4 Java VM Security Settings for OC4J

This chapter discusses tasks related to configuring the security system at the OC4J instance level. It contains the following topics:

• Specifying an Alternate JAAS Policy Provider

• Specifying a Java 2 Security Manager and Policy File

• Enabling Subject Propagation for ORMI

Note: Set system properties by using the -D command-line option when starting OC4J, as described in the Oracle Containers for J2EE Configuration and Administration Guide.

Specifying an Alternate JAAS Policy Provider

If you use the Java virtual machine shipped with Oracle Application Server, the OracleAS JAAS Provider is automatically specified as the JAAS policy provider. If you use another JVM, you must explicitly specify oracle.security.jazn.spi.PolicyProvider as the policy provider, because by default, the JVM uses the Sun Microsystems JAAS provider.

Note: When you use OC4J, the JAAS configuration properties are set by default during OC4J startup, so in most circumstances there is no need to worry about setting these properties. You set them only when you are running a J2SE application outside OC4J.

You can specify Oracle-specific JAAS properties in a separate file that you supply to the JVM when you run OC4J.

Oracle supplies a default file, ORACLE_HOME/j2ee/home/config/jazn.security.props, that specifies the OracleAS JAAS Provider.

• To replace all security properties with the Oracle properties (note the two equals signs, "=="):

  java -Djava.security.properties==propfile
  
  

• To append the Oracle-specific properties to existing security properties:

  java -Djava.security.properties=propfile
  

Specifying a Java 2 Security Manager and Policy File

The OracleAS JAAS Provider checks permissions only when a security manager (java.lang.SecurityManager instance) has been installed. Specify a security manager in one of two ways:

• Calling System.setSecurityManager()

• Setting the system property java.security.manager when starting OC4J (or using this property with no setting to use the standard default security manager)

You can use either mechanism to install the default security manager or a custom security manager.

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

    -Djava.security.policy=policyfilepath

Within an Oracle Application Server installation, OC4J instances run by default with no security manager. If you choose to install a security manager, you must specify one that does not interfere with normal OC4J functions.

The following example starts OC4J with the default security manager:

% java -Doracle.home=ORACLE_HOME -Djava.security.manager \
       -Djava.security.policy=ORACLE_HOME/j2ee/home/config/java2.policy \
       -jar oc4j.jar

See the following subsections for related information:

• Creating a Java 2 Policy File

• Using PrintingSecurityManager to Debug Java 2 Policy

See Also: "Security Managers and Access Control" for an overview of security managers

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.

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 JAAS 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 JAAS permissions to the demo to run JAAS 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;
}

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=ORACLE_HOME

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 security manager 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

To assist you in identifying all the required permissions for an application running on OC4J, Oracle provides a custom security manager, PrintingSecurityManager, that does not throw security exceptions. Instead, it prints a message specifying what exceptions the default security manager would have thrown. PrintingSecurityManager also generates the policy grants that would avoid the security exceptions.

Run PrintingSecurityManager as follows, assuming you run OC4J from ORACLE_HOME/j2ee/home:

% java -Xbootclasspath/p:lib/oc4j-psm.jar -Doracle.home=ORACLE_HOME \
   -Djava.security.manager=oracle.oc4j.security.PrintingSecurityManager \
   -Djava.security.policy=ORACLE_HOME/j2ee/home/config/java2.policy -jar oc4j.jar

(-Xbootclasspath puts PrintingSecurityManager into the boot classpath, where it runs with all the permissions.)

PrintingSecurityManager generates output that lists the following:

• Which code source requires which permissions

• A policy grant that you can copy and paste into the policy file

By default, these outputs go to System.out, but you can specify output files through the following system properties, the first for messages about missing permissions, and the second for policy grants:

-Doracle.oc4j.security.manager.printing.file=filenamepath
-Doracle.oc4j.security.manager.printing.generated.grants.file=filenamepath

Note: PrintingSecurityManager is not tied to OC4J, so you can use it outside of OC4J.

Enabling Subject Propagation for ORMI

Subject propagation is always used in OC4J with IIOP, in accordance with the CSIv2 specification. It is also used with ORMI if you specifically enable it on the client and server. You can accomplish this with the following system property setting at each end:

-Dsubject.propagation=true

In the current release, this setting controls subject propagation at a global OC4J level.

See Also: "Enabling and Configuring Subject Propagation for ORMI" for complete information about subject propagation in OC4J