+

Search Tips   |   Advanced Search

Migrate Java 2 security policy


Use this topic for guidance pertaining to migrating Java2 security policy.

Previous WAS releases

WAS uses the Java 2 security manager in the server runtime to prevent enterprise apps from calling the System.exit and the System.setSecurityManager methods. These two Java APIs have undesirable consequences if called by enterprise apps. The System.exit API, for example, causes the Java virtual machine (appserver process) to exit prematurely, which is not a beneficial operation for an application server.

To support Java 2 security properly, all the server runtime 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 that are required by the server runtime. This situation is due to the design and algorithm used by Java 2 security to enforce permission checks. Refer to the Java 2 security check permission algorithm.

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

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

However, not all WAS server runtime 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 apps is liberal.

What changed

Java 2 Security is fully supported in WAS, which means that all permissions are enforced. The default Java 2 security policy for an enterprise application is the recommended permission set defined by the Java EE Version 1.4 specification. Refer to the $WP_PROFILE/config/cells/cell_name/nodes/node_name/app.policy file for the default Java 2 security policy that is granted to enterprise apps. This policy is a much more stringent compared to previous releases.

All policy is declarative. WAS ND v7.0 security manager honors all policy that is declared in the policy files. There is an exception to this rule: enterprise applications are denied access to permissions that are declared in the $WP_PROFILE/config/cells/cell_name/filter.policy file.

The default Java 2 security policy for enterprise apps is much more stringent and all the permissions are enforced in WAS V6.0.x and later. The security policy might fail because the application code does not have the necessary permissions granted where system resources, such as file I/O, 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 WAS. If we must set a security manager in an application for RMI purposes, you also must enable the Use Java 2 security to restrict application access to local resources option on the Global security page within the WAS admin console. WAS then registers a security manager. The application code can verify that this security manager is registered by using System.getSecurityManager() API (API).

Migrate system properties

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

Migrate the Java 2 Security Policy

No easy way exists to migrate the Java policy file to WAS V 6.0.x and later automatically because of a mixture of system permissions and application permissions in the same policy file. Manually copy the Java 2 security policy for enterprise apps 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 code base is used instead of an absolute code base. This process has many advantages. Grant the permissions defined in the was.policy to the specific enterprise application only, while permissions in app.policy apply to all the enterprise applications that run on the node where app.policy belongs.

Refer to the Java 2 security policy files topic 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 for the app1.ear enterprise application and the system permissions, which are permissions that are granted to the JVM and WAS server runtime.

The default location for the Java 2 security policy file is $WP_PROFILE/properties/java.policy. Default permissions are omitted for clarity: 

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

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

 

  1. Ensure that Java 2 security is disabled on the application server.

  2. Create a new was.policy file, if the file is not present, or update the was.policy file for migrated applications in the configuration repository 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 presented on two lines for illustrative purposes only.

    The was.policy file is located in...

    $WP_PROFILE/config/cells/cell_name/applications/app.ear/deployments/app/META-INF/

  3. Use an assembly tool to attach the was.policy file to the EAR file.

    We also can use an assembly tool to validate the contents of the was.policy file.

    See Set the was.policy file for Java 2 security.

  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 ${user.install.root}/config/cells/cell_name/nodes/node_name/app.policy file. This validation requires code review, code inspection, application documentation review, and sandbox testing of migrated enterprise apps with Java 2 security enabled in a preproduction environment. Refer to developer kit APIs protected by Java 2 security for information about which APIs are protected by Java 2 security. If we 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 preproduction testing of the migrated enterprise application with Java 2 security enabled. Enable trace for the WAS Java 2 security manager in a preproduction testing environment with the following trace string: com.ibm.ws.security.core.SecurityManager=all=enabled. This trace function can be helpful in debugging the AccessControlException exception that is created 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 that are granted to the classes on the call stack when the exception is created.

    See Access control exception.

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

 

Related concepts


Assembly tools

 

Related tasks


Set the was.policy file for Java 2 security
Protecting system resources and APIs (Java 2 security)