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:

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:

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:

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.

If there are syntax errors in the policy files, the enterprise application or server process might fail to start. Be cautious when editing these policy files. For example, if a policy has a trailing space in the policy permission target name, the policy fails to parse the permission properly in WebSphere Application Server. In the following example, note the space between the third and fourth quotation marks:

grant {  permission javax.security.auth.PrivateCredentialPermission
         "javax.resource.spi.security.PasswordCredential * \"*\" ","read"; };

If the permission is in a policy file loaded by the IBM Developer Kit, Java Technology Edition Version 1.4.x policy tool, the following message might display:

Errors have occurred while opening the policy configuration.
View the warning log for more information.

or the following message might display in warning log:

Warning: Invalid argument(s) for constructor:
         javax.security.auth.PrivateCredentialPermission.

To fix this problem, edit the permission and remove the trailing space. When the trailing space is removed, the permission loads properly. The following code sample shows the corrected permission:

grant { permission javax.security.auth.PrivateCredentialPermission
        "javax.resource.spi.security.PasswordCredential * \"*\"","read"; }

For more information about the policy tool, 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: