165 lines
10 KiB
HTML
165 lines
10 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<LINK rel="stylesheet" type="text/css" href="../../../rzahg/ic.css">
|
||
|
|
|
||
|
|
<title>Syntax of policy files</title>
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<BODY>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<SCRIPT LANGUAGE="Javascript" SRC="../../../rzahg/synch.js" TYPE="text/javascript"></SCRIPT>
|
||
|
|
|
||
|
|
<h5><a name="secj2syn"></a>Syntax of policy files</h5>
|
||
|
|
|
||
|
|
<p>This topic describes the syntax of Java 2 Security policy files that are supported by WebSphere Application Server - Express.</p>
|
||
|
|
|
||
|
|
<p><strong>Syntax of the policy file</strong></p>
|
||
|
|
|
||
|
|
<p>A policy file contains several policy entries. The format of each policy entry follows a specific format:</p>
|
||
|
|
|
||
|
|
<pre> grant [codebase <em>Codebase</em>] {
|
||
|
|
permission <em>Permission</em>;
|
||
|
|
permission <em>Permission</em>;
|
||
|
|
permission <em>Permission</em>;
|
||
|
|
};</pre>
|
||
|
|
|
||
|
|
<p>where these variables are used:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><p><strong><em>Codebase</em></strong>
|
||
|
|
<br>This is a URL. For example: <tt>"file:${java.home}/../lib/tools.jar"</tt></p>
|
||
|
|
|
||
|
|
<p>Usage:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If <tt>[codebase <em>Codebase</em>]</tt> is not specified, listed permissions are applied to everything.</li>
|
||
|
|
<li>If the URL ends with a JAR file name, only the classes in the JAR file belong to the codebase.</li>
|
||
|
|
<li>If the URL ends with "<tt>/</tt>", only the class files in the specified directory belong to the codebase.</li>
|
||
|
|
<li>If the URL ends with "<tt>*</tt>", all JAR and class files in the specified directory belong to the codebase.</li>
|
||
|
|
<li>If the URL ends with "<tt>-</tt>", all JAR and class files in the specified directory and its subdirectories belong to the codebase.</li>
|
||
|
|
</ul><p></p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> A <tt>grant</tt> 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 <tt>file:${application}</tt> as a code base in the grant entry.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong><em>Permissions</em></strong>
|
||
|
|
<br>A permission is defined with these pieces of information:</p>
|
||
|
|
<ul>
|
||
|
|
<li>A permission type, which is the class name of the permission.</li>
|
||
|
|
<li>A target name, which specifies the target.</li>
|
||
|
|
<li>Actions, which specify the actions that are allowed to be performed upon the target.</li>
|
||
|
|
</ul>
|
||
|
|
<p>Here is an example of a permission entry: <tt>java.io.FilePermission "/tmp/xxx", "read,write"</tt></p>
|
||
|
|
|
||
|
|
<p>For details about the permissions, see <a href="http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html" target="_">Permissions in the Java 2 SDK</a> <img src="www.gif" width="19" height="15" alt="Link outside Information Center"> (http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html)</p></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><strong>Syntax of dynamic policy files</strong></p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>This list contains the valid symbols for the codebase entry:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><p><strong><tt>file:${application}</tt></strong>
|
||
|
|
<br>Permissions apply to all resources within the application.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong><tt>file:${jars}</tt></strong>
|
||
|
|
<br>Permissions apply to all utility JAR files within the application.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong><tt>file:${webComponent}</tt></strong>
|
||
|
|
<br>Permissions apply to Web resources within the application.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong><tt>file:${connectorComponent}</tt></strong>
|
||
|
|
<br>Permissions apply to connector resources both within the application and stand alone connector resources.</p></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>For a more granual setting, you can specify a particular module name. For example:</p>
|
||
|
|
|
||
|
|
<pre> 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";
|
||
|
|
};</pre>
|
||
|
|
|
||
|
|
<p>A relative codebase can be used only in the was.policy file.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>Here are the embedded symbols that are supported:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><p><strong><tt>${app.installed.path}</tt></strong>
|
||
|
|
<br>Path where the application is installed.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong><tt>${was.module.path}</tt></strong>
|
||
|
|
<br>Path where the module is installed.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong><tt>${current.cell.name}</tt></strong>
|
||
|
|
<br>Current cell name.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong><tt>${current.node.name}</tt></strong>
|
||
|
|
<br>Current node name.</p></li>
|
||
|
|
|
||
|
|
<li><p><strong><tt>${current.server.name}</tt></strong>
|
||
|
|
<br>Current server name.</p></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> The <tt>${was.module.path}</tt> symbol cannot be used in the <tt>${application}</tt> entry.</p>
|
||
|
|
|
||
|
|
<p>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 <tt>${webComponent}</tt> instead of <tt>${application}</tt>, and update the was.policy file instead of the app.policy file, if possible.</p>
|
||
|
|
|
||
|
|
<p><strong>Filtering static policies</strong></p>
|
||
|
|
|
||
|
|
<p>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 <tt>java</tt> or <tt>javax</tt>.</p>
|
||
|
|
|
||
|
|
<p>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 <tt>runtimeFilterMask</tt>, 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.</p>
|
||
|
|
|
||
|
|
<p>If <strong>Issue Permission Warning</strong> 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 <tt>java</tt> or <tt>javax</tt>), 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.</p>
|
||
|
|
|
||
|
|
<p><strong>Editing policy files</strong></p>
|
||
|
|
|
||
|
|
<p>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 <tt>bin</tt> subdirectory) to edit the policy files.</p>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<pre>grant { permission javax.security.auth.PrivateCredentialPermission
|
||
|
|
"javax.resource.spi.security.PasswordCredential * \"*\" ","read"; };</pre>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<pre>Errors have occurred while opening the policy configuration.
|
||
|
|
View the warning log for more information.</pre>
|
||
|
|
|
||
|
|
<p>or the following message might display in warning log:</p>
|
||
|
|
|
||
|
|
<pre>Warning: Invalid argument(s) for constructor:
|
||
|
|
javax.security.auth.PrivateCredentialPermission.</pre>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<pre>grant { permission javax.security.auth.PrivateCredentialPermission
|
||
|
|
"javax.resource.spi.security.PasswordCredential * \"*\"","read"; }</pre>
|
||
|
|
|
||
|
|
<p>For more information about the policy tool, see <a href="seccupol.htm">Create and edit policy files with the policy tool</a>.</p>
|
||
|
|
|
||
|
|
<p><strong>Troubleshooting</strong></p>
|
||
|
|
|
||
|
|
<p>To debug the dynamic policy, you can use these ways to generate the detail report of the AccessControlException exception:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><p>Enable tracing with the trace specification: <tt>com.ibm.ws.security.policy.*=all=enabled:com.ibm.ws.security.core.SecurityManager=all=enabled</tt></p></li>
|
||
|
|
|
||
|
|
<li><p>Enable first-fail data capture (FFDC). Modify the ffdcRun.properties file and specify <tt>Level=4</tt> and <tt>LAE=true</tt>. Look for a keyword <strong>Access Violation</strong> in the log file.</p></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|