Java 2 security policy files

 

The J2EE 1.3 specification has a well-defined programming model of responsibilities between the container providers and the application code. Using Java 2 security manager to help enforce this programming model is recommended. There are certain operations that are not allowed in the application code because such operations interfere with the behavior and operation of the containers. The Java 2 security manager is used by WAS to enforce responsibilities of the container and the application code.

WAS provides support for policy file management. There are a number of policy files in the product, which are either static or dynamic. Dynamic policy is a template of permissions for a particular type of resource. There is no relative codebase defined in the dynamic policy template. The codebase is dynamically calculated from the deployment and run-time data.

 

Static policy files

Policy file Location
java.policy $WAS_HOME/java/jre/lib/security/java.policy.

Default permissions granted to all classes. The policy of this file applies to all the processes launched by the WAS.

server.policy $WAS_HOME/properties/server.policy

Default permissions granted to all the product servers.

client.policy $WAS_HOME/properties/client.policy.

Default permissions for all of the product client containers and applets on a node.

The static policy files are not managed by configuration and file replication services. Changes made in these files are local and are not replicated to other nodes in the Network Deployment cell.

 

Dynamic policy files

Policy file Location
spi.policy For Service Provider Interface (SPI) or third-party resources embedded in the product. Examples of SPI are Java Messaging Service (JMS) (MQSeries) and JDBC drivers. The codebase for the embedded resources are dynamically worked out from the configuration resources.xml(file) and run-time data, and permissions defined in the spi.policy files are automatically applied to these resources. The default permission of spi.policy file is java.security.AllPermissions.

$WAS_HOME/config/cells/cell/nodes/node/spi.policy
library.policy For the library (Java library classes). You can define a shared library to use in multiple product applications. The default permission of the library.policy is empty.

$WAS_HOME/config/cells/cell_name/nodes/node/library.policy
app.policy

The app.policy file defines the default permissions granted to all enterprise applications running on node in cell.

$WAS_HOME/config/cells/cell/nodes/node/app.policy
was.policy For application-specific permissions. The was.policy is embedded in the EAR file.

$WAS_HOME/config/cells/cellname/applications/ear_file/deployments/appname/META-INF/was.policy
ra.xml This file can have a permission specification defined in the ra.xml file. The ra.xml file is embedded in the RAR file.

rar_file_name/META-INF/was.policy.RAR.

Grant entry specified in the app.policy and was.policy files must have a code base defined. If there are grant entries specified without a code base, the policy files are not loaded properly and the application can fail. If the intent is to grant the permissions to all applications, then use file:${application} as a code base in the grant entry.

 

Syntax of the policy file

A policy file contains several policy entries. The following example depicts each policy entry format... 

grant [codebase <Codebase>] 
{
permission <Permission>;
 permission <Permission>;
permission <Permission>;
};

<CodeBase>:     A URL.
            For example,  "file:${java.home}/lib/tools.jar"
                        When [codebase <Codebase>] is not specified, listed 
               permissions are applied to everything.
                        If URL ends with a JAR file name,  only the classes in the 
               JAR file belong to the codebase.
               If URL ends with "/", only the class files in the specified
               directory belong to the codebase.
               If URL ends with "*", all JAR and class files in the specified
               directory belong to the codebase.
               If URL ends with "-", all JAR and class files in the specified 
               directory and its subdirectories belong to the codebase.
<Permissions>: Consists from
                            Permission Type      : class name of the permission
                         Target Name          : name specifying the target
                         Actions              : actions allowed on target
            For example,
                  java.io.FilePermission "/tmp/xxx", "read,write"
Refer to developer kit specifications for the details of each permission.

 

Syntax of dynamic policy

You can define permissions for specific types of resources in dynamic policy files for an enterprise application. This action is achieved by using product-reserved symbols. The reserved symbol scope depends on where it is defined. If you define the permissions in the app.policy file, the symbol applies to all the resources on all of the enterprise applications running on node. If you define the permissions in the META-INF/was.policy file, it only applies to the specific enterprise application. Valid symbols for codebase are listed in the following table...

Symbol Meaning
file:${application} Permissions apply to all resources within the application
file:${jars} Permissions apply to all utility Java archive (JAR) files within the application
file:${ejbComponent} Permissions apply to EJB resources within the application
file:${webComponent} Permissions apply to Web resources within the application
file:${connectorComponent} Permissions apply to connector resources within the application

Other than these entries specified by the codebase symbols, you can specify the module name for a granular setting. For example: 

"file:DefaultWebApplication.war" 
{
    permission java.security.SecurityPermission "printIdentity";
};

grant codeBase "file:IncCMP11.jar" {
     permission java.io.FilePermission "${user.install.root}${/}bin${/}DefaultDB${/}-", 
"read,write,delete";
};

The 6th and 7th lines in the previous code sample are one continuous line.

Use a relative codebase only in the META-INF/was.policy file.

Several product-reserved symbols are defined to associate the permission lists to a specific type of resources.

Symbol Meaning
file:${application} Permissions apply to all resources within the application
file:${jars} Permissions apply to all utility JAR files within the application
file:${ejbComponent} Permissions apply to enterprise beans resources within the application
file:${webComponent} Permissions apply to Web resources within the application
file:${connectorComponent} Permissions apply to connector resources both within the application and stand-alone connector resources.

There are five embedded symbols provided to specify the path and name for java.io.FilePermission. These symbols enable flexible permission specification. The absolute file path is fixed after the installation of the application.

Symbol Meaning
${app.installed.path} Path where the application is installed
${was.module.path} Path where the module is installed
${current.cell.name} Current cell name
${current.node.name} Current node name
${current.server.name} Current server name

You must not use the ${was.module.path} in the ${application} entry.

Carefully determine where to add a new permission. An incorrectly specified permission causes an AccessControlException exception. Since dynamic policy resolves the codebase at run time, determining which policy file has a problem is difficult. Add a permission only to the necessary resources. For example, use ${ejbcomponent}, and etc instead of ${application}, and update the was.policy file instead of the app.policy file, if possible.

 

Static policy filtering

Limited static policy filtering support exists. If the app.policy file and the was.policy file have permissions defined in the filter.policy file with the keyword, filterMask, the run time removes the permissions from the applications and an audit message is logged. However, if the permissions defined in the app.policy and was.policy are compound permissions, for example, java.security.AllPermission, the permission is not removed, rather an warning message is written to the log file. The policy filtering only supports Developer Kit permissions, (the permissions package name begins with java or javax).

Run time policy filtering support is provided to force stricter filtering. If the app.policy file and was.policy file have permissions defined in the filter.policy file with the keyword, runtimeFilterMask, the run time removes the permissions from the applications no matter what permissions are granted to the application. For example, even if a was.policy file has java.security.AllPermission granted to on of its modules, specified permissions such as runtimeFilterMask are removed from the granted permission during run time.

If the Issue Permission Warning flag in the Global Security panel is enabled and if the app.policy file and the was.policy file contain custom permissions (non-Developer Kit permissions, where the permissions package name begins with java or javax), a warning message logs. The permission is not removed. If the permission, AllPermission, is listed in the app.policy file and the was.policy file, a warning message logs.

 

Policy file editing

Using the policy tool provided by the Developer Kit ($WAS_HOME/java/jre/bin/policytool), to edit the previous policy files is recommended. For Network Deployment, extract the policy files from the repository before editing. After the policy file is extracted, use the policy tool to edit the file. Check the modified policy files into the repository and synchronized them with other nodes.

If there are syntax errors in the policy files, the enterprise application or server process might fail to start. Be very cautious when editing these policy files.

 

Troubleshoot

To debug the dynamic policy, there are three ways to generate the detail report of the exception, AccessControlException.

 

See Also

Configuring Java 2 security
Using PolicyTool to edit policy files
Java 2 security