Security Managers and the JavaTM 2 SDK

The original Link :

http://download.oracle.com/javase/1.4.2/docs/guide/security/smPortGuide.html

Security Managers and the Java^TM 2 SDK

Last Modified: 1 May, 2001

 

---

Introduction

This document describes changes made to the security manager in the Java 2 SDK that allow it to be used as-is as the default security manager in applications.

Security Model Evolution

In JDK 1.1, local applications and correctly digitally signed applets were generally trusted to have full access to vital system resources, such as the file system, while unsigned applets were not trusted and could access only limited resources. A security manager was responsible for determining which resource accesses were allowed.

The Java 2 SDK security architecture is policy-based, and allows for fine-grained access control. When code is loaded, it is assigned "permissions" based on the security policy currently in effect. Each permission specifies a permitted access to a particular resource, such as "read" and "write" access to a specified file or directory, or "connect" access to a given host and port. The policy, specifying which permissions are available for code from various signers/locations, can be initialized from an external configurable policy file. Unless a permission is explicitly granted to code, it cannot access the resource that is guarded by that permission. These new concepts of permission and policy enable the SDK to offer fine-grain, highly configurable, flexible, and extensible access control. Such access control can now not only be specified for applets, but also for all Java code, including applications, beans, and servlets.

For more information on the Java 2 SDK security architecture, please see the security documentaton.

Security Manager Evolution

Security Manager Methods

In both JDK 1.1 and the Java 2 SDK, the SecurityManager class contains many methods with names that begin with the word check. Examples are checkRead and checkConnect. Various methods in the Java libraries call a check method before performing each potentially security-sensitive operation. The security manager is thereby given an opportunity to prevent completion of the operation by throwing an exception. A security manager routine simply returns if the operation is permitted, but throws a SecurityException if the operation is not permitted. The only exception to this convention is checkTopLevelWindow, which returns a boolean value.

The other main type of methods contained in the SecurityManager class are those related to class loader existence and depth:

·         currentClassLoader

·         currentLoadedClass

·         inClassLoader

·         classLoaderDepth

Security Managers in JDK 1.1

In JDK 1.1, the class java.lang.SecurityManager was an abstract class. The default implementations of the security manager check methods threw exceptions. The class loader and depth-related classes were appropriately implemented, often in native code.

Any application (such as a browser) that wanted to install a security manager had to write their own, providing appropriate concrete implementations of the methods that threw exceptions by default -- primarily the check methods.

Security managers based on the JDK 1.1 applet security manager model typically based access control decisions on two things:

1.  Whether or not a class with a class loader (i.e., an applet in JDK 1.1) was on the stack.

2.  The class loader depth -- how far down the stack was the most recent occurrence of a method from a class defined using a class loader.

These types of decisions were made by calling the SecurityManager methods related to class loader existence and depth. For example, a typical 1.1-style security manager might have a checkExit method like the following:

     public void checkExit(int status) {

       if (inClassLoader()) {

        throw new SecurityException(..);

       }

     }

Such a checkExit method would not allow Runtime.exit to be called when any class defined with a class loader (an applet) was on the stack. This is an example of the first case, checking whether or not a class with a class loader is on the stack. An example of the second case (class loader depth) would be something like:

      public void checkCreateClassLoader() {

         if (classLoaderDepth() == 2) {

            throw new SecurityException();

         }

      }

This method is saying that the class loader depth can't be 2. That is, the method that called the method that called checkCreateClassLoader must not be in a class defined with a class loader. For example, the constructor for java.lang.ClassLoader calls checkCreateClassLoader, which means the method that calls the constructor for java.lang.ClassLoader must not have a class loader. This means applets can't directly create class loaders.

Note that there is a big difference between the two methods, even though both attempt to prevent applets from performing actions. In the first case, checkExit will throw an exception if an applet is anywhere on the stack. That means even built-in JDK code can't exit the VM if it was called from an applet. In the second case, JDK code is allowed to create a class loader, even if it was called by an applet. That is because the depth of a class with a class loader is used, and not the fact that there is one.

Security Managers in the Java 2 SDK

In the Java 2 SDK, the class java.lang.SecurityManager had a number of changes made to it in order to allow it to be used as the default security manager for applications. In particular:

·         It is no longer an abstract class, and can thus be installed as-is.

·         Most check methods call a new checkPermission method, which by default calls the method of the same name (checkPermission) in the new AccessController class. Those methods that don't call checkPermission have reasonable defaults.

·         Methods used in JDK 1.1 to determine if a class loader is on the stack and/or to calculate class loader depth have been modified in the Java 2 SDK to ignore system class loaders and security contexts that have been granted java.security.AllPermission.

Installing java.lang.SecurityManager as the Default Security Manager

Since java.lang.SecurityManager is no longer abstract, you can install and use it as the default security manager. You can do this by setting a system property when launching the VM:

    java -Djava.security.manager YourApp

Alternatively, your application can install it directly via the following line of code:

    System.setSecurityManager(new SecurityManager());

You can customize the behavior of the default security manager by modifying policy files. See the security guide on policy files for more information.

Changes to Methods For Class Loaders And Class Loader Depth

In the Java 2 SDK, the SecurityManager methods related to class loaders and class loader depth are not called by any of the check methods, and they are deprecated. They should not be used by any new security managers, and it is recommended that their use be eliminated from existing security managers as well. However, they are left in for backward compatibility and they have been modified in an attempt to enable old 1.1-style security managers to still work under the Java 2 SDK, without modification.

These methods are:

·         currentClassLoader

·         currentLoadedClass

·         inClassLoader

·         classLoaderDepth

Modification of Class Loader/Depth-related Methods

The class loader/depth related methods have all been modified in three ways:

1.  These methods skip system class loaders. A system class loader is defined as being a class loader that is equal to the system class loader (as returned by ClassLoader.getSystemClassLoader) or one of its ancestors.

Since classes loaded by the system class loader include application classes (loaded off of CLASSPATH), extension classes, and the built-in SDK classes, this modification enables these methods to ignore such code.

Note that if you run an application that installs a custom security manager, and that security manager is loaded off of CLASSPATH in the Java 2 SDK, it will have a system class loader associated with it. (Application classes did not have a class loader in JDK 1.1.) If you were to call a method like classLoaderDepth from within the custom security manager, and that method were not modified to ignore classes loaded by a system class loader, it would always return 0, which would not be very useful. Similarly, if class loader methods weren't changed to skip system classes and a custom security manager was loaded off of CLASSPATH, then this might also open up security holes in cases where the security manager is making decisions based on, for example, disallowing an operation if "classLoaderDepth() == 2". (It should really be "classLoaderDepth() <= 2".)

2.  These methods stop checking after they reach a method on the stack that has been marked as "privileged." (See java.security.AccessController.doPrivileged() and API for Privileged Blocks.)

3.  These methods treat security contexts that have been granted AllPermission as if there is no class loader on the stack.

As an example of the use of the first two modifications, note that there are now places in the SDK that open files, etc., after a security manager has been installed. Some 1.1-style security managers have a checkRead method that looks like the following:

       public void checkRead(String file) {

         if (inClassLoader()) {

          throw new SecurityException(..);

         }

       }

Without SDK code modifications, such a check run in the Java 2 SDK would cause a security exception to be thrown when the SDK itself tries to read a file and there is a class with a non-system class loader on the stack. With the new security model, all such SDK code that tries to perform an operation that its caller might not be allowed to do has a doPrivileged block around it. Since inClassLoader just examines the stack up to and including the frame containing the "privileged" code, and the code at the top of the stack is SDK code, which is loaded by the system class loader or one of its ancestors, the inClassLoader method will return false, allowing the read to occur.

Maintenance of Class Loader Depths

As noted previously, security managers based on the 1.1 applet security manager based some of their access control decisions on class loader depth. As an example, the checkCreateClassLoader method previously presented is repeated here:

       public void checkCreateClassLoader() {

          if (classLoaderDepth() == 2) {

             throw new SecurityException();

          }

       }

In the Java 2 SDK we have attempted to maintain the stack depth as used in 1.1-style security managers. For example, the constructor for java.security.SecureClassLoader has an explicit call to SecurityManager.checkCreateClassLoader even though the constructor for its super class (ClassLoader) also does. If the check was not placed in the constructor for SecureClassLoader, then a 1.1-style security manager would allow untrusted code to extend SecureClassLoader and construct class loaders, as the class loader depth would always be greater than 2.

How to Port 1.1-Style Security Managers

First and foremost, we highly recommend analyzing all your custom security manager methods before running your security manager under the Java 2 SDK. Failure to do so could result in a security hole or prevent the proper operation of the SDK. This is due to the fragile nature of 1.1-style security managers.

Where possible, you should just use the default implementation of the 1.2 SecurityManager. This helps give users and administrators consistent behavior. If this is not possible, then you should at least try to call super.checkXXX in your checkXXX method before throwing a security exception. Doing so will allow the access controller algorithm to be used, and will allow the SDK itself to function correctly.

In the Java 2 SDK, any existing code that used to call any of the SecurityManager check methods continues to do so. For new code that requires a security check, calls are made to SecurityManager.checkPermission instead of adding a new SecurityManager check method. For example, the new java.lang.System.setProperty method calls checkPermission with a java.util.PropertyPermission permission.

When extending the SecurityManager class and overriding existing methods, some care should be taken. For example, if you override the checkRead(String file) method so it always throws a security exception, then the SDK itself may fail to operate properly. That is, if some SDK code needs to open a file (to read a properties file, load a JAR file, etc.) then throwing a security exception for every read attempt would cause such opens to always fail.

In general, you should only override the default methods if you intend to loosen security, not to make it stronger. If you want to tighten security, you should modify the default policy files and/or install a custom java.security.Policy object. See the security guide on policy files for more information.

In general, when overriding security manager methods you should place a call to the super.checkXXX method at the point where your overridden checkXXX method would throw an exception. For example:

      public class MySecurityManager extends SecurityManager {

 

        public void checkRead(String file) {

          if (someCustomSecurityCheckFails()) {

             super.checkRead(file);

          }

        }

      }

   

If your custom security check fails, then super.checkRead gets called. The default implementation of checkRead invokes checkPermission, which by default consults the AccessController. By invoking the AccessController, system code that has done an AccessController.doPrivileged before trying to read a file will succeed in reading that file. All other code will be subjected to the current policy in effect, and an access control exception will be thrown if access to that file has not been granted.

Note, there are some checkXXX methods in which you should not call super.checkXXX methods when overriding them. That is because the default implementation of these methods may not be as strict as the policy you are implementing in the overridden method. For example, the default checkAccess(ThreadGroup g) method only protects the system thread group. If you intend to protect threads in distinct thread groups from each other (for example applet thread groups), then you would not want to call super.checkAccess at the point you would normally throw a security exception, as that would defeat the purpose of your customized check. Instead, you could place a call to super.checkAccess as the first statement in your overridden method.

For example:

      public class AppletSecurityManager extends SecurityManager {

 

        public void checkAccess(ThreadGroup g) {

          // a call to super will throw an exception if someone

          // is trying to modify the system thread group

          super.checkAccess(g);

          ...

          // now perform checks based on which applet thread group

          // the current caller is in to see if they can modify thread group g.

          ...

      }

   

We describe how to override each method in the following section.

SecurityManager Method Changes and Override Advice

This section lists changes made to java.lang.SecurityManager methods in the Java 2 SDK and provides suggestions regarding any overrides you may wish to make. Please see the Java documentation for the SecurityManager class for more information on these methods.

protected boolean inCheck

This field has been deprecated, and any uses of this field within the SDK itself have been removed. Instead of using inCheck, you should use checkPermission along with doPrivileged.

public boolean getInCheck();

This method has also been deprecated.

public SecurityManager();

The constructor has been modified to allow multiple SecurityManagers to be created, assuming the caller has the RuntimePermission("createSecurityManager") permission.

protected native Class[] getClassContext();

No changes. This call can be used to emulate the 1.1 behavior of the methods that have been changed in the Java 2 SDK ( currentClassLoader, currentLoadedClass, classLoaderDepth, inClassLoader).

protected ClassLoader currentClassLoader();

The typical use of this method in JDK 1.1-style security managers was to see if there was a class loader on the stack, and if not, treat the code as "trusted" and allow it to do anything. This method has been modified in the Java 2 SDK to allow trusted SDK code (actually any code granted java.security.AllPermission) that calls doPrivileged to be treated as trusted by 1.1-style security managers. It has also been modified to skip system class loaders. A system class loader is defined as being a class loader that is equal to the system class loader (as returned by ClassLoader.getSystemClassLoader) or one of its ancestors.

This method will return null in the following three cases:

1.  All methods on the execution stack are from classes defined using the system class loader or one of its ancestors.

2.  All methods on the execution stack up to the first "privileged" caller (see java.security.AccessController.doPrivileged) are from classes defined using the system class loader or one of its ancestors.

3.  A call to checkPermission with java.security.AllPermission does not result in a SecurityException.

This method has been deprecated. Use checkPermission instead.

protected Class currentLoadedClass();

This method has been modified in the same fashion as currentClassLoader, and will return null if the current security context has been granted AllPermission or all the methods on the stack (up to the first privileged caller, if any) are from classes defined using the system class loader or one of its ancestors.

This method has been deprecated. Use checkPermission instead.

protected int classDepth(String name);

No changes in behavior. This method has been deprecated. Use checkPermission instead.

protected int classLoaderDepth();

This method has been modified in the same fashion as currentClassLoader, and will return -1 if the current security context has been granted AllPermission or all the methods on the stack (up to the first privileged caller, if any) are from classes defined using the system class loader or one of its ancestors.

This method has been deprecated. Use checkPermission instead.

protected boolean inClass(String name);

No changes in behavior. This method has been deprecated. Use checkPermission instead.

protected boolean inClassLoader();

This method returns true if currentClassLoader returns a non-null class loader, so it follows the same semantics that currentClassLoader does.

This method has been deprecated. Use checkPermission instead.

public Object getSecurityContext();

This method returns a java.security.AccessControlContext object that is created with a call to java.security.AccessController.getContext. In JDK1.1 it returned null by default.

public void checkPermission(Permission perm);

This method is new in the Java 2 SDK. It calls java.security.AccessController.checkPermission with the given permission. Internally, the SDK always calls SecurityManager.checkPermission instead of calling the AccessController directly. This allows people to override this method to provide additional functionality such as auditing and/or GUI dialogs.

public void checkPermission(Permission perm, Object context);

This method is new in the Java 2 SDK. If context is an instance of AccessControlContext then the AccessControlContext.checkPermission method will be invoked on the given context with the specified permission.

If context is not an instance of AccessControlContext then a SecurityException is thrown.

public void checkCreateClassLoader();

This method has been modified to call checkPermission with the RuntimePermission("createClassLoader") permission.

If this method is overridden, then a call to super.checkCreateClassLoader should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

 

    public void checkCreateClassLoader() {

      if (someCustomSecurityCheckFails()) {

        super.checkCreateClassLoader();

      }

    }

  }

public void checkAccess(Thread t);

If the thread argument is a system thread (belongs to the thread group with a null parent) then this method calls checkPermission with the RuntimePermission("modifyThread") permission.

Applications that want a stricter policy should override this method.

If this method is overridden, then super.checkAccess should be called by the first statement in the overridden method, or the equivalent security check should be placed in the overridden method.

If this method is overridden, the method that overrides it should additionally check to see if the calling thread has the RuntimePermission("modifyThread") permission, and if so, return silently. This is to ensure that code granted that permission (such as the SDK itself) is allowed to manipulate any thread.

For example:

  public class MySecurityManager extends SecurityManager {

 

    public void checkAccess(Thread t) {

      // a call to super will throw an exception if someone

      // is trying to modify a system thread

      super.checkAccess(t);

      ...

      if (someCustomSecurityCheckForOtherThreadsFails()) {

        // if the check fails, instead of throwing an exception,

        // call checkPermission, which will throw an exception

        // if need be

        checkPermission(new RuntimePermission("modifyThread")); 

      }

      ...

    }

  }

public void checkAccess(ThreadGroup g);

If the thread group argument is the system thread group (has a null parent) then this method calls checkPermission with the RuntimePermission("modifyThreadGroup") permission.

Applications that want a stricter policy should override this method.

If this method is overridden, then super.checkAccess should be called by the first statement in the overridden method, or the equivalent security check should be placed in the overridden method.

If this method is overridden, the method that overrides it should additionally check to see if the caller has the RuntimePermission("modifyThreadGroup") permission, and if so, return silently. This is to ensure that code granted that permission (such as the SDK itself) is allowed to manipulate any thread group.

For example:

  public class MySecurityManager extends SecurityManager {

 

    public void checkAccess(ThreadGroup g) {

      // a call to super will throw an exception if someone

      // is trying to modify the system thread group

      super.checkAccess(g);

      ...

      if (someCustomSecurityCheckForOtherThreadGroupsFails()) {

        // if the check fails, instead of throwing an exception,

        // call checkPermission, which will throw an exception

        // if need be

        checkPermission(new RuntimePermission("modifyThreadGroup")); 

      }

      ...

    }

  }

public void checkExit(int status);

This method has been modified to call checkPermission with the RuntimePermission("exitVM") permission.

If this method is overridden, then a call to super.checkExit should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

 

    public void checkExit(int status) {

      if (someCustomSecurityCheckFails()) {

        super.checkExit(status);

      }

    }

  }

public void checkExec(String cmd);

This method has been modified to call checkPermission with a FilePermission. If the cmd is an absolute path (see java.io.File.isAbsolute) then it is passed as-is as the target for the FilePermission. If cmd is not absolute, then the special target "<<ALL FILES>>" is used. This target is used because it is difficult to determine the actual path of the command that will be ex