About com.ms.security

This package provides access to the security system of the Microsoft Win32 VM for Java. The security system is based on associating sets of permissions with individual classes so that the Microsoft VM can examine the call stack to determine what permissions are valid in a given context.

Overview of Classes

The StandardSecurityManager class implements a granular, permission-based security policy. The StandardSecurityManager is the installed security manager within the Microsoft VM for all Java code (except Java applications), and it processes security checks for the standard Java APIs. The StandardSecurityManager.checkXXX methods call the PolicyEngine.checkPermission methods to do the stack crawl that actually determines whether the specified operation is permitted. For instance, if your code creates a new java.io.FileOutputStream object and then attempts to write to that file, the Microsoft VM calls the StandardSecurityManager's checkWrite method, passing in the name of the file you want to write to. If the security check fails, a SecurityExceptionEx is thrown.

The PolicyEngine class contains methods that check for a particular type of permission, using either a deep or a shallow security check. A deep security check examines the call stack (beginning with the immediate caller to PolicyEngine and working backwards) and determines whether each class on the stack has the specified permission. If any class does not have the specified permission, the security check fails. If the right to the specified permission has been explicitly asserted, the stack crawl terminates immediately and the security check passes. If the right to the specified permission has been explicitly denied, the stack crawl terminates immediately and the security check fails. A shallow security check requires that you specify a skip set that indicates a set of classes to ignore during the security check. During a shallow security check, only the first class found outside the skip set is examined for the specified permission. To learn more about security checks and how to assert, deny, or revert a permission, see the PolicyEngine class.

Each permission class must implement the IPermission interface. Optionally, one or both of the IAdjustablePermission and the IEncodablePermission interfaces can be implemented. If the IAdjustablePermission interface is implemented, a permission object can be adjusted to give context information. For instance, the ThreadPermission class implements IAdjustablePermission. Therefore, a ThreadPermission object can be adjusted to indicate a ThreadGroup object that classes with the ThreadPermission should have access to. If a permission class implements the IEncodablePermission interface, the permission object can encode itself for use in digital signatures. The encoding formats that are supported (HTML, ASN, text, and others) are supplied by constants in the EncodeFormats class.

Permission types are identified by the constants in the PermissionID class. Except for PermissionID.SYSTEM, each constant corresponds to the name of a permission class that implements that type of permission. For instance, the PermissionID.REGISTRY value corresponds to the com.ms.security.permissions.RegistryPermission class. PermissionID objects are passed to the PolicyEngine.checkPermission(PermissionID,Object) methods to indicate the type of permission being checked. If you have designed a custom permission class and need a PermissionID that identifies your new class, you can call the PolicyEngine.permissionNameToID method to create a PermissionID. You can also use permissionNameToID to convert a predefined system permission name to its corresponding PermissionID.

Several of the predefined classes in the com.ms.security.permissions package implement the ISecurityRequest interface. An instance of a class that implements ISecurityRequest represents both a PermissionID and one or more parameters that are relevant to the permission type. To do a parameterized security check for a permission that has a corresponding ISecurityRequest class, you should pass an ISecurityRequest object of the appropriate type to the PolicyEngine.checkPermission(ISecurityRequest) method. The example at the end of this overview shows how to do a parameterized security check using an ISecurityRequest object. To learn more about doing security checks for predefined permissions, see the Using ISecurityRequest Objects To Perform Security Checks section of the com.ms.security.permissions overview. The com.ms.security.permissions overview also provides a list of classes that implement ISecurityRequest.

Permission objects can be grouped into a PermissionSet or a PermissionDataSet. A PermissionSet object is immutable, so you could turn your PermissionDataSet into a PermissionSet to protect your permission objects from modification. However, if you want to enumerate the permissions in the set, they must be in the form of a PermissionDataSet so that you can use the PermissionDataSetEnumerator methods. Similarly, when a set of permissions is ready to be encoded for use in a digital signature, the set must be in the form of a PermissionDataSet object. However, when the permission set is associated with a particular class (using the SecurityClassLoader methods), it should be in PermissionSet form so that it cannot be modified.

The PermissionUtils class supplies a variety of useful methods whose functionality falls into one of three categories.

• Deep copy helpers to use when implementing IPermission.copy.
• Comparison helpers to use when implementing SetComparison.compareSet methods.
• Combine helpers to use when implementing IPermission.combine.

Examples

The following example illustrates one way to do a parameterized security check for the PropertyPermission that indicates permission to read the java.class.path property.

// Create a request object
PropertyAccessRequest par = 
   new PropertyAccessRequest("java.class.path");   
PolicyEngine.checkPermission(par);

Suppose you want to create a set of three permissions and mark a new class with those permissions. The following code could be written within a class that extends the SecurityClassLoader class.

// Create the PermissionDataSet. 
PermissionDataSet pds = new PermissionDataSet();

// Create a permission object.   
PropertyPermission perm1 = 
   new PropertyPermission();
perm1.addAllowedProperties("java.*");

// Add the permission to the set.
pds.add(PermissionID.PROPERTY,perm1);
 
// Create a second permission object.
SystemStreamsPermission perm2 = 
   new SystemStreamsPermission();
perm2.setCanSetSystemIn(true);

// Add the second permission to the set.
pds.add(PermissionID.SYSSTREAMS,perm2);

// Create a third permission object.
FileIOPermission perm3 = new FileIOPermission();
perm3.AddReadableFile("MySample.txt",true);
perm3.AddDeleteableFile("Useless.txt",true);

// Add the third permission to the set.
pds.add(PermissionID.FILEIO);

// Convert to a PermissionSet.
PermissionSet permSet = pds.toPermissionSet();

... 
// Obtain the Principal  (prince) 
// Obtain the class name (classname) 
// Obtain the class data (classdata) 
...

int len = classdata.length;
 
// Mark the class with the PermissionSet.
Class cl = defineClass(classname,classdata,0,
                       len,permSet,prince);     

Classes

Class EncodeFormats

This class contains values that are used to encode permissions or retrieve information about permissions.

Class PermissionDataSet

This class represents sets of permission objects.

Class PermissionDataSetEnumerator

This class implements an enumeration of the permission identifiers stored within a PermissionDataSet object.

Class PermissionID

This class represents objects that are used to identify permission types.

Class PermissionRequestDeniedException

This class represents a security exception that is thrown by a component of the security system when a security check fails because a permission has been explicitly denied.

Class PermissionSet

This class represents an immutable form of a PermissionDataSet object.

Class PermissionTreeOutput

This class is used to create a tree representation of the permissions.

Class PermissionUtils

This class provides routines used by the permission classes.

Class PolicyEngine

This class exposes methods that perform permission-based security checks.

Class SecurityClassLoader

This class provides methods that associate permissions with classes.

Class SecurityExceptionEx

This class represents security exceptions that are thrown by a component of the security system to indicate a security violation.

Class StandardSecurityManager

This class defines a security policy that uses the permission model to perform security checks.

Interfaces

Interface IAdjustablePermission

This interface provides a method for modifying a permission object to give context information.

Interface IEncodablePermission

This interface provides methods that allow permissions to represent their internal state in any desired format.

Interface IPermission

This interface must be implemented by all classes that represent permissions.

Interface ISecurityRequest

This interface is used to associate specific types of objects with specific permission types.

Hierarchy

Object
  |
  +--EncodeFormats
  |
  +--PermissionDataSet (IEncodablePermission, com.ms.util.SetComparison)
  |
  +--PermissionDataSetEnumerator (Enumeration)
  |
  +--PermissionID
  |
  +--PermissionSet
  |
  +--PermissionUtils
  |
  +--PolicyEngine

ClassLoader
  |
  +--SecurityClassLoader

SecurityException
  |
  +--SecurityExceptionEx
     |
     +--PermissionRequestDeniedException

SecurityManager
  |
  +--StandardSecurityManager

OutputStream
  |
  +--PermissionTreeOutput

IAdjustablePermission
IEncodablePermission
IPermission
ISecurityRequest