Syntax of policy files

This topic describes the syntax of Java 2 Security policy files that are supported by WebSphere Application Server - Express.

Syntax of the policy file

A policy file contains several policy entries. The format of each policy entry follows a specific format:

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

where these variables are used:

• Codebase
  This is a URL. For example: "file:${java.home}/../lib/tools.jar"

  Usage:

  • If [codebase Codebase] is not specified, listed permissions are applied to everything.
  • If the URL ends with a JAR file name, only the classes in the JAR file belong to the codebase.
  • If the URL ends with "/", only the class files in the specified directory belong to the codebase.
  • If the URL ends with "*", all JAR and class files in the specified directory belong to the codebase.
  • If the URL ends with "-", all JAR and class files in the specified directory and its subdirectories belong to the codebase.

  Note: A grant entry that is specified in the app.policy and was.policy files must have a defined code base. If grant entries are 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.

• Permissions
  A permission is defined with these pieces of information:

  • A permission type, which is the class name of the permission.
  • A target name, which specifies the target.
  • Actions, which specify the actions that are allowed to be performed upon the target.

  Here is an example of a permission entry: java.io.FilePermission "/tmp/xxx", "read,write"

  For details about the permissions, see Permissions in the Java 2 SDK (http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html)

Syntax of dynamic policy files

You can define permissions for specific types of resources in dynamic policy files for an enterprise application. You do this by using product-reserved symbols in the policy files.

The scope of the reserved symbol 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 that run in the node. If you define the permissions in the META-INF/was.policy file in your assembled application, it only applies to the specific enterprise application.

This list contains the valid symbols for the codebase entry:

• file:${application}
  Permissions apply to all resources within the application.

• file:${jars}
  Permissions apply to all utility JAR files 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.

For a more granual setting, you can specify a particular module name. For example:

  grant codebase "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";
  };

A relative codebase can be used only in the was.policy file.

There are embedded symbols provided that specify the path and name for java.io.FilePermission. These symbols enable you to specify more flexible permissions. The absolute file path is not fixed until after the application has been installed.

Here are the embedded symbols that are supported:

• ${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.

Note: The ${was.module.path} symbol cannot be used in the ${application} entry.

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

Filtering static policies

The policy model supports some limited static policy filtering. If the app.policy file and the was.policy file have permissions that are defined in filter.policy file, the run time removes the permissions from the applications and an audit message is logged. However, if the permissions defined in app.policy and was.policy are compound permissions (for example, java.security.AllPermission), the permission is not removed, and a warning message is written to the log file. Policy filtering only supports packages whose names begin with java or javax.

Run time policy filtering support is provided to force filtering that is more strict. If the app.policy file and was.policy file have permissions that are defined in the filter.policy file with the keyword runtimeFilterMask, the run time removes the permissions from the applications no matter which permissions are granted to the application. For example, even if a was.policy file grants java.security.AllPermission permission to a module, the specified permissions (such as runtimeFilterMask) are removed from the granted permission during run time.

If Issue Permission Warning is enabled in the Global Security panel of the administrative console and if the app.policy file and the was.policy file contain custom permissions (for packages that do not begin with java or javax), a warning message is logged and the permission is not removed. If the AllPermission permission is listed in both the app.policy file and the was.policy file, a warning message is logged.

Editing policy files

It is recommended that you use the policy tool (policytool) that is provided with the IBM Developer Kit for Java or the Sun Microsystems Java 2 Software Development Kit (in the bin subdirectory) to edit the policy files.

Note: If there are syntax errors in the policy files, the enterprise application or server process may fail to start. Extreme care should be taken when editing these policy files.

For more information, see Create and edit policy files with the policy tool.

Troubleshooting

To debug the dynamic policy, you can use these ways to generate the detail report of the AccessControlException exception:

• Enable tracing with the trace specification: com.ibm.ws.security.policy.*=all=enabled:com.ibm.ws.security.core.SecurityManager=all=enabled

• Enable first-fail data capture (FFDC). Modify the ffdcRun.properties file and specify Level=4 and LAE=true. Look for a keyword Access Violation in the log file.