Configure Java 2 policy files

The J2EE 1.3 specification has a well-defined programming model of responsibilities between the container providers and the application code. It is recommended that you use the Java 2 Security manager to help enforce this programming model. Certain operations 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 in the product to enforce responsibilities of the container and the application code.

WebSphere Application Server - Express provides support for policy file management. There are a number of policy files in the product, which are either static or dynamic. Static policy files provide default permissions. Dynamic policy files are templates of permissions for a particular type of resource. You can use relative file paths in some dynamic policy files. The absolute path is resolved when the application is deployed. For more information, see Syntax of policy files.

Dynamic policy files

These files provide the permissions for an application:

• app.policy
  This file contains the default permissions for all of the enterprise applications in the cell. For more information, see Configure the app.policy file.

• was.policy
  This file contains application-specific permissions for a WebSphere Application Server - Express enterprise application. This file is packaged within an EAR file. For more information, see Configure the was.policy file.

• ra.xml
  This file contains connector-specific permissions for a particular WebSphere Application Server - Express enterprise application. This file is packaged within a RAR file.

• spi.policy
  This file contains permissions for a service provider interface (SPI) or third-party resources that are embedded in WebSphere Application Server - Express. For more information, see Configure the spi.policy file.

• library.policy
  This file contains permissions for Java library classes that are shared by enterprise applications. By default, this file is empty. For more information, see Configure the library.policy file.

• filter.policy
  This file contains a list of permissions that are filtered out of the was.policy and app.policy files in the cell. This filtering mechanism only applies to was.policy and app.policy. For more information, see Configure the filter.policy file.

Static policy files

These files provide default permissions. If permissions are required beyond the application level, you may need to update the static policy files. Note that the static policy file is not a configuration file that is managed by the WebSphere repository and file replication service. Changes to these files are local and are not replicated to other machines.

• java.policy
  This file contains default permissions for all of the Java programs that run in the node's Java virtual machine. (On iSeries, this file is shipped with IBM Development Kit for Java.) By default, permissions are granted to all Java classes. Because this file represents permissions for all JVM processes, it is recommended that you do not modify its contents unless it is absolutely necessary. For more information, see Configure the java.policy file.

• server.policy
  This file contains default permissions for all WebSphere Application Server - Express programs on the node. By default, permissions are granted to all the product servers. Because this file represents permissions for all server processes, it is recommended that you do not modify its contents unless it is absolutely necessary. For more information, see Configure the server.policy file.

Here are some considerations when you edit Java 2 Security policy files:

• The Signed By keyword is not supported in the following policy files: app.policy, spi.policy, library.policy, was.policy, and filter.policy. However, the Signed By keyword is supported in the following policy files: java.policy and server.policy.

• The Java Authentication and Authorization Service (JAAS) principal keyword is not supported in the app.policy, spi.policy, library.policy, was.policy, and filter.policy files. However, the JAAS principal keyword is supported in a JAAS policy file when it is specified by the Java Virtual Machine (JVM) system property, java.security.auth.policy. You can statically set the authorization policy files in java.security.auth.policy with auth.policy.url.n=URL where n is an integer and URL is the location of the authorization policy.

• It is recommended that you update dynamic policy files rather than static policy files because the static policy files grant permissions beyond the application level.

• When you edit a policy file to add required permissions, it is recommended that you use the policy file of smallest scope. That way you can avoid giving a unnecessary permissions to applications, which better protects your resources. For example, update the ra.xml or was.policy file (these files define permissions for a single application) rather than the app.policy file (which defines permissions for all applications in the cell).

• Use specific component symbols, such as ${webComponent}, ${connectorComponent}, and ${jars}, rather than ${application} symbols.

• If there is any permission that should never be granted to the WebSphere Application Server - Express enterprise application within the cell, add this permission to the filter.policy file.

• After you have modified a dynamic policy file, restart the enterprise application.

• After you have modified a static policy file, restart the application server.

Troubleshooting

If a WebSphere Application Server - Express enterprise application within a cell requires permissions, some of the dynamic policy files may need to be updated. The symptom of a missing permission is a java.security.AccessControlException. For more information, see AccessControlException.

The missing permission is listed in the exception data, for example:

  java.security.AccessControlException: access denied
  (java.io.FilePermission /QIBM/ProdData/WebASE51/ASE/java/ext/mail.jar read)

When a Java program receives this exception and adding this permission is justified, add a permission to an adequate dynamic policy file, for example:

  grant codeBase "file:${application}" {
    permission java.io.FilePermission 
      "/QIBM/ProdData/WebASE51/ASE/java/ext/mail.jar", "read";
  };