Microsoft SDK for Java

PolicyEngine Class

The PolicyEngine Class of the com.ms.security package exposes methods that perform permission-based security checks.

public class PolicyEngine
{
  // Methods
  public static native void assertPermission(PermissionID pid);
  public static void checkCallerForAllPermissions(Class[] skipset);
  public static void checkCallersPermission(PermissionID pid,
        Class[] skipset);
  public static void checkCallersPermission(String pname,
        Class[] skipset);
  public static void checkCallersPermission(PermissionID pid,Object
        sreq,Class[] skipset);
  public static void checkCallersPermission(String pname,
        Object sreq,Class[] skipset);
  public static void checkCallersPermission(ISecurityRequest sreq,
        Class[] skipset);
  public static void checkClass(Class cls,PermissionID pid);
  public static void checkClass(Class cls,String pname);
  public static void checkClass(Class cls,PermissionID pid,
        Object sreq);
  public static void checkClass(Class cls,ISecurityRequest sreq);
  public static void checkClassForAllPermissions(Class cls);
  public static void checkForAllPermissions();
  public static void checkPermission(PermissionID pid);
  public static void checkPermission(String pname);
  public static void checkPermission(PermissionID pid,Object sreq);
  public static void checkPermission(String pname,Object sreq);
  public static void checkPermission(ISecurityRequest sreq);
  public static native void denyPermission(PermissionID pid);
  public static Class getClassOfCaller();
  public static Class getClassOfCaller(Class[] skip);
  public static native PermissionDataSet getPermissionsOfClass(
        Class c);
  public static native Principal getPrincipalOfClass(Class c);
  public static synchronized PermissionID permissionNameToID(String
        pname);
  public static native void revertPermission(PermissionID pid);
}

These security checks are based on a security model that allows you to associate sets of permissions with the classes in the system. Then, at any point in time, the execution context can be examined to determine which operations are allowed by the permissions active within that context. The class types found on the call stack provide the required information about the active permissions. For more information about permissions, see the com.ms.security package overview.

The PolicyEngine class provides several different ways to examine the execution context to determine whether a given operation is allowed. The two main types of security checks are deep checks and shallow checks. Deep checks examine the entire call stack to ensure that all the classes within that execution context possess a certain permission. The PolicyEngine.checkPermission methods perform deep checks. In contrast, shallow checks do not use the depth of the stack to determine when to terminate the stack crawl. They are provided as a means of implementing roughly the same type of behavior as the original JDK SecurityManager methods classDepth and classLoaderDepth. The PolicyEngine.checkCallersPermission methods perform shallow checks. In general, deep checks are preferred over shallow checks.

Deep security checks are implemented in the following way: The stack is examined, starting with the immediate caller to the PolicyEngine class and working backward.

During a deep security check, the following steps are taken.

  1. Get the set of permissions associated with the class type of the stack frame, and then find the IPermission instance for the specific type of permission that is being checked for within that set.

  2. If the permission set does not contain an instance of the type of permission that is being searched for, terminate the stack crawl. The check fails.

  3. If this is a parameterized check, call the check method (IPermission.check) on the permission instance that has been found, passing it the security request object. If the check method throws an exception, terminate the stack crawl. The check fails.

  4. If the permission type has been explicitly denied by the current stack frame (using the denyPermission method), terminate the stack crawl. The security check fails.

  5. If the permission type has been explicitly asserted by the current stack frame (using the assertPermission method), terminate the stack crawl. The security check succeeds.

  6. The current frame has passed. Continue the stack crawl with the next frame.

Shallow security checks only check the immediate caller outside a boundary that is defined by a specified skip set. A skip set is a set of classes that is ignored during the security check. The first (and only the first) class found outside of the skip set will be checked for the permissions in question.

Shallow security checks are implemented in the following way. The stack is examined, starting with the immediate caller to the PolicyEngine class, and working backward. During a shallow security check, the following steps are taken.

  1. Get the class type associated with the current stack frame. If the class type is not within the specified skip set, the frame that should be checked has been found. Proceed to step 4.

  2. The class type of the current frame is in the skip set; however, the stack frame must still be checked for any explicit assertions or denials. If the permission type has been explicitly denied by the current stack frame (using the denyPermission method), terminate the stack crawl. The security check fails. If the permission type has been explicitly asserted by the current stack frame (using the assertPermission method), terminate the stack crawl. The security check succeeds.

  3. Since this frame was in the skip set, and no assertions or denials stopped the crawl, search for the next frame and continue the crawl. Proceed to step 1.

  4. The frame to be examined has been found. Get the set of permissions associated with the class type of the stack frame, and then find the IPermission instance for the specific type of permission that is being checked for within that set.

  5. If the permission set does not contain an instance of the type of permission that is being searched for, terminate the stack crawl. The security check fails.

  6. If this is a parameterized check, call the check method (IPermission.check) on the permission instance that was found, passing it the security request object. If the check method throws an exception, terminate the stack crawl. The security check fails.

  7. The current frame has passed, so terminate the stack crawl. The security check succeeds.

Deep and shallow security checks are provided in both parameterized and unparameterized forms.

Unparameterized checks simply ensure that all the classes in question possess a certain type of permission. This type of check is used for simple permissions, like the printing permission. Either a class has the printing permission or it doesn't.

Parameterized checks are used for more complex permissions, where the parameter to the check method is an object that is specific to the permission type. For instance, when checking for the file I/O permission, you must specify exactly which file I/O operation is being attempted and which file is involved. To check file I/O permission, you would create an instance of the com.ms.security.permissions.FileIORequest class that indicates which file is involved and which I/O operation is requested. You would then call the PolicyEngine.checkPermission(ISecurityRequest) method, passing in the FileIORequest object. If the check succeeds (no SecurityException is thrown), the specified operation is allowed.

© 1999 Microsoft Corporation. All rights reserved. Terms of use.