Java 2 Security

Java 2 Security is a supported feature in WebSphere Application Server. Java 2 Security provides a policy-based, fine-grain access control mechanism that increases overall system integrity by checking for permissions before allowing access to certain protected system resources. Java 2 Security is independent of J2EE role-based authorization. Java 2 Security guards access to system resources such as file input and output, sockets, and properties, whereas J2EE security guards access to Web resources such as servlets, JSPs, and enterprise bean methods. WebSphere global security includes J2EE role-based authorization, the CSIv2 authentication protocol, and SSL configuration. Java 2 Security can be disabled and enabled independently of WebSphere global security (the Enforce Java 2 Security check box in the Global Security Panel or Server Level Security Panel). However, when WebSphere global security is enabled, by default Java 2 Security is also enabled. Note that Java 2 security can be disabled even though WebSphere Global Security may be enabled.

Because Java 2 Security is relatively new to the industry and new to WebSphere, many existing or even new applications may not be prepared for the very fine-grain access control programming model that Java 2 Security is capable of enforcing. Administrators should understand the possible consequences of enabling Java 2 Security if applications are not prepared for Java 2 Security. Java 2 Security places some new requirements on application developers and administrators.

Java 2 Security for deployers and administrators

Before you enable Java 2 Security, you need to make sure that all the applications are granted the required permissions, otherwise, applications may fail to run. By default, applications are granted the permissions recommended in the J2EE 1.3 Specification. For details of default permissions granted to applications in WebSphere, please refer to the following policy files:

• /QIBM/ProdData/Java400/jdk13/lib/security/java.policy
• /QIBM/UserData/WebAS5/product/instance/properties/server.policy
• /QIBM/UserData/WebAS5/product/instance/config/cells/cell/nodes/node/app.policy

where product is Base or ND, instance is the name of your instance, cell is the name of your cell, and node is the name of your node.

WebSphere Application Server does not support a more restrictive policy than the default one that is embodied in these policy files. This is because WebSphere may not have the necessary Java 2 Security doPrivileged APIs in place. The result of attempting to make the default policy more restrictive may result in WebSphere throwing Java 2 security access control exceptions and causing applications or WebSphere Application Server itself to fail unexpectedly.

Several policy files are used to define the security policy for Java processes. Some policy files are static (the code base is statically defined in the policy file). An example of a static policy file is the java.policy file that is provided by the Java development kit.

Other policy files are dynamic. WebSphere provides support for both static and dynamic policy files. Dynamic policy files are used with enterprise applications, resources and utility libraries. For dynamic policy files, the codebase is dynamically calculated (based on deployment information) and permissions are granted (based on template policy files) during run time.

For more information about policy files, see Configure Java 2 policy files.

If an application is not prepared for Java 2 Security, if the application provider does not provide a was.policy file as part of the application, or if the application provider does not communicate the expected permissions that should be granted to one of the WebSphere policy files, the application is likely to cause Java 2 security access control exceptions at runtime (if Java 2 Security is enabled in WebSphere) and probably runs incorrectly.

It may not be obvious that a application is or is not prepared for Java 2 security. WebSphere provides several runtime debugging aids to help determine troubleshoot applications that may be experiencing Java 2 Security-related access control exceptions.

Java 2 Security for application developers

Application developers must understand the permissions that are granted in the default WebSphere policy and the permission requirements of the Java SDK APIs. You need to know whether the APIs that your application calls requires additional permissions or not. For more information about which Java APIs require permissions, see Permissions in the Java 2 SDK (http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html).

Application providers can assume that applications are granted the necessary permissions in the default policy. Applications that access resources that are not covered by the default WebSphere policy are required to grant the additional Java 2 security permissions to the application.

While it is possible to grant the application additional permissions in one of the other dynamic WebSphere policy files or in one of the more traditional static policy files, such as java.policy, the was.policy file (which is embedded in the EAR file) ensures that the additional permissions are scoped to the exact application that requires them. If permissions are scoped to the application code that requires the permission, application code that normally does not have permission to access secured resources is not granted that permission.

If a component of an application (such as a library) is included in more than one EAR file, then the library developer should document the required Java 2 permissions that are needed by the application assembler. There is no was.policy type of file for library type components, the developer must communicate the required permissions through external documentation. If the component library is shared by multiple enterprise applications, the permissions can be granted to all enterprise applications on the node in the app.policy.

If the permission is only used internally by the component library and the application is never granted access to resources that are protected by the permission, then it may be necessary to mark the code as privileged (by inserting a doPrivileged block). (For more information, see AccessControlException.) However, improperly inserting a doPrivileged block could open up security holes, so great care and understanding should be employed when decided whether to use a doPriveleged block or not

See Configure the was.policy file for a description of how the permissions in was.policy files are granted at runtime.

Developing an application with Java 2 Security in mind may be a new skill and impose a security awareness that was not previously required of application developers. Describing the Java 2 Security model and the implications on application development is beyond the scope of this section. For more information, see The J2SDK 1.3 Security documentation (http://java.sun.com/j2se/1.3/docs/guide/security/index.html).

Debugging aids

There are two primary aids to debugging Java 2 Security:

• The WebSphere SystemOut.log file
  The AccessControl exception is logged in the SystemOut.log, and it contains the permission violation that causes the exception, the exception call stack, and the permissions that are granted to each stack frame. This information is usually enough to determine the missing permission and the code that requires the permission.

• The com.ibm.websphere.java2secman.norethrow property
  When Java 2 Security is enabled in WebSphere, by default the Security Manager component throws an java.security.AccessControl exception when a permission violation occurs. If this exception is not handled, it may cause a runtime failure. (This exception is also logged in the SystemOut.log.) However, when the com.ibm.websphere.java2secman.norethrow property is set to true, the Security Manager logs the AccessControl exception rather than throw it.

  Note: Because this property instructs the Security Manager to not throw the exception, the Security Manager is technically not enforcing Java 2 Security. The norethrow property should not be used in a production environment.

  This property is valuable in a sandbox or test environment where the application can be thoroughly tested and the SystemOut.log can be inspected for AccessControl exceptions. Because this property causes the AccessControl exception not to be thrown, the exception is not propagated up the call stack and does not cause a failure. Without this property, AccessControl exceptions would have to be found and fixed, one at a time.

Handling applications that are not ready for Java 2 Security

If you use a third-party application and the increased system integrity that is provided by Java 2 Security is important, contact the application provider to request support for Java 2 Security or, at least, to understand the additional permissions beyond the default WebSphere policy that are needed.

The easiest way to deal with applications that do not support Java 2 Security is to disable Java 2 Security in WebSphere. The downside is that this solution applies to the entire system and the integrity of the system is not as strong as it could be. This should be a consideration that is not taken lightly. In some cases, disabling Java 2 Security may be an acceptable risk.

Another approach is to leave Java 2 Security enabled but either grant only enough additional permissions or grant all permissions to only the problematic application. Determining how many permissions are enough may not be trivial. If the application provider has not communicated the required permissions in some way, then there is no easy way to determine the required permissions, so granting all permissions may be the only choice. You can minimize this risk by deploying such an application on a different node; this may help to isolate it from certain resources. Then, you can grant java.security.AllPermission in the was.policy file that is embedded in the application's EAR file, for example:

  grant codeBase "file:${application}" {
    permission java.security.AllPermission;
  };

The server.policy file

This policy defines the policy for the WebSphere classes. At present, all the server processes in the same WebSphere instance share the same server.policy file. However, it can be configured that each server process can have their own server.policy file. This can be configured by defining the desired policy file as the value of the Java system properties java.security.policy. For details of how to define Java system properties, see Configure the server.policy file.

The server.policy file should be used to define the Java 2 security policy for server resources. For enterprise application resources, use the app.policy file for node-scoped permissions or the was.policy file for application-scoped permissions.

The java.policy file

This file represents the default permissions granted to all classes. The policy of this file applies to all the processes that are launched by the Java virtual machine in which WebSphere Application Server runs. For more information, see Configure the java.policy file.

Troubleshooting

• Symptom
  Error message SECJ0314E: Current Java 2 Security policy reported a potential violation of Java 2 Security Permission. Please refer to Problem Determination Guide for further information.{0}Permission\:{1}Code\:{2}{3}Stack Trace\:{4}Code Base Location\:{5}

• Problem
  The Java Security Manager checkPermission() reported a SecurityException on the subject Permission with debugging information. The reported information can be different with respect to the system configuration. This report is enabled by configuring RAS trace into debug mode. For more information, see Use the WebSphere Application Server trace service in the Troubleshooting topic.

• Recommended response
  The reported exception may be critical to the secure system. Turn on security trace to determine the potential code that may have violated the security policy. After you determine the violating code, your should verify if the attempted operation is permitted (with respect to Java 2 Security) by examining all applicable Java 2 security policy files and the application code itself.

  Note: If the application uses Java Mail, this message may be benign. You can update the was.policy file to grant the following permissions to the application:

    permission java.io.FilePermission "${user.home}${/}.mailcap", "read"; 
    permission java.io.FilePermission "${user.home}${/}.mime.types", "read"; 
    permission java.io.FilePermission "${java.home}${/}lib${/}mailcap", "read"; 
    permission java.io.FilePermission "${java.home}${/}lib${/}mime.types", "read";

  Note: If the application uses the getResourceAsStream(foo) method of the ClassLoader class where foo is some file name, this message may be benign. You can update the was.policy file to grant the following permission to the application (or update the app.policy file to grant the permission to all applications on node):

    permission java.io.FilePermission "/QIBM/ProdData/Java400/foo", "read";

Messages

• Message: SECJ0313E: Java 2 Security Manager debug message flags are initialized: TrDebug: {0}, Access: {1}, Stack: {2}, Failure: {3}
  Problem: Configured values of the valid debug message flags for Security Manager.
  Recommended response: None.

• Message: SECJ0307E: Unexpected exception is caught when trying to determine the code base location. Exception: {0}
  Problem: An unexpected exception is caught when the code base location is being determined.
  Recommended response: Please contact an IBM representative.