Class PolicyEngine

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);
}

This class exposes methods that perform permission-based security checks. 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.

Methods

assertPermission

public static native void assertPermission(PermissionID pid);

Asserts the right to a certain type of permission. This method causes the security system to ignore your callers when you cause a security check of the asserted type to occur.

Return Value:

No return value.

Parameter	Description
pid	The type of permission to assert.

Remarks:

Normally, when checking a given permission, the security system examines every frame on the call stack to ensure that all the callers possess the ability to perform the operation in question. However, if the security system sees a stack frame where the requested permission has been asserted (with this method), the stack crawl stops early and the security check succeeds.

The asserted permission state disappears when the stack frame of the caller to assertPermission exits (by executing a return statement or throwing an exception). The revertPermission method can be used to un-assert a permission type.

The following example shows how to assert the right to perform file I/O operations.

   ...
   // Assert the right to perform file I/O   
   PolicyEngine.assertPermission(PermissionID.FILEIO);

   // Now, do some file operation. Since you have asserted
   // your rights to file I/O, this check will succeed even if your callers do
   // not possess the ability to perform file I/O.
   FileInputStream fis = new FileInputStream("c:\\MySample.txt");      
   ...

Note To assert all permissions, pass PermissionID.SYSTEM to the assertPermission method. This assertion forces the security system to ignore your callers during all security checks. Only fully trusted code can assert the SYSTEM permission.

See Also: denyPermission, revertPermission

checkCallerForAllPermissions

public static void checkCallerForAllPermissions(Class[] skipset);

Performs a security check to determine whether the first calling class outside the skip set is fully trusted.

Note Permission assertions and denials of the permission type PermissionID.SYSTEM are recognized within the skip set frames. They will affect the stack crawl and could cause it to terminate early.

Return Value:

No return value.

Parameter	Description
skipset	The set of classes to ignore on the call stack.

Exceptions:

SecurityException if the security check fails.

checkCallersPermission

public static void checkCallersPermission(PermissionID pid,Class[] skipset);

Performs a simple (non-parameterized) security check for a specific type of permission. This check is shallow. Only the first stack frame found outside the specified skip set will be checked.

Note Permission assertions and denials are recognized within the skip set frames, and could cause the stack crawl to terminate early.

Return Value:

No return value.

Parameter	Description
pid	The type of permission to check for.
skipset	The set of classes to ignore on the call stack.

Exceptions:

SecurityException if the security check fails.

checkCallersPermission

public static void checkCallersPermission(String pname,Class[] skipset);

Performs a simple (non-parameterized) security check for a specific type of permission. This check is shallow. Only the first stack frame found outside the specified skip set will be checked. A permission name is used to specify the permission type (instead of a PermissionID).

Note Permission assertions and denials are recognized within the skip set frames, and could cause the stack crawl to terminate early.

Return Value:

No return value.

Parameter	Description
pname	The name of the permission to check for.
skipset	The set of classes to ignore on the call stack.

Exceptions:

SecurityException if the security check fails.

checkCallersPermission

public static void checkCallersPermission(PermissionID pid,Object sreq,
        Class[] skipset);

Performs a parameterized security check for a specific type of permission. The check is shallow. Only the first stack frame found outside the specified skip set will be checked.

Note Permission assertions and denials are recognized within the skip set frames, and may cause the stack crawl to terminate early.

Return Value:

No return value.

Parameter	Description
pid	The type of permission to check for.
sreq	The security request object that indicates the specific resource to check for within the realm of the permission type. The type of the object depends on the type of the permission being checked.
skipset	The set of classes to ignore on the call stack.

Exceptions:

SecurityException if the security check fails.

checkCallersPermission

public static void checkCallersPermission(String pname,Object sreq,
        Class[] skipset);

Performs a parameterized security check for a specific type of permission. The check is shallow. Only the first stack frame found outside the specified skip set will be checked. A permission name is used to specify the permission type (instead of a PermissionID).

Note Permission assertions and denials are recognized within the skip set frames, and may cause the stack crawl to terminate early.

Return Value:

No return value.

Parameter	Description
pname	The name of the permission to check for.
sreq	The security request object.
skipset	The set of classes to ignore on the call stack.

Exceptions:

SecurityException if the security check fails.

checkCallersPermission

public static void checkCallersPermission(ISecurityRequest sreq,
        Class[] skipset);

Performs a parameterized security check for a specific type of permission. The check is shallow. Only the first stack frame found outside the specified skip set will be checked.

This method is a variation on the checkCallersPermission(PermissionID,Object,Class[]) method, where the sreq parameter indicates the permission type, and it also represents the security request object.

Return Value:

No return value.

Parameter	Description
sreq	The object that indicates the type of permission to check for and represents the security request object.
skipset	The set of classes to ignore on the call stack.

Exceptions:

SecurityException if the security check fails.

checkClass

public static void checkClass(Class cls,PermissionID pid);

Performs a security check directly against a specified class. If the class does not possess the specified type of permission, a SecurityException is thrown.

Return Value:

No return value.

Parameter	Description
cls	The class to check against.
pid	The type of permission to check for.

Exceptions:

SecurityException if the security check fails.

checkClass

public static void checkClass(Class cls,String pname);

Performs a security check directly against a specified class. If the class does not possess the specified type of permission, a SecurityException is thrown. The permission type is specified as a permission name (instead of a PermissionID object).

Return Value:

No return value.

Parameter	Description
cls	The class to check against.
pname	The name of the permission to check for.

Exceptions:

SecurityException if the security check fails.

checkClass

public static void checkClass(Class cls,PermissionID pid,Object sreq);

Performs a security check directly against a specified class. The class must possess the specified type of permission, and the parameterized check against the class's associated permission object must pass, or a SecurityException is thrown.

Return Value:

No return value.

Parameter	Description
cls	The class to check against.
pid	The type of permission to check for.
sreq	The security request object.

Exceptions:

SecurityException if the security check fails.

checkClass

public static void checkClass(Class cls,ISecurityRequest sreq);

Performs a security check directly against a specified class. The class must possess the specified type of permission, and the parameterized check against the class's associated permission object must pass, or a SecurityException is thrown.

Parameter	Description
cls	The class to check against.
sreq	The object that determines the type of permission to check for and also represents the security request object.

Remarks:

This method is a variation on the checkClass(Class,PermissionID,Object) method, where the ISecurityRequest object is used to determine the permission type, and it is also used as the permission request object.

Exceptions:

SecurityException if the security check fails.

checkClassForAllPermissions

public static void checkClassForAllPermissions(Class cls);

Performs a security check directly against a class object. If the class is not fully trusted, the security check fails.

Return Value:

No return value.

Parameter	Description
cls	The class to check against.

Exceptions:

SecurityException if the security check fails.

checkForAllPermissions

public static void checkForAllPermissions();

Performs a security check to determine whether all the calling class types on the call stack are fully trusted. If any of the calling classes are not fully trusted, the security check fails (a SecurityException is thrown).

Note Permission assertions and denials on the permission type PermissionID.SYSTEM affect the stack crawl, causing it to terminate early without examining the entire stack.

Return Value:

No return value.

Exceptions:

SecurityException if the security check fails.

checkPermission

public static void checkPermission(PermissionID pid);

Performs a simple (non-parameterized) security check for a specified type of permission. For the security check to pass, all the callers on the call stack must possess the specified type of permission.

Note Permission assertions and denials might affect the stack crawl, which could cause it to terminate early without examining the entire stack.

Return Value:

No return value.

Parameter	Description
pid	The type of permission to check for.

Exceptions:

SecurityException if the security check fails.

checkPermission

public static void checkPermission(String pname);

Performs a simple (non-parameterized) security check for a specified type of permission. A permission name is used to specify the permission type. For the security check to pass, all the callers on the call stack must possess the specified type of permission.

Note Permission assertions and denials might affect the stack crawl, causing it to terminate early without examining the entire stack.

Return Value:

No return value.

Parameter	Description
pname	The name of the permission to check for.

Exceptions:

SecurityException if the security check fails.

checkPermission

public static void checkPermission(PermissionID pid,Object sreq);

Performs a parameterized security check for a specific type of permission.

Return Value:

No return value.

Parameter	Description
pid	The type of permission to check for.
sreq	The security request object that indicates the specific resource to check for within the realm of the permission type. The type of this object depends on the type of the permission being checked.

Remarks:

For the security check to pass, all the callers on the call stack must possess the specified type of permission. In addition, all the permission objects associated with the calling class types found on the stack must validate that the operation indicated by the security request object is allowed. Validation is accomplished by calling the IPermission.check method of all the found permission instances.

Note Permission assertions and denials might affect the stack crawl, causing it to terminate early without examining the entire stack.

Exceptions:

SecurityException if the security check fails.

checkPermission

public static void checkPermission(String pname,Object sreq);

Performs a parameterized security check for a specific type of permission. A permission name is used to specify the permission type (instead of a PermissionID).

Return Value:

No return value.

Parameter	Description
pname	The name of the permission to check for.
sreq	The security request object that indicates the specific resource to check for within the realm of the permission type. The type of this object depends on the type of the permission being checked.

Remarks:

For the security check to pass, all the callers on the call stack must possess the specified type of permission. In addition, all the permission objects associated with the calling class types found on the stack must validate that the operation indicated by the security request object is allowed. Validation is accomplished by calling the IPermission.check method of all the found permission instances.

Note Permission assertions and denials might affect the stack crawl, causing it to terminate early without examining the entire stack.

Exceptions:

SecurityException if the security check fails.

checkPermission

public static void checkPermission(ISecurityRequest sreq);

Performs a parameterized security check for a specific type of permission. This method is a variation on the checkPermission(PermissionID,Object) method where the sreq parameter is used to determine the permission type and is also used as the security request object.

Calling the checkPermission(ISecurityRequest) method is equivalent to the following call.

   checkPermission(sreq.getPermissionID(),sreq);

Return Value:

No return value.

Parameter	Description
sreq	The object that determines the permission type and indicates the resource to check for.

Exceptions:

SecurityException if the security check fails.

See Also: PolicyEngine.checkPermission(PermissionID,Object)

denyPermission

public static native void denyPermission(PermissionID pid);

Denies the right to a certain type of permission. Any stack-based security checks (for the specific type of permission that has been denied) that encounter the stack frame of the caller to denyPermission will fail. This forces the methods that you call to assert their permissions (using the assertPermission method) to pass security checks.

Return Value:

No return value.

Parameter	Description
pid	The type of permission to deny.

Remarks:

Normally, when checking a given permission, the security system examines every frame on the call stack to ensure all the callers possess the ability to perform the operation in question. If the security system sees a stack frame where that permission has been denied (with this method), the stack crawl stops early and the security check fails.

The denied permission state will disappear when the stack frame of the caller to denyPermission exits (by executing a return statement or throwing an exception). The revertPermission method can be used to un-deny a permission type.

The following example shows you how to deny the right to perform file I/O operations.

   ... 
   // Deny your right to perform file I/O.

   PolicyEngine.denyPermission(PermissionID.FILEIO);

   // Now, call into some other code in the MySample
   // class. If that code wants to perform some file I/O operations,
   // it must assert its rights to do so, or the file I/O 
   // security checks will fail because you have denied your rights to
   // them.

   MySample.doSomething();

   ...

Note To deny all permissions, pass PermissionID.SYSTEM to the denyPermission method. This forces any code you call to assert its rights to any permissions it needs to utilize. Only fully trusted code can deny the SYSTEM permission.

See Also: assertPermission, revertPermission

getClassOfCaller

public static Class getClassOfCaller ();

Retrieves the class type of the immediate caller of this method.

Return Value:

Returns the class type of the immediate caller of this method.

getClassOfCaller

public static Class getClassOfCaller (Class[] skip);

Retrieves the class type of the caller of this method, skipping any classes found in the specified skip set.

Return Value:

Returns the class type of the caller.

Parameter	Description
skip	The set of classes to ignore.

getPermissionsOfClass

public static native PermissionDataSet getPermissionsOfClass (Class c);

Obtains the permissions of a class. Only fully trusted classes are allowed to call this method.

Return Value:

Returns the permissions of the specified class.

Parameter	Description
c	The class whose permissions are being obtained.

getPrincipalOfClass

public static native Principal getPrincipalOfClass (Class c);

Obtains the principal associated with a specified class. Only fully trusted classes are allowed to call this method.

Return Value:

Returns the principal associated with the specified class.

Parameter	Description
c	The class to examine.

Exceptions:

SecurityException if the calling class is not fully trusted.

permissionNameToID

public static synchronized PermissionID permissionNameToID(String pname);

Creates a PermissionID object from a permission name.

Return Value:

Returns the PermissionID that maps to the specified permission name.

Parameter	Description
pname	The name of the permission.

Remarks:

Permission names must be the name of the class that implements the permission. The permission class must be a fully trusted system class. Only fully trusted code can create new permission identifiers.

revertPermission

public static native void revertPermission(PermissionID pid);

Negates the effects of any assertions (assertPermission) or denials (denyPermission) that have been performed for the specified permission type by the current stack frame.

Return Value:

No return value.

Parameter	Description
pid	The type of permission to revert.

Remarks:

The following example asserts a right, and then reverts it.

   ...

   // Assert your rights to perform file I/O operations

   PolicyEngine.assertPermission(PermissionID.FILEIO);

   // Do some file I/O. Your callers will be ignored during
   // the file I/O security check that this operation causes 
   // because you have asserted your rights.

   FileInputStream fis = new FileInputStream("c:\\MySample.txt");

   // Remove the file I/O assertion.

   PolicyEngine.revertPermission(PermissionID.FILEIO);

   // Do some more file I/O. This time your callers will be
   // included in the security check since
   // your file I/O rights are no longer asserted.

   FileInputStream fis = new FileInputStream("c:\\MySample.txt"); 
   ...

See Also: assertPermission, denyPermission