System.Security.Permissions.PrincipalPermission Class

Summary

Allows checks against the active principal (see IPrincipal) using the language constructs defined for both declarative and imperative security actions. This class cannot be inherited.

C# Syntax:

[Serializable] public sealed class PrincipalPermission : IPermission, ISecurityEncodable, IUnrestrictedPermission

By passing identity information (user name and role) to the constructor, PrincipalPermission can be used to demand that the identity of the active principal matches this information.

To match the active IPrincipal and associated IIdentity, both the specified identity and role must match. If null identity string is used, it is interpreted as a request to match any identity. Use of null role string will match any role. By implication, passing null parameter for name or role to PrincipalPermission will match the identity and roles in any IPrincipal. It is also possible to construct a PrincipalPermission that only determines whether the IIdentity represents an authenticated or unauthenticated entity. In this case, name and role are ignored.

Unlike most other permissions, PrincipalPermission does not extend CodeAccessPermission. It does, however, implement the IPermission interface. This is because PrincipalPermission is not a code access permission; that is, it is not granted based on the identity of the executing assembly. Instead, it allows code to perform actions ( PrincipalPermission.Demand, PrincipalPermission.Union, PrincipalPermission.Intersect, and so on) against the current user identity in a manner consistent with the way those actions are performed for code access and code identity permissions.

The following example creates two PrincipalPermission objects representing two different administrative users, forms the union of the two, and makes a demand. PrincipalPermission.Demand will succeed only if the active implementation of IPrincipal represents either user Bob in the role of Manager or user Louise in the role of Supervisor.

 String id1 = "Bob";
 String role1 = "Manager";
 PrincipalPermission PrincipalPerm1 = new PrincipalPermission(id1, role1);
 
 String id2 = "Louise";
 String role2 = "Supervisor";
 PrincipalPermission PrincipalPerm2 = new PrincipalPermission(id2, role2);
 
 (PrincipalPerm1.Union(PrincipalPerm2)).Demand();

    

System.Security.Permissions Namespace See also:
MSDN: permissions | MSDN: requestingpermissions | MSDN: principal | PrincipalPermissionAttribute

System.Security.Permissions.PrincipalPermission Member List:

Public Constructors

ctor #1	Overloaded: .ctor(PermissionState state) Initializes a new instance of the PrincipalPermission class with the specified PermissionState.
ctor #2	Overloaded: .ctor(string name, string role) Initializes a new instance of the PrincipalPermission class for the specified name and role.
ctor #3	Overloaded: .ctor(string name, string role, bool isAuthenticated) Initializes a new instance of the PrincipalPermission class for the specified name, role, and authentication status.

Public Methods

Copy	Creates and returns an identical copy of the current permission.
Demand	Determines at run time whether the current principal matches that specified by the current permission.
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 permission with a specified 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.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Intersect	Creates and returns a permission that is the intersection of the current permission and the specified permission.
IsSubsetOf	Determines whether the current permission is a subset of the specified permission.
IsUnrestricted	Returns a value indicating whether the current permission is unrestricted.
ToString	Overridden: Creates and returns a string representing the current permission.
ToXml	Creates an XML encoding of the permission and its current state.
Union	Creates a permission that is the union of the current permission and the specified permission.

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.Permissions.PrincipalPermission

System.Security.Permissions.PrincipalPermission Member Details

Summary

Initializes a new instance of the PrincipalPermission class with the specified PermissionState.

C# Syntax:

public PrincipalPermission(    PermissionState state );

state

One of the PermissionState values.

Exceptions

Exception Type	Condition
ArgumentException	The state parameter is not a valid PermissionState.

None matches only the unauthenticated principal ( PrincipalPermissionAttribute.Name is the empty string (""), no PrincipalPermissionAttribute.Role, PrincipalPermissionAttribute.Authenticated is false).Unrestricted matches all principals ( PrincipalPermissionAttribute.Name is null, PrincipalPermissionAttribute.Role is null).

Note This constructor is included for consistency with the design of other permissions, but is not useful in practice.

Return to top

Summary

Initializes a new instance of the PrincipalPermission class for the specified name and role.

C# Syntax:

public PrincipalPermission(    string name,    string role );

name

The name of the IPrincipal object's user.

role

The role of the IPrincipal object's user (for example, Administrator).

Both the name parameter and the role parameter must match for this permission to match the active IPrincipal and associated IIdentity.

Return to top

Summary

Initializes a new instance of the PrincipalPermission class for the specified name, role, and authentication status.

C# Syntax:

public PrincipalPermission(    string name,    string role,    bool isAuthenticated );

name

The name of the IPrincipal object's user.

role

The role of the IPrincipal object's user (for example, Administrator).

isAuthenticated

true to signify that the user is authenticated; otherwise, false.

Both the name parameter and the role parameter must match for this permission to match the active IPrincipal and associated IIdentity.

Return to top

Summary

Creates and returns an identical copy of the current permission.

C# Syntax:

public IPermission Copy();

Return Value:

A copy of the current permission.

Implements:

IPermission.Copy

A copy of the permission represents the same principal and identity as the original permission.

Return to top

Summary

Determines at run time whether the current principal matches that specified by the current permission.

C# Syntax:

public void Demand();

Exceptions

Exception Type	Condition
SecurityException	The current principal does not pass the security check for the principal specified by the current permission. -or- The current IPrincipal is null.

Implements:

IPermission.Demand

If no SecurityException is raised, PrincipalPermission.Demand succeeds.

This method acts against the principal attached to the calling thread.

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:

~PrincipalPermission();

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

Return to top

Summary

Reconstructs a permission with a specified state from an XML encoding.

C# Syntax:

public void FromXml(    SecurityElement elem );

elem

The XML encoding to use to reconstruct the permission.

Exceptions

Exception Type	Condition
ArgumentNullException	The elem parameter is null.
ArgumentException	The elem parameter is not a valid permission element. -or- The elem parameter's version number is not valid.

Implements:

ISecurityEncodable.FromXml

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

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

Summary

Creates and returns a permission that is the intersection of the current permission and the specified permission.

C# Syntax:

public IPermission Intersect(    IPermission target );

target

A permission to intersect with the current permission. It must be of the same type as the current permission.

Return Value:

A new permission that represents the intersection of the current permission and the specified permission. This new permission will be null if the intersection is empty.

Exceptions

Exception Type	Condition
ArgumentException	The target parameter is not null and is not an instance of the same class as the current permission.

Implements:

IPermission.Intersect

Because two users never intersect, this method is not useful for PrincipalPermission. For example,

              PrincipalPermission ppBob = new PrincipalPermission("Bob", "Administrator");
              PrincipalPermission ppLouise = new PrincipalPermission("Louise", "Administrator");
              PrincipalPermission pp1 = ppBob.Intersect(ppLouise);
            

is equivalent to

              PrincipalPermission pp1 = new PrincipalPermission("", "Administrator");
            

because no identity can simultaneously represent both Bob and Louise. In effect, pp1.Demand() only succeeds if an unauthenticated principal (with name equal to the empty string ("")) is allowed to act in the Administrator role.

Return to top

Summary

Determines whether the current permission is a subset of the specified permission.

C# Syntax:

public bool IsSubsetOf(    IPermission target );

target

A permission that is to be tested for the subset relationship. This permission must be of the same type as the current permission.

Return Value:

true if the current permission is a subset of the specified permission; otherwise, false.

Exceptions

Exception Type	Condition
ArgumentException	The target parameter is an object that is not of the same type as the current permission.

Implements:

IPermission.IsSubsetOf

The current permission is a subset of the specified permission if all demands that succeed for the current permission also succeed for the specified permission.

The following example defines instances of PrincipalPermission corresponding to three distinct users. Two additional instances are then created as groups of users. pp1 represents Bob and Louise, pp2 represents Bob, Louise, and Greg.

//Define users and roles.
PrincipalPermission ppBob = new PrincipalPermission("Bob", "Manager");
PrincipalPermission ppLouise = new PrincipalPermission("Louise", "Supervisor");
PrincipalPermission ppGreg = new PrincipalPermission("Greg", "Employee");

//Define groups of users.
PrincipalPermission pp1 = (PrincipalPermission)ppBob.Union(ppLouise);
PrincipalPermission pp2 = (PrincipalPermission)ppGreg.Union(pp1);

    

With the preceding declarations, pp1.IsSubsetOf(pp2) returns true, and pp2.IsSubsetOf(pp1) returns false.

Return to top

Summary

Returns a value indicating whether the current permission is unrestricted.

C# Syntax:

public bool IsUnrestricted();

Return Value:

true if the current permission is unrestricted; otherwise, false.

Implements:

IUnrestrictedPermission.IsUnrestricted

An unrestricted PrincipalPermission matches any principal.

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

Creates and returns a string representing the current permission.

C# Syntax:

public override string ToString();

Return Value:

A representation of the current permission.

Return to top

Summary

Creates an XML encoding of the permission and its current state.

C# Syntax:

public SecurityElement ToXml();

Return Value:

An XML encoding of the permission, including any state information.

Implements:

ISecurityEncodable.ToXml

Return to top

Summary

Creates a permission that is the union of the current permission and the specified permission.

C# Syntax:

public IPermission Union(    IPermission other );

other

A permission to combine with the current permission. It must be of the same type as the current permission.

Return Value:

A new permission that represents the union of the current permission and the specified permission.

Exceptions

Exception Type	Condition
ArgumentException	The other parameter is an object that is not of the same type as the current permission.

Implements:

IPermission.Union

PrincipalPermission.Union creates a permission representing the criteria of a given set of individual PrincipalPermission objects. It is useful for compactly representing a set of conditions to test. For example, with the declarations

              PrincipalPermission ppBob = new PrincipalPermission("Bob", "Administrator");
              PrincipalPermission ppLouise = new PrincipalPermission("Louise", "Administrator");
            

(ppBob.Union(ppLouise)).Demand() will succeed if the current principal represents Bob in the role of Administrator or Louise in the role of Administrator.

Return to top

Top of page