Java 2 security policy files

Java 2 security policy files

The J2EE Version 1.3 and later specifications have 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. Certain operations are not supported 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.
The application server does not support a custom Java security manager implementation.gotcha
This product provides support for policy file management. A number of policy files in the product are either static or dynamic. Dynamic policy is a template of permissions for a particular type of resource. No relative code base is defined in the dynamic policy template. The code base is dynamically calculated from the deployment and run-time data.

Static policy files

policy files.
This table lists the location of the static policy files.
Policy file Location

java.policy
(dist)(zos) app_server_root/java/jre/lib/security/java.policy. Default permissions are granted to all classes. The policy of this file applies to all the processes launched by WebSphere Application Server.
server.policy profile_root/properties/server.policy. Default permissions are granted to all the product servers.
client.policy profile_root/properties/client.policy. Default permissions are granted 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 WAS Network Deployment cell.

Dynamic policy files

policy files.
This table lists the location of the dynamic policy files.
Policy file Location

spi.policy
profile_root/config/cells/cell_name
/nodes/node/spi.policy
This template is for the Service Provider Interface (SPI) or the third-party resources that are embedded in the product. Examples of SPI are the Java Message Service (JMS) in MQ Series and Java database connectivity (JDBC) drivers. The code base for the embedded resources are dynamically determined from the configuration (resources.xml file) and run-time data, and permissions defined in the spi.policy files are automatically applied to these resources and JAR files specified in the class path of a resource adapter. The default permission of the spi.policy file is java.security.AllPermissions.
library.policy
profile_root/config/cells/cell_name/nodes
/node/library.policy
This template is for the library (Java library classes). We can define a shared library to use in multiple product applications. The default permission of the library.policy file is empty.
app.policy
profile_root/config/cells/cell_name
/nodes/node/app.policy
The app.policy file defines the default permissions that are granted to all of the enterprise applications running on node in cell_name.
Updates to the app.policy file only apply to the enterprise applications on the node to which the app.policy file belongs.
was.policy
profile_root/config/cells/cell_name
/applications/ear_file_name/deployments/
application_name/META-INF/was.policy
This template is for application-specific permissions. The was.policy file is embedded in the EAR file.
ra.xml rar_file_name/META-INF/was.policy.RAR.
This file can have a permission specification defined in the ra.xml file. The ra.xml file is embedded in the RAR file.
Grant entries specified in the app.policy and was.policy files must have a code base defined. 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, 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
We 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 we define the permissions in the app.policy file, the symbol applies to all the resources on all of the enterprise applications that run on node. If we define the permissions in the META-INF/was.policy file, the symbol applies only to the specific enterprise application. Valid symbols for the code base are listed in the following table:

valid symbols for the code base for dynamic policy files.
Symbol Meaning

file:${application} Permissions apply to all the resources within the application
file:${jars} Permissions apply to all the utility JAR files within the application
file:${ejbComponent} Permissions apply to the EJB resources within the application
file:${webComponent} Permissions apply to the web resources within the application
file:${connectorComponent} Permissions apply to the connector resources within the application
We can specify the module name for a granular setting, except for these entries specified by the code base symbols. 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";
};
The sixth and seventh lines in the previous code sample are one continuous line. We can use a relative code base 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.

table describes several product-reserved symbols defined to associate the permission lists to a specific type of resource.
Symbol Meaning

file:${application} Permissions apply to all the resources within the application
file:${jars} Permissions apply to all the utility JAR files within the application
file:${ejbComponent} Permissions apply to the enterprise beans resources within the application
file:${webComponent} Permissions apply to the web resources within the application
file:${connectorComponent} Permissions apply to the connector resources both within the application and in the standalone connector resources.
Five embedded symbols are provided to specify the path and the name for the java.io.FilePermission permission. These symbols enable flexible permission specification. The absolute file path is fixed after the installation of the application.

policy syntax.
This table describes the embedded symbols provided to specify the path and name for the java.io.FilePermission permission.
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

Do 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. Because dynamic policy resolves the code base at runtime, 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 thefilterMask keyword, the runtime removes the permissions from the applications and an audit message is logged. However, if the permissions defined in the app.policy and the was.policy files are compound permissions, for example, java.security.AllPermission, the permission is not removed, but a 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 the was.policy file have permissions defined in the filter.policy file with the runtimeFilterMask keyword, the runtime removes the permissions from the applications no matter what permissions are granted to the application. For example, even if a was.policy file has the java.security.AllPermission permission granted to one of its modules, specified permissions such as the runtimeFilterMask permission are removed from the granted permission during runtime.

Policy file editing

Use the policy tool provided by the Developer Kit (app_server_root/java/jre/bin/policytool), to edit the previous policy files is recommended. For WebSphere Application Server 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 synchronize them with other nodes.

Troubleshooting

To debug the dynamic policy, choose one of three ways to generate the detail report of the AccessControlException exception.
Trace (Configured by RAS trace). Enables traces with the trace specification:
The following command is one continuous line
com.ibm.ws.security.policy.*=all=enabled:
com.ibm.ws.security.core.SecurityManager=all=enabled
Trace (Configured by property). Specifies a Java java.security.debug property. Valid values for the java.security.debug property are as follows:

Access. Print all debug information including required permission, code, stack, and code base location.

Stack. Print debug information including, required permission, code, and stack.

Failure. Print debug information including required permission and code.

ffdc. Enable ffdc, modify the ffdcRun.properties file by changing Level=4 and LAE=true. Look for an Access Violation keyword in the log file.
Related concepts

Java 2 security

Related tasks

Protecting system resources and APIs (Java 2 security) for developing applications
Use PolicyTool to edit policy files for Java 2 security

Policy file	Location
java.policy	(dist)(zos) app_server_root/java/jre/lib/security/java.policy. Default permissions are granted to all classes. The policy of this file applies to all the processes launched by WebSphere Application Server.
server.policy	profile_root/properties/server.policy. Default permissions are granted to all the product servers.
client.policy	profile_root/properties/client.policy. Default permissions are granted for all of the product client containers and applets on a node.

Policy file	Location
spi.policy	profile_root/config/cells/cell_name /nodes/node/spi.policy This template is for the Service Provider Interface (SPI) or the third-party resources that are embedded in the product. Examples of SPI are the Java Message Service (JMS) in MQ Series and Java database connectivity (JDBC) drivers. The code base for the embedded resources are dynamically determined from the configuration (resources.xml file) and run-time data, and permissions defined in the spi.policy files are automatically applied to these resources and JAR files specified in the class path of a resource adapter. The default permission of the spi.policy file is java.security.AllPermissions.
library.policy	profile_root/config/cells/cell_name/nodes /node/library.policy This template is for the library (Java library classes). We can define a shared library to use in multiple product applications. The default permission of the library.policy file is empty.
app.policy	profile_root/config/cells/cell_name /nodes/node/app.policy The app.policy file defines the default permissions that are granted to all of the enterprise applications running on node in cell_name. Updates to the app.policy file only apply to the enterprise applications on the node to which the app.policy file belongs.
was.policy	profile_root/config/cells/cell_name /applications/ear_file_name/deployments/ application_name/META-INF/was.policy This template is for application-specific permissions. The was.policy file is embedded in the EAR file.
ra.xml	rar_file_name/META-INF/was.policy.RAR. This file can have a permission specification defined in the ra.xml file. The ra.xml file is embedded in the RAR file.

Symbol	Meaning
file:${application}	Permissions apply to all the resources within the application
file:${jars}	Permissions apply to all the utility JAR files within the application
file:${ejbComponent}	Permissions apply to the EJB resources within the application
file:${webComponent}	Permissions apply to the web resources within the application
file:${connectorComponent}	Permissions apply to the connector resources within 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