Membership Conditions

for RuBoard

Membership conditions provide the first step in turning the evidence of an assembly into a grant set. At its most basic level, a membership condition is an object that can answer "yes" or "no" when asked if an assembly matches its membership test. For example, a membership condition object can be constructed to only answer "yes" if an assembly is being loaded from the Web site www.microsoft.com.

The following are some key points to understand about membership conditions:

Membership conditions and evidence are closely linked.
The .NET Framework provides several membership conditions by default.
Membership conditions are extensible security objects, so developers can define their own.

Membership Conditions and Evidence

As mentioned in Chapter 5, "Evidence: Knowing Where Code Comes From," evidence on an assembly by itself does nothing without a membership condition that uses the evidence. This is similar to buying something using a credit card. If the merchant doesn't accept credit cards and the consumer has no other method to pay, the customer cannot buy the goods. If an assembly has evidence that no membership condition classes use, the evidence is useless.

Membership conditions have no other purpose than to match evidence provided for an assembly while it is loading. However, membership conditions can check more than one kind of evidence at once. For example, the ApplicationDirectoryMembershipCondition uses ApplicationDirectory evidence and Url evidence. Thus, each type of evidence can be examined by multiple types of membership conditions.

If a membership condition exists in policy that looks for evidence types not provided for an assembly, the membership condition simply doesn't match it. It is not an error or fatal condition.

Membership Conditions Provided by the .NET Framework

Membership condition classes are provided by default that match evidence classes provided by the .NET Framework. Table 8.1 lists the membership conditions provided by the .NET Framework. They all reside in the System.Security.Policy namespace. Note the similarity of Table 8.1 to Table 5.2, which lists all the default evidence classes.

Table 8.1. Full List of Default Membership Conditions Provided by the .NET Framework

Membership Condition Class	Description
`AllMembershipCondition`	This matches all code, regardless of what evidence is provided.
`ApplicationDirectoryMembershipCondition`	This looks at the `ApplicaitonDirectory` evidence and `Url` evidence. (Both kinds of evidence must be present to match the membership condition.) The provided URL must be contained somewhere in the application directory. For example, if the application directory is `C:\myapp` , the URL path must start with `C:\myapp` , such as `file://C:\myapp\test.dll` .
`HashMembershipCondition`	This compares `Hash` evidence to a hash value stored in the membership condition itself.
`PublisherMembershipCondition`	This compares the Authenticode signing certificate from `Publisher` evidence to a certificate stored in the membership condition itself. The comparison of certificates is based solely on their public keys.
`SiteMembershipCondition`	This compares `Site` evidence to a site stored in the membership condition itself.
`StrongNameMembershipCondition`	This compares the `StrongNamePublicKeyBlob` , `Name` , and `Version` in `StrongName` evidence to the same kinds of values stored in the membership condition itself. The `Name` and `Version` can be `null` , but the `StrongNamePublicKeyBlob` cannot be `null` .
`UrlMembershipCondition`	This compares `Url` evidence to a URL stored in the membership condition itself.
`ZoneMembershipCondition`	This compares `Zone` evidence to an IE Security Zone stored in the membership condition itself.

Writing Custom Membership Conditions

As with many kinds of security objects in the .NET Framework, membership conditions are extensible. You can define your own membership condition that uses any default or custom-written evidence. To write your own membership condition, you need to define a class that implements the following interfaces:

IMembershipCondition ” Defines key membership condition methods
ISecurityEncodable ” Defines methods to convert objects to/from the XML representation used by .NET Framework security
ISecurityPolicyEncodable ” Same as ISecurityEncodable , but the methods to convert to/from XML also take the policy level into account

Microsoft provides an example custom membership condition with a whitepaper at http://www.gotdotnet.com. You might find this helpful if you want to implement your own membership condition.

TIP

If you plan on creating a custom evidence class and a corresponding custom membership condition class, you should place both classes in the same assembly. The resulting assembly will need to be added to the "policy assembly list" of security policy, so creating multiple assemblies would require you to place all of them in this list.

In addition to the assemblies that define your custom policy classes, you will need to add the transitive closure of all referenced assemblies to the policy assembly list. That is, all assemblies your custom policy classes rely on will also need to be added to the list.

The `IMembershipCondition` Interface

The IMembershipCondition interface defines the primary methods that a membership condition must implement. It has four methods:

Check ” This is the fundamental method of a membership condition. It returns true or false to note if a given assembly's evidence matches the membership condition.
Copy ” This simply returns a new membership condition object that is equal to the current membership condition.
Equals ” This determines if two membership condition objects have equivalent states.
ToString ” This prints out a friendly name for the membership condition. The output is used in security policy administration tools like caspol .exe .

The `ISecurityEncodable` Interface

The ISecurityEncodable interface defines methods that allow the security policy engine to serialize and deserialize membership conditions. It has two methods:

ToXml ” This method turns the given membership condition into a SecurityElement , which is the intermediary between raw XML text that represents a security object and the security object itself. It takes no arguments.
FromXml ” This converts a SecurityElement into a membership condition. The only argument is the SecurityElement to translate.

NOTE

The System.Security.SecurityElement class defines a lightweight, XML object model for security objects. It exists so that each security object doesn't need to understand XML or call into a general-purpose XML parser.

Attributes of SecurityElements are name/value pairs in the XML object. Security objects generally store internal states in attributes. Children are nested XML objects inside a given SecurityElement . Membership conditions don't have children, but code groups (which are covered later in this chapter) do.

The `ISecurityPolicyEncodable` Interface

The ISecurityPolicyEncodable interface provides an additional way for the security policy engine to serialize and deserialize a membership condition. It has two methods:

ToXml ” This is similar to the ToXml method on the ISecurityEncodable interface. It converts a membership condition to a SecurityElement . However, this method also takes a PolicyLevel object as an argument in case the translation would differ depending on the PolicyLevel .
FromXml ” This is similar to the FromXml method on the ISecurityEncodable interface. As with this interface's ToXml method, the difference is that it takes a PolicyLevel as an argument.

NOTE

No default membership conditions in the .NET Framework create SecurityElement s differently when called with the ISecurityPolicyEncodable methods as compared to the ISecurityEncodable methods. The ISecurityPolicyEncodable interface is provided for the possible benefit of developers writing custom membership conditions.