System.Security.Policy.PolicyLevel Class

Summary

Represents the security policy levels for the common language runtime. This class cannot be inherited.

C# Syntax:

[Serializable] public sealed class PolicyLevel

The highest level of security policy is enterprise-wide. Successive lower levels of hierarchy represent further policy restrictions, but can never grant more permissions than allowed by higher levels. The following policy levels are implemented:

1. Enterprise: security policy for all managed code in an enterprise.

2. Machine: security policy for all managed code run on the computer.

3. User: security policy for all managed code run by the user.

4. Application domain: security policy for all managed code in an application.

A policy level consists of a set of code groups organized into a single rooted tree (see CodeGroup), a set of named permission sets that are referenced by the code groups to specify permissions to be granted to code belonging to the code group, and a list of fully-trusted assemblies.

Use SecurityManager.PolicyHierarchy to enumerate the policy levels.

System.Security.Policy Namespace

System.Security.Policy.PolicyLevel Member List:

Public Properties

FullTrustAssemblies	Read-only Gets a list of StrongNameMembershipCondition objects used to determine whether an assembly is a member of the group of assemblies used to evaluate security policy.
Label	Read-only Gets a descriptive label for the policy level.
NamedPermissionSets	Read-only Gets a list of named permission sets defined for the policy level.
RootCodeGroup	Read-write Gets or sets the root code group for the policy level.
StoreLocation	Read-only Gets the path where the policy file is stored.

Public Methods

AddFullTrustAssembly	Overloaded: AddFullTrustAssembly(StrongName sn) Adds a StrongNameMembershipCondition corresponding to the specified StrongName to the list of StrongNameMembershipCondition objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated.
AddFullTrustAssembly	Overloaded: AddFullTrustAssembly(StrongNameMembershipCondition snMC) Adds the specified StrongNameMembershipCondition to the list of StrongNameMembershipCondition objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated.
AddNamedPermissionSet	Adds a NamedPermissionSet to the current policy level.
ChangeNamedPermissionSet	Replaces a NamedPermissionSet in the current policy level with the specified PermissionSet.
CreateAppDomainLevel	Creates a new policy level for use at the application domain policy level.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
FromXml	Reconstructs a security object with a given state from an XML encoding.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetNamedPermissionSet	Returns the NamedPermissionSet in the current policy level with the specified name.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Recover	Replaces the configuration file for this PolicyLevel with the last backup (reflecting the state of policy prior to the last time it was saved) and returns it to the state of the last save.
RemoveFullTrustAssembly	Overloaded: RemoveFullTrustAssembly(StrongName sn) Removes an assembly with the specified StrongName from the list of assemblies the policy level uses to evaluate policy.
RemoveFullTrustAssembly	Overloaded: RemoveFullTrustAssembly(StrongNameMembershipCondition snMC) Removes an assembly with the specified StrongNameMembershipCondition from the list of assemblies the policy level uses to evaluate policy.
RemoveNamedPermissionSet	Overloaded: RemoveNamedPermissionSet(NamedPermissionSet permSet) Removes the specified NamedPermissionSet from the current policy level.
RemoveNamedPermissionSet	Overloaded: RemoveNamedPermissionSet(string name) Removes the NamedPermissionSet with the specified name from the current policy level.
Reset	Returns the current policy level to the default state.
Resolve	Resolves policy based on evidence for the policy level, and returns the resulting PolicyStatement.
ResolveMatchingCodeGroups	Resolves policy at the policy level and returns the root of a code group tree that matches the evidence.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.
ToXml	Creates an XML encoding of the security object and its current state.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Security.Policy.PolicyLevel

System.Security.Policy.PolicyLevel Member Details

Summary

Gets a list of StrongNameMembershipCondition objects used to determine whether an assembly is a member of the group of assemblies used to evaluate security policy.

C# Syntax:

public IList FullTrustAssemblies {get;}

PolicyLevel.FullTrustAssemblies are granted full trust during security policy evaluation of assemblies not in the list, but are not automatically granted full trust when directly evaluated by the security policy system.

Return to top

Summary

Gets a descriptive label for the policy level.

C# Syntax:

public string Label {get;}

The label is used to help the administrator identify the policy level.

The following example writes a list of the labels of all policy levels in the hierarchy.

 //Write out names (labels) of all policy levels.
 IEnumerator levels = SecurityManager.PolicyHierarchy();
 while (levels.MoveNext()) {
    PolicyLevel level = (PolicyLevel)levels.Current;
    Console.WriteLine(level.Label);
 }

    

Return to top

Summary

Gets a list of named permission sets defined for the policy level.

C# Syntax:

public IList NamedPermissionSets {get;}

The following example writes the names of the permission sets in all policy levels.

 //Write out names of permission sets in all policy levels.
 IEnumerator levels = SecurityManager.PolicyHierarchy();
 while (levels.MoveNext()) {
    PolicyLevel level = (PolicyLevel)levels.Current;
    Console.WriteLine("Policy Level: {0}", level.Label);
    IEnumerator sets = level.NamedPermissionSets.GetEnumerator();
    while (sets.MoveNext()) {
       NamedPermissionSet pset = (NamedPermissionSet)sets.Current;
       Console.WriteLine("\tPermission set: {0}", pset.Name);
    }
 }

    

Return to top

Summary

Gets or sets the root code group for the policy level.

C# Syntax:

public CodeGroup RootCodeGroup {get; set;}

Every policy level has one root CodeGroup.

The following example writes the type of the membership condition that the root CodeGroup in each policy level uses.

 //Write out type of membership condition of root code group in all policy levels.
 IEnumerator levels = SecurityManager.PolicyHierarchy();
 while (levels.MoveNext()) {
   PolicyLevel level = (PolicyLevel)levels.Current;
   Console.WriteLine ("Policy Level: {0}", level.Label);
 
   CodeGroup group = level.RootCodeGroup;
   Console.WriteLine ("\tRoot CodeGroup type: {0}",
      group.MembershipCondition.ToString());
 }

    

Return to top

Summary

Gets the path where the policy file is stored.

C# Syntax:

public string StoreLocation {get;}

Return to top

Summary

Adds a StrongNameMembershipCondition corresponding to the specified StrongName to the list of StrongNameMembershipCondition objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated.

C# Syntax:

public void AddFullTrustAssembly(    StrongName sn );

sn

The StrongName used to create the StrongNameMembershipCondition to add to the list of StrongNameMembershipCondition objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated.

Exceptions

Exception Type	Condition
ArgumentNullException	The sn parameter is null.
ArgumentException	The StrongName specified by the sn parameter already has full trust.

Return to top

Summary

Adds the specified StrongNameMembershipCondition to the list of StrongNameMembershipCondition objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated.

C# Syntax:

public void AddFullTrustAssembly(    StrongNameMembershipCondition snMC );

snMC

The StrongNameMembershipCondition to add to the list of StrongNameMembershipCondition objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated.

Exceptions

Exception Type	Condition
ArgumentNullException	The snMC parameter is null.
ArgumentException	The StrongNameMembershipCondition specified by the snMC parameter already has full trust.

Return to top

Summary

Adds a NamedPermissionSet to the current policy level.

C# Syntax:

public void AddNamedPermissionSet(    NamedPermissionSet permSet );

permSet

The NamedPermissionSet to add to the current policy level.

Exceptions

Exception Type	Condition
ArgumentNullException	The permSet parameter is null.
ArgumentException	The permSet parameter has the same name as an existing NamedPermissionSet in the PolicyLevel.

Named permission sets are scoped by policy level.

Return to top

Summary

Replaces a NamedPermissionSet in the current policy level with the specified PermissionSet.

C# Syntax:

public NamedPermissionSet ChangeNamedPermissionSet(    string name,    PermissionSet pSet );

name

The name of the NamedPermissionSet to replace.

pSet

The PermissionSet that replaces the NamedPermissionSet specified by the name parameter.

Return Value:

A copy of the NamedPermissionSet that was replaced.

Exceptions

Exception Type	Condition
ArgumentException	The name parameter is null. -or- The pSet parameter is null.
ArgumentException	The name parameter is equal to the name of a reserved permission set. -or- The PermissionSet specified by the pSet parameter cannot be found.

Return to top

Summary

Creates a new policy level for use at the application domain policy level.

C# Syntax:

public static PolicyLevel CreateAppDomainLevel();

Return Value:

The newly created PolicyLevel.

This method creates a new PolicyLevel with the PolicyLevel.Label "AppDomain". The new PolicyLevel will initially contain the same NamedPermissionSet objects as in the default computer policy, and will have a single root code group that grants FullTrust to all code.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~PolicyLevel();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Reconstructs a security object with a given state from an XML encoding.

C# Syntax:

public void FromXml(    SecurityElement e );

e

The XML encoding to use to reconstruct the security object.

Exceptions

Exception Type	Condition
ArgumentNullException	The e parameter is null.
ArgumentException	The SecurityElement specified by the e parameter is invalid.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns the NamedPermissionSet in the current policy level with the specified name.

C# Syntax:

public NamedPermissionSet GetNamedPermissionSet(    string name );

name

The name of the NamedPermissionSet to find.

Return Value:

The NamedPermissionSet in the current policy level with the specified name, if found; otherwise, null.

Exceptions

Exception Type	Condition
ArgumentNullException	The name parameter is null.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Replaces the configuration file for this PolicyLevel with the last backup (reflecting the state of policy prior to the last time it was saved) and returns it to the state of the last save.

C# Syntax:

public void Recover();

Exceptions

Exception Type	Condition
PolicyException	The policy level does not have a valid configuration file.

This method does not make modifications to the current PolicyLevel. Instead, it updates the PolicyLevel object's file and the PolicyLevel that the security system uses to evaluate policy.

This method is used by the caspol -recover option (see ).

Return to top

Summary

Removes an assembly with the specified StrongName from the list of assemblies the policy level uses to evaluate policy.

C# Syntax:

public void RemoveFullTrustAssembly(    StrongName sn );

sn

The StrongName of the assembly to remove from the list of assemblies used to evaluate policy.

Exceptions

Exception Type	Condition
ArgumentNullException	The sn parameter is null.
ArgumentException	The assembly with the StrongName specified by the sn parameter does not have full trust.

Return to top

Summary

Removes an assembly with the specified StrongNameMembershipCondition from the list of assemblies the policy level uses to evaluate policy.

C# Syntax:

public void RemoveFullTrustAssembly(    StrongNameMembershipCondition snMC );

snMC

The StrongNameMembershipCondition of the assembly to remove from the list of assemblies used to evaluate policy.

Exceptions

Exception Type	Condition
ArgumentNullException	The snMC parameter is null.
ArgumentException	The StrongNameMembershipCondition specified by the snMC parameter does not have full trust.

Return to top

Summary

Removes the specified NamedPermissionSet from the current policy level.

C# Syntax:

public NamedPermissionSet RemoveNamedPermissionSet(    NamedPermissionSet permSet );

permSet

The NamedPermissionSet to remove from the current policy level.

Return Value:

The NamedPermissionSet that was removed.

Exceptions

Exception Type	Condition
ArgumentException	The NamedPermissionSet specified by the permSet parameter was not found.
ArgumentNullException	The permSet parameter is null.

Return to top

Summary

Removes the NamedPermissionSet with the specified name from the current policy level.

C# Syntax:

public NamedPermissionSet RemoveNamedPermissionSet(    string name );

name

The name of the NamedPermissionSet to remove.

Return Value:

The NamedPermissionSet that was removed.

Exceptions

Exception Type	Condition
ArgumentException	The name parameter is equal to the name of a reserved permission set. -or- A NamedPermissionSet with the specified name cannot be found.
ArgumentNullException	The name parameter is null.

Return to top

Summary

Returns the current policy level to the default state.

C# Syntax:

public void Reset();

The default state is different for each policy level.

Return to top

Summary

Resolves policy based on evidence for the policy level, and returns the resulting PolicyStatement.

C# Syntax:

public PolicyStatement Resolve(    Evidence evidence );

evidence

The Evidence used to resolve the PolicyLevel.

Return Value:

The resulting PolicyStatement.

Exceptions

Exception Type	Condition
PolicyException	The policy level contains multiple matching code groups marked as exclusive.
ArgumentNullException	The evidence parameter is null.

PolicyLevel.Resolve is the basic policy evaluation operation for policy levels. Given a set of evidence as input, this method tests membership conditions of code groups starting at the root and working down as matched. The combination of permissions resulting from the matching code groups produces a PolicyStatement that is returned.

In granting permissions to code, security policy uses the resolved policy statements for all applicable policy levels, together with the code request for permissions.

Return to top

Summary

Resolves policy at the policy level and returns the root of a code group tree that matches the evidence.

C# Syntax:

public CodeGroup ResolveMatchingCodeGroups(    Evidence evidence );

evidence

The Evidence used to resolve policy.

Return Value:

A CodeGroup representing the root of a tree of code groups matching the specified evidence.

Exceptions

Exception Type	Condition
PolicyException	The policy level contains multiple matching code groups marked as exclusive.
ArgumentNullException	The evidence parameter is null.

You can use this method to analyze the effect of the code groups in a policy level with respect to a certain set of evidence. For example, if the security policy is not granting an assembly the minimum code request permissions it needs, it can be difficult to tell by examination of the code groups exactly where the problem is.

Since this method returns a code group that can have child code groups, it is possible for an administrator to examine the code group and its child code groups and determine which code groups match.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Creates an XML encoding of the security object and its current state.

C# Syntax:

public SecurityElement ToXml();

Return Value:

An XML encoding of the security object, including any state information.

Return to top

Top of page