Migrating Java 2 security policy

Why and when to perform this task

Previous WebSphere Application Server releases

Starting from Version 3.x, WebSphere Application Server installed a Java 2 security manager in the server run time to prevent enterprise applications from calling the System.exit() and the System.setSecurityManager() methods. These two Java APIs have undesirable consequences if called by enterprise applications. The System.exit() API, for example, causes the Java virtual machine (application server process) to exit prematurely, which is an undesirable operation for an application server.

However, Java 2 security was not a fully supported feature prior to Version 5. To support Java 2 security properly, all the server run time must be marked as privileged (with doPrivileged() API calls inserted in the correct places), and identify the default permission sets or policy. Application code is not privileged and subject to the permissions defined in the policy files. The doPrivileged instrumentation is important and necessary to support Java 2 security. Without it, the application code must be granted the permissions required by the server run time. This is due to the design and algorithm used by Java 2 security to enforce permission checks. Please refer to the Java 2 security check permission algorithm.

The following two permissions are enforced by the WebSphere Java 2 security manager (hard coded):

Application code is denied access to these permissions regardless of what is in the Java 2 security policy. However, the server run time is granted these permissions. All the other permission checks are not enforced.

Partial support was introduced since the version 4.02 product release. Prior to version 4.0.2, Java 2 security was not supported. From version 4.02 and later, only two permissions are supported:

However, not all the product server run time is properly marked as privileged. You must grant the application code all the other permissions besides the two listed previously or the enterprise application can potentially fail to run. This Java 2 security policy for enterprise applications is liberal.

What changed

Java 2 Security is fully supported in version 5, which means all permissions are enforced. The default Java 2 security policy for enterprise application is the recommended permission set defined by the J2EE 1.3 specification. Refer to the ${install_root}/config/cells/cell_name/nodes/node_name/app.policy file for the default Java 2 security policy granted to enterprise applications. This is a much more stringent policy compared to previous releases.

All policy is declarative. The product security manager honors all policy declared in the policy files. There is an exception to this rule: enterprise applications are denied access to permissions declared in the ${install_root}/config/cells/cell_name/filter.policy file.

Note: Enterprise applications that run on Version 4.0.x with Java 2 security enabled are not guaranteed to run successfully when migrating to Version 5 (when Java 2 security is enabled), even if the Java 2 security policy is migrated properly. The default Java 2 security policy for enterprise applications is much more stringent and all permissions are enforced in Version 5. It might fail because the application code does not have the necessary permissions granted where system resources (such as file I/O for example) can be programmatically accessed and are now subject to the permission checking.

In application code, do not use the setSecurityManager permission to set a security manager. When an application uses the setSecurityManager permission, there is a conflict with the internal security manager within WebSphere Application Server. If you must set a security manager in an application for RMI purposes, you also must enable the Enforce Java 2 Security option on the Global security settings page within the WebSphere Application Server administrative console. WebSphere Application Server then registers a security manager. The application code can verify that this security manager is registered by using System.getSecurityManager() application programming interface (API).

Migrating system properties

The following system properties are used in previous releases in relation to Java 2 security:

Migrating the Java 2 Security Policy

There is no easy way of migrating the Java policy file from Version 4.0.x automatically because there is a mixture of system permissions and application permissions in the same policy file. Manually copy the Java 2 security policy for enterprise applications to a was.policy or app.policy file. However, migrating the Java 2 security policy to a was.policy file is preferable because symbols or relative codebase is used instead of absolute codebase. There are many advantages to this process. The permissions defined in the was.policy file should only be granted to the specific enterprise application, while permissions in the app.policy file apply to all the enterprise applications running on the node where the app.policy file belongs. Refer to the Java 2 security policy files article for more details on policy management.

The following example illustrates the migration of a Java 2 security policy from a previous release. The contents include the Java 2 security policy file (the default is install_root/properties/java.policy) for the app1.ear enterprise application and the system permissions (permissions granted to the JVM and product server run time). Default permissions are omitted for clarity:

// For product Samples
   grant codeBase "file:${install_root}/installedApps/app1.ear/-" {
     permission java.security.SecurityPermission "printIdentity";
     permission java.io.FilePermission "${install_root}${/}temp${/}somefile.txt", 
       "read";
   };

For clarity of illustration, all the permissions are migrated as the application level permissions in this example. However, you can grant permissions at a more granular level at the component level (Web, enterprise beans, connector or utility Java archive (JAR) component level) or you can grant permissions to a particular component.

Steps for this task

  1. Ensure that Java 2 security is disabled on the application server.
  2. Create a new was.policy file (if one is not present) or update the was.policy for migrated applications in the configuration repository in (config/cells/<cell_name>/applications/app.ear/deployments/app/META-INF/was.policy) with the following contents:
    grant codeBase "file:${application}" {
         permission java.security.SecurityPermission "printIdentity";
         permission java.io.FilePermission "
                 ${user.install.root}${/}temp${/}somefile.txt", "read";
       };

    The third and fourth lines in the previous code sample are one continuous line, but extended beyond the width of the page.

  3. [5.0 only][Version 5.0.1][Version 5.0.2]Use the Application Assembly Tool (AAT) to attach the was.policy to the enterprise archive (EAR) file. You can use the AAT or the policy tool provided by the Software Developer Kit to validate the contents of the was.policy file.
    In the Application Assembly Tool, complete the following steps to attach the policy file to the EAR:
    1. Expand the Enterprise Archive (EAR) file.
    2. Right-click Files.
    3. Click Add Files.
    4. Click Browse to select the was.policy file.
  4. Validate that the enterprise application does not require additional permissions to the migrated Java 2 Security permissions and the default permissions set declared in the ${was.install.root}/config/cells/cell_name/nodes/node_name/app.policy file. This requires code review, code inspection, application documentation review, and sandbox testing of migrated enterprise applications with Java 2 security enabled in a pre-production environment. Refer to developer kit APIs protected by Java 2 security for information about which APIs are protected by Java 2 security. If you use third party libraries, consult the vendor documentation for APIs that are protected by Java 2 security. Verify that the application is granted all the required permissions, or it might fail to run when Java 2 security is enabled.
  5. Perform pre-production testing of the migrated enterprise application with Java 2 security enabled.
    Hint: Enable trace for the WebSphere Application Server Java 2 security manager in the pre-production testing environment (with trace string: com.ibm.ws.security.core.SecurityManager=all=enabled). This can be helpful in debugging the AccessControlException exception thrown when an application is not granted the required permission or some system code is not properly marked as privileged. The trace dumps the stack trace and permissions granted to the classes on the call stack when the exception is thrown. For more information, see AccessControlException.

    Note: Because the Java 2 security policy is much more stringent compared with previous releases, it is strongly advised that the administrator or deployer review their enterprise applications to see if extra permissions are required before enabling Java 2 security. If the enterprise applications are not granted the required permissions, they fail to run.


Related tasks
Configuring Java 2 security
Configuring the was.policy file



Searchable topic ID:   tsecmigratejava2sec
Last updated: Jun 21, 2007 8:07:48 PM CDT    WebSphere Business Integration Server Foundation, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.wasee.doc/info/ee/ae/tsec_migratejava2sec.html

Library | Support | Terms of Use | Feedback