Skip Headers

Oracle® Containers for J2EE Security Guide 10g Release 3 (10.1.3) B14429-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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

## Spe cifying 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 pe rmissions 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 PrintingSec urityManager 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