Migrate Java 2 Security policy

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

However, Java 2 Security was not a fully supported feature prior to Version 5. To support Java 2 Security properly, all of the server run time must be marked as privileged (with doPrivileged() API calls inserted in the correct places), and it must identify the default permission sets or policy. Application code is not privileged and subject to the permissions that are 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 check.

These permissions are enforced by the WebSphere Java 2 Security Manager (hard-coded):

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

Partial support has been introduced since the 4.0.2 product release. Prior to Version 4.0.2, Java 2 Security was not supported in any capacity. Starting from the 4.0.2 product release, only two permissions are supported (enforced):

However, not all of the product server run time is properly marked as privileged prior to this release. The application code has to be granted all the other permissions in addition to these, or else the enterprise application could potentially fail to run.

What changed

Java 2 Security is fully supported (but optional) in Version 5, which means that all permissions are enforced. The default Java 2 Security policy for enterprise applications is the recommended permission set that is defined by the J2EE 1.3 Specification. This is a much more stringent policy compared to previous releases.

There is no hard-coded policy, and all policy is declarative. The product Security Manager honors all policies that are declared in policy files. However, there is an exception to this rule: enterprise applications are denied access to permissions declared in the filter.policy file. For more information about policy files, see Configure Java 2 policy files.

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 its Java 2 Security policy is properly migrated. This is because the default Java 2 Security policy for enterprise applications is much more stringent and all permissions are enforced in Version 5. An enterprise application may fail because the application code does not have the necessary permissions granted where system resources (such as file input and output for example) may be programmatically accessed and are now subject to the permission checking.

Migrate system properties

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

Java 2 Security policy

There is no easy way of migrating the Java policy files from Version 4.x automatically because there is a mixture of system permissions and application permissions in the same policy files. The Java 2 Security policy for enterprise applications has to be manually copied over to a was.policy or app.policy file. However, migrating the Java 2 Security policy over to a was.policy file is a preferable way of migrating (it implies that symbols or relative codebase is used instead of absolute codebase). There are many advantages to this process, rather than migrating the permissions to the app.policy file. The permissions that are defined in the was.policy file are granted to a specific enterprise application, while permissions in the app.policy file apply to all the enterprise applications that run on the node. For more information about policy files, see Configure Java 2 policy files.

This example shows how to migrate Java 2 Security policy from previous releases. The contents include the Java 2 Security policy file (the default is the java.policy file in the properties subdirectory of the instance) for the app1.ear enterprise application, and the system permissions (permissions that are granted to the Java virtual machine and product server run time). The default permissions are omitted for clarity:

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

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

Follow these steps to migrate to Version 5.0:

  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. See Configure the was.policy file for more information.

  3. Use the Application Assembly Tool (AAT) to attach the was.policy to the EAR file. Use the AAT or the policytool that is provided by the Java development kit to validate the contents of the was.policy file. (For more information, see Create and edit policy files with the policy tool.) This step is only required for re-deploying enterprise applications prior to J2EE 1.3.

  4. It is important to validate that the enterprise application does not require more permissions than the migrated Java 2 Security permissions and the default permissions declared in the 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. For information about which Java APIs are protected by Java 2 Security, see Methods and the Permissions They Require (http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html#PermsAndMethods).

    If you use third-party libraries, consult the vendor documentation for APIs that are protected by Java 2 Security. Ensure the application is granted all the required permissions, or it may fail to run when Java 2 Security is enabled.

  5. It is very important to perform pre-production testing of the migrated enterprise application with Java 2 Security enabled.

    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.

    Because the Java 2 Security policy is much more stringent compared with previous releases, it is recommended 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.