Use PolicyTool to edit policy files for Java 2 security

The Java Development Kit provides the PolicyTool utility for updating Java 2 security policy files.

The tool verifies syntax. If there is an error when the application runs, or when the system starts, an AccessControlException exception occurs. Identifying the cause of this exception is not easy because the user might not be familiar with the resource that has an access violation. Be careful when editing these policy files.

(ZOS) To use the PolicyTool utility with WebSphere Application Server for z/OS, choose one of the following two options:

• Copy the policy files to another platform such as Microsoft Windows and modify the files. To use this option, we must issue the FTP command to transfer the files to the other platform, invoke the PolicyTool, and transfer the updated files back to the z/OS system in binary mode.

• Invoke the PolicyTool supplied with the Software Development Kit (SDK) installed on your z/OS system.

(iSeries) We must install either the client or plug-ins component of WAS on a workstation in order to access the PolicyTool. It is not currently supported on the iSeries server.

Edit Java 2 policy files 2

1. (ZOS) Invoke the PolicyTool...

   1. Export the display to an Xwindows-enabled device. For example, in Open MVS (OMVS), type...
      export DISPLAY=<IP_address_of_the_Xwindows_device>:0.0

   2. Enable the z/OS system to access the display of the Xwindows-enabled device. For example, on AIX systems, type...
      xhost + address_of_the_MVS_system

   3. Convert the policy file to the Extended Binary Coded Decimal Interchange Code (EBCDIC) format.

   4. Invoke the PolicyTool on OMVS by typing...
      $JAVA_HOME/policytool

      The JAVA_HOME variable represents the directory in which the SDK is installed.

2. (iSeries) Map a drive to the operating system to navigate the directory tree to the policy file.

3. (iSeries) (Windowss) Start the PolicyTool.
   %{was.install.root}/java/jre/bin/policytool

   The PolicyTool window opens. The tool looks for the java.policy file in your home directory. If it does not exist, an error message displays.

   Click OK.

4. Click File > Open.

5. Navigate the directory tree in the Open window to pick up the policy file needed to update. After selecting the policy file, click Open. The code base entries are listed in the window.

6. Create or modify the code base entry.

   1. Modify the existing code base entry by double-clicking the code base, or click the code base and click Edit Policy Entry. The Policy Entry window opens with the permission list defined for the selected code base.

   2. Create a new code base entry by clicking Add Policy Entry.

      The Policy Entry window opens. At the code base column, enter the code base information as a URL format.

      For example, we can enter:

      app_server_root/InstalledApps/testcase.ear

      ...where the app_server_root variable represents the installation location.

      (iSeries) For example, we can enter:

      profile_root/InstalledApps/testcase.ear

7. Modify or add the permission specification.

   1. Modify the permission specification by double-clicking the entry to modify, or by selecting the permission and clicking Edit Permission. The Permissions window opens with the selected permission information.

   2. Add a new permission by clicking Add Permission. The Permissions window opens. In the Permissions window are four rows for Permission, Target Name, Actions, and Signed By.

8. Select the permission from the Permission list. The selected permission displays. After a permission is selected, the Target Name, Actions, and Signed By fields automatically show the valid choices or they enable text input in the text input area.

   1. Select Target Name from the list, or enter the target name in the text input area.

   2. Select Actions from the list.

   3. Input Signed By if it is needed.

      The Signed By keyword is not supported in the following policy files: app.policy, spi.policy, library.policy, was.policy, and filter.policy.

      The Signed By keyword is supported in the following policy files: java.policy, server.policy, and client.policy.

      JAAS is not supported in the following policy files: app.policy, spi.policy, library.policy, was.policy, and filter.policy.

      The JAAS principal keyword is supported in a JAAS policy file when it is specified by the java.security.auth.policy JVM system property.

9. Click OK to close the Permissions window. Modified permission entries of the specified code base display.

10. Click Done to close the window. Modified code base entries are listed. Repeat the previous steps until you complete editing.

11. Click File > Save after you finish editing the file.

12. Convert the policy file back from the EBCDIC format to the ASCII format.

A policy file is updated. If any policy files need editing, use the PolicyTool utility. Do not edit the policy file manually. Syntax errors in the policy files can potentially cause application servers or enterprise applications to not start or function incorrectly. For the changes in the updated policy file to take effect, restart the Java processes.

Protecting system resources and APIs (Java 2 security) for developing applications

Configure Java 2 security policy files

Configure static policy files in Java 2 security

Java 2 security policy files