Manipulating the Security Policy Tree DirectlyBasic Techniques

for RuBoard

Manipulating the Security Policy Tree DirectlyBasic Techniques

One of the key advantages of the .NET Framework security system really lies in its ability to allow for very fine-grained differentiations between assemblies, thus allowing for very fine-grained differentiation of rights to access protected resources. There is now a whole world of semi-trust between allowing code to run or not. Such flexibility is the result of a rich, hierarchically structured, tree-based policy system. The tool itself is simply a graphical instantiation of this model.

In this section, the elements, basic features, techniques, and hints of the tool's policy tree view are introduced. The following sections cover more complex scenarios and actions.

Policy Level Features

Security policy consists of three administrable policy levelsenterprise policy, machine policy, and user policy. You can find the policy levels by simply expanding the Runtime Security Policy Node (see Figure 18.10).

Figure 18.10. Security Policy Level representation in the tool.

The task window will display some general information about policy levels, followed by two important policy level specific pieces of information:

• Whether the selected policy level is used by the security system to determine the permissions an assembly gets, or whether it is a policy level that has been created or loaded in for policy modeling purposes. If the somewhat cryptic statement "This security policy applies to this computer" appears, the policy level information you see and edit will affect assemblies run on your machine.

• The location of the configuration file of the selected policy level.

TIP

Prior to major changes to a policy level, it is often worth making a backup copy of the policy level state before editing. Selecting the policy level in the tree view gives you a quick way to find out (and copy and paste) the file path to the configuration file.

The only option that right-clicking any one of the policy levels in the tree view will give you is the option to do a Reset. This will set the selected policy level back to the default policy statethe way the respective policy level was configured on install of the .NET Framework. The default policy has been designed to be a safe default and represents a good point of return if you want to start fresh in designing the policy of the respective policy level. For more information, please see the "Resetting Security Policy" section later in this chapter.

NOTE

You will only succeed in resetting a policy level if you have write access to the respective policy configuration file. Both the enterprise and machine policy configuration files are in directories to which only users with machine administrator rights have access. ACL settings typically prevent other users from access to these system locations.

Every policy level consists of three constituents:

• Code Group Hierarchy The tree of code groups determines how the set of all assemblies is partitioned to give various subsets of assemblies a specific level of permissions to access protected resources.

• Permission sets All the named permission sets that can be referenced in the code group hierarchy at the respective policy level. A permission set is simply a set of statements of access to protected resources.

• Policy Assemblies A list of all assemblies that security objects accessed during policy evaluation depend on.

When you expand a policy level node, you will indeed find each of the three constituents of a policy level mentioned. In Figure 18.11, you can see how expanding the machine policy node revealed code groups, permission sets, and the policy assemblies list.

Figure 18.11. Accessing the constituents of a policy level.

We will now give an explanation of the available features and administrative techniques enabled on eachthe features available for code group manipulation, viewing, and changing permission sets, as well as altering the policy assemblies list.

Code Group Hierarchy

Every policy level contains a tree of code groups that express the configuration state of that policy level. You can think of a code group simply as a form of conditionalit checks some condition about an assembly, such as whether the assembly came from a specific URL. If the condition is met, it then allots a permission set to the respective assembly. Each code group represents one way to slice up the set of assembliesit "groups code," hence, its name . The code group hierarchy simply is a tree of these conditionals (for more detail on the underlying model, see Chapter 8).

When you expand the Code Groups folder, you will always be brought to the root of the code group treethe All_Code group. It cannot be deleted, because a policy level must always contain at least one code group (see the User and Enterprise policy levels in the default Runtime Security Policy for examples). The tool offers a variety of features that help in the administration of code group hierarchies.

Creating a New Code Group

One of the most common ways to fine tune security policy is to add another code group under an already existing one. This can be used to further differentiate between assemblies if the parent code group applies. As an example, look at the way the default machine policy is set up (see the expanded code group tree under the Machine node in Figure 18.12).

Figure 18.12. Machine policy code group tree in default policy expanded.

Suppose that you add a new code group under the Internet code group, let this code group check for a strong name of company X, and grant full trust to access protected resources. The result would be that all assemblies coming from the Internet zone would get whatever the default policy allows them except for all assemblies whose origin is the Internet zone and that are signed with company X' s strong name. Those assemblies would receive default policy permissions for the Internet and the permissions granted by the added code group, amounting to being granted full trust to access all protected resources at this policy level.

NOTE

Always remember that the permissions granted to an assembly from one policy level are intersected with the permissions the assembly is given at other policy levels (unless Level Final code group attributes are used).

You can create a new code group as a child code group under any code group in the code group tree. This includes the root of the code group hierarchy (the All_Code group), as well as any leaf nodes in the code group hierarchy. The tool includes a wizard that will help you create a new code group and set all its properties.

You can access the New Code Group Wizard by performing the following steps:

1. Right-click the code group under which to insert the new code group.

2. Select New.

After you have started the Wizard, you have the choice of either creating a new code group from scratch or importing one from an XML file (see Figure 18.13). The latter option will be explained in the "Dealing with Custom Code Groups" section later in this chapter, and is, as you may suspect, used to import code groups that have been custom authored into policy. The far more common option is to just create a code group from scratch by filling in all necessary properties.

Figure 18.13. Choosing to create a new code group from scratch or importing one from an XML file.

All code groups have a name and optionally a description. You can leave out the description when first creating a code group, although it is a good practice to make an annotation here of what the addition of this new code group is intended to accomplish. This is an easy way to remind yourself at a later time what that policy change was intended to accomplish, greatly helping you to find potential security issues or unintended side effects. The code group name is mandatory. That name is used by the tool as a label for a code group. It can also be used to write a policy change script against (see Chapter 19, "Administering .NET Framework Security Policy Using Scripts and Security APIs"). For that reason, it needs to be unique within the policy level. The tool will reject any duplicate code group name entry within a policy level.

Each code group also consists of a membership condition (testing an assembly for a specific piece of evidence, such as a specific site of origin) and a permission set that is granted if the membership condition applies. After selecting a name and description, the tool will ask you to select a membership condition type and, if applicable , you must supply a membership condition value (such as a specific site) for which this code group should check (see Figure 18.14).

Figure 18.14. Selecting a membership condition for the new code group.

The following are the membership condition types available:

• All Code As its name implies, all code irrespective of origin will pass this membership condition. If you choose this membership condition for your code group, the assembly reaching this code group during policy evaluation is guaranteed to receive the permission set you associate with this code group. All Code is something like a pass key for a code group's membership condition.

• Application Directory This membership condition is met if an assembly comes from the same application directory as the assembly that is currently being executed. This code group can be used to distill assemblies comprising a specific managed application from other assemblies.

• Hash This membership condition succeeds if the hash value of an assembly matches with one defined in the membership condition value. Hash values are highly unique identifiers for larger pieces of data or code. Code groups with hash membership conditions are used as a cryptographically strong (hard to spoof) means of identifying one specific assembly, especially if the assembly neither has a strong name nor a publisher certificate. This membership condition is used by the Trust Assembly Wizard if it cannot find either a strong name or publisher certificate on an assembly.

  The tool allows you to either type in or import a hash value from a specific assembly. The latter is suggested because typing mistakes in a hash membership condition value could easily cause hard-to-trace security policy issues. Unless you are certain otherwise , always use SHA1, because this is the preferred hash function compared to MD5.

• Publisher Checks for a specific X.509v3 publisher certificate. Only code that has been authenticode signed by the publisher chosen when setting up this code group will meet this membership condition. This code group is typically used to identify a set of assemblies from a specific publisher and grant it more rights based on that information, while other assemblies, everything else being equal, would not receive that level of trust. For example, you could extend the default policy by adding a new code group under the Internet code group, with a publisher membership condition, and set the publisher certificate to a publisher you trust, and set the permission set to full trust. This would have the effect of leaving the default policy as is except for the assemblies from the trusted publisher, which get a higher level of permissions to access protected resources.

  The tool allows you to set the membership condition value in two ways. The simplest way is to point the tool to an assembly that has been authenticode signed by the publisher; use Import from Signed File for this option. Alternatively, you may have an actual certificate file handy (typically with .cer extension). You can point the tool at that file using the Import from Cert File option.

• Site The site membership condition checks whether an assembly came from a specified site. Code groups with this membership condition are often used if all assemblies from a designated site are to receive higher levels of trust compared to assemblies from other sites.

  To specify the site that this membership condition should check for, simply type in the site name.

• Strong name The strong name membership condition checks whether an assembly has been strong name signed and matches the specific strong name defined in the membership condition value. Like the publisher certificate and hash values, a strong name is a cryptographically strong form of evidence that can be used to uniquely identify an assembly or set of assemblies. Code groups with this membership are often used to mete out a high level of permissions based on this strong form of evidence. For example, if you look into the machine policy level of default policy, you will find a code group named Microsoft_strong_Name under the MyComputer zone code group. It is used to give all assemblies strong name signed by Microsoft full trust to access protected resources, enabling, among other things, the tool to continue to function, even if other code on the local machine has been constrained.

  If you want a code group to apply to all assemblies from a given strong name publisher, you only need to supply the strong name public key, either by browsing to a strong name signed file (the highly suggested method) or by typing it in yourself. If you want only one particular assembly by a given publisher to be checked, irrespective of its version, you also need to check the name and can only use the Import function to set up the public key. If you want a specific version of a specific assembly of a publisher to be checked for, also mark the Version check box. To set the correct version, you need to use the Import function to browse to the respective assembly for which you want the membership condition to check.

• URL This membership condition checks whether an assembly came from the supplied URL. Code groups with this membership condition are often used to increase the level of trust given to specific intranet shares or mounted drives .

  The tool requires you to simply type in the URL value. It is important that you remember to suffix drive names and shares with the \* symbols if you want the membership condition to apply to all files and subdirectories at the specified location.

• Zone This membership condition checks whether an assembly comes from a given zone. For examples of how code groups with such membership conditions are used, please browse through the default policy, which is based around the concept of zones.

CAUTION

Use the site, zone, and URL membership conditions with caution because they could allow very wide broadening of security policy. You should always ask yourself whether you really can trust all assemblies at the specified site, zone, or URL before increasing any permissions based on these types of evidence.

• Custom The .NET Framework security system is fully extensible with custom security objects. It is possible to write your own membership conditions, code groups, permissions, and so on. The custom option in the tool is used to import any custom written membership condition into security policy. To do so, you must browse to an XML file representing the XML serialization of the custom membership condition type.

TIP

If you have a lot of child code groups under a parent node and you'd like to group them into different categories for policy readability, but don't want to impact the actual security policy resolution for any assembly, simply use a code group with membership condition All Code and associated permission set to Nothing. For example, if in the default policy the Internet and intranet permission set were both under a code group Internet/Intranet Groups, which in turn is a child code group of the All_Code group, the actual results for any assembly is exactly the same as if you left the security policy in the default policy state. Code groups with an All_Code membership condition and a Nothing permission set just don't add anything to policy evaluation.

After you have chosen the membership condition for the new code group, you then need to decide what the permissions are that this code group should hand out. In a sense, by defining the membership condition, you have defined a filter that assemblies are required to pass through before being given a set of permissions. The next Wizard page will present you with two options to set that level of permissions to be handed out to an assembly if it matched the membership condition (see Figure 18.15).

Figure 18.15. Selecting a permission set for the new code group.

You can choose a permission set that is already known and "registered" at the policy level in which you are editing. Alternatively, you can also elect to create a newly named permission set that is returned by the newly created code group. In that case, the Wizard to create a new permission set is started. The newly created permission set is available afterward for reference in other code groups as well.

TIP

When in doubt as to the level of access to protected resources that a specific named permission set stands for, use the Permission set node and inspect permission sets prior to assigning them to a code group. You may forget to double check later and, as a result, the newly created code group may grant a level of permissions that you definitely did not have in mind.

Deleting a Code Group

Except for the root code group, you can delete any other code group in a code group hierarchy. Deleting a code group may have some strong side effects; the following are some of the possible implications:

• All child code groups are deleted also; you will lose any customizations you had done at that level in the code group hierarchy.

• Batch scripts to change security policy can break because both the code group labeling will change as well as one or more code group names may become unavailable.

• Assemblies that received the necessary permissions from the deleted code group to run properly will break.

Consequently, you should be cautious and try to be aware of all the possible side effects before deleting a code group.

If you have decided to delete a code group, you can do so by simply selecting it in the code group hierarchy and pressing the Delete key or, alternatively, right-clicking it and choosing the Delete option. Let me mention again that this will delete the whole subtree of code groups if the selected code group is a parent to other code groups.

Renaming a Code Group

Every code group has a name associated with it. This name is used both as the display name in the tool as well as a way to write a batch script to change security policy. When renaming a code group, the tool does not allow you to use a name already in use by another code group at that policy level. This would both make the tool's code group display ambiguous and any policy change scripts based on code group names indeterministic.

CAUTION

Make sure that you do not have any security policy change batch scripts that rely on the code group name you are changing. See more on administrating policy using batch scripts in Chapter 19.

To rename a code group, simply right-click it and select the Rename option. The tool will check whether the name is already in use.

Making a Duplicate of a Code Group

The tool allows you to select any code group and duplicate it, including any child code groups the code group may have. The tool will automatically rename the duplicate to avoid name conflicts by prepending a "Copy of" to the original name. You can use the Rename option to give it a more pleasing and descriptive name.

TIP

If there is a code group or subtree of code groups that is already very close to something you want to add to policy, it can be of great help to simply generate a duplicate, make the few changes necessary, and then move it to the place in the policy hierarchy where you intended to make the change.

To duplicate a code group, including all its child code groups, right-click the respective code group and select the Duplicate option.

Moving a Copy of a Code Group into Another Policy Level

Because the final permission grant to an assembly depends on the intersection of all permissions granted at the enterprise, machine, and user policy levels respectively (see Chapter 8), it may be necessary to copy a large part of a code group hierarchy of one level into one of the two remaining policy levels. For example, this would be necessary if user or enterprise policy are changed from granting unrestricted permissions at the root of their code group hierarchy. For such cases, the tool provides a quick and easy way to copy whole code group trees between policy levels.

Simply drag-and-drop the respective code group or tree of code groups to the desired spot in another policy level.

Moving a Code Group Within a Policy Level

Changing the position of a code group within a code group hierarchy can strongly influence security policy. For example, if you move the Microsoft_strong_Name code group in default policy from its default position under the MyComputer code group to the LocalIntranet code group, all assemblies signed with the Microsoft strong name would now only receive the FullTrust permission set either when run from the local intranet or when run from the local computer (default policy grants full trust to access protected resources to all assemblies installed on the local machine).

You can move a code group and all its child code groups to a new position in a code group hierarchy simply by dragging and dropping it.

Editing a Code Group

All properties of a code group can be viewed and changed from a code group's property page (see Figure 18.16). You can open a code group's property page by right-clicking the code group and selecting the Property option.

Figure 18.16. Editing a code group using the code group's property page.

In addition to the membership condition, permission set, name, and description, all of which had to be defined during the creation of a code group in the tool, the Level Final and Exclusive properties can also be set.

If a code group with the Level Final property (the second check box in Figure 18.16) switched on applies to an assembly, no policy level below the one currently evaluated is taken into account in the permissions calculation for that assembly. This property is very useful when you must make certain that no administrable policy level below the one you are editing should interfere with the permission grant an assembly receives. Obviously, this will also prevent any policy customizations done in lower policy levels from being effective, so this property should be used in a very targeted and sparing way.

NOTE

Security policy for an assembly is always evaluated starting with the enterprise security policy level, the machine policy level, user policy level, and then the application domain policy if it has been set programmatically by a host of the .NET Framework Runtime. Applying the Level Final attribute to a code group in user level policy will have no effect whatsoever because the Level Final attribute only applies to administrable policy levels.

Another property that can be set using a code group's property page is the Level Exclusive property (see the first check box in Figure 18.16). If a code group with this property turned on applies to an assembly (in other words, if the code group's membership condition matches the evidence of an assembly for which policy is being resolved), no other code group at that policy level will contribute to the permissions that the assembly receives from that policy level. As a result, this property is an "override" over all other code groups in a policy level. It can be used very effectively if you want to lower the level of trust for a select set of assemblies. For example, if you want to alter default policy to "sand box" a region on your local hard drive, you could add a code group with a URL membership condition of the hard drive path and the Internet permission set under the MyComputer code group, and then check the Level Exclusive (first check box) property for that code group.

CAUTION

The security system will throw an exception and the evaluated assembly will not run, if, at a single policy level, the assembly's evidence matches more than one code groups that have the exclusive property turned on.

This is the case because the semantics of the level exclusive property stipulates that all other code groups are excluded from contributing to the assembly's permission calculation. When more than one level exclusive code groups apply to an assembly, an inherently ambiguous state ensues, causing a security exception to be thrown.

Dealing with Custom Code Groups

With the exception of the child code groups of the intranet code group, default policy contains only so called "union code" groups. A union code group adds together all the permissions given by all applicable child code groupshence, the name union code group. Because this is the most common form of code group, the tool has very deep support for these code groups and allows easy viewing and editing of its properties. However, the security system is fully extensible, so code groups implementing completely custom defined semantics can be used in security policy. This adds great flexibility. For example, it is possible to implement a code group that depends on the date and time to grant its permissions. On the other hand, this flexibility also means great strain on having full user interface support for editing a custom code group's properties. As a result, in version 1.0 of the .NET Framework

Configuration tool, custom code group properties cannot be edited directly in the user interface.

A custom code group is symbolized as shown in Figure 18.17.

Figure 18.17. Non-union code group symbol in the tool.

Whenever you see this symbol in the code group hierarchy, you know that the respective code group is not a union code group. With the exception of the name and description, you cannot change any properties for these code groups on their property page, nor can you set their properties when creating them via the New option. Non-union code group property pages only include the code group's name, description, and XML serialization.

Non-union code groups are added to policy by right-clicking a desired parent code group and selecting the New option. Instead of choosing the Create a New Code Group option, you should choose the Import a Code Group from an XML File option (see Figure 18.18).

Figure 18.18. Creating a custom code group by importing its XML serialization.

All custom code group XML serializations have the following format:

 <CodeGroup class="fully qualified class name of code group type,  assembly name, Version=version number,  Culture=culture value, PublicKeyToken=strong name public key token"            version="1"            Name="Code group name"            Description="code group description"          [Custom Code group attributes] >    [Custom code group XML] </CodeGroup> 

If you try to import a custom code group and the import fails, you should check whether the file indeed follows the schema just shown. The Name and Description attributes are optional, and import of the code group should still succeed, even if both are missing.

If you want to change any properties on a custom code group, you need to delete the outdated custom code group, change the custom code group XML to the desired state, and re-import the code group serialization. You should get directions on doing so, potentially even a little tool, from the vendor distributing the custom security code group.

CAUTION

You have to add the assembly implementing the custom code group, as well as all assemblies it depends on to the policy assembly list in the policy level to which you are importing the custom code group. Please see the "Policy Assemblies" section later in the chapter.

Administrating Permission Sets

Every policy level contains a list of named permission sets. These permission sets can be referenced by one or more code groups in the code group hierarchy of that policy level. Code groups always refer to permission sets by the permission set's name. Thus, a code group will continue to refer to a permission set, even if you change all properties except for the permission set's name.

Each permission set represents a statement of trust to access a variety of protected resources. Permission sets allow for very fine-grained and granular access control to protected resources. As its name implies, a permission set is just a list of individual permissions. Each permission covers exactly one protected resource. The .NET Framework ships with a large set of built-in permission types that are used throughout the .NET Framework Base Class Library to protect resources, such as the file system and the registry.

Not surprisingly, you can find the list of known named permission sets of a policy level by expanding the Permission Set node under a policy level node (see Figure 18.19).

Figure 18.19. Finding the permission sets known at a policy level.

Default security policy ships with a number of permission sets (seen in Figure 18.19) that are used to build default policy. To find out what these permission sets contain, please see the next section, "Viewing a Permission Set." All of the permission sets shipping with the .NET Framework are immutable, with the exception of the Everything permission set.

Viewing a Permission Set

To find out what permissions a particular permission set includes, select the permission set in question.

Unless you had previously unchecked the Help topic check box (see Figure 18.20), simply click on the View Permissions link. If you always want to see the permissions for the selected permission set directly without being bothered by the Help screen, simply uncheck the Show This Help box.

Figure 18.20. Viewing a permission set using the View Permissions task.

The right view will now contain the list of permissions that are part of the permission set. If the permission set does not include a particular permission type, that permission is not granted at all through that permission set. So for example, if you look at the included permission types for the LocalIntranet permission set (used by the default policy for all assemblies from the intranet), you will notice that the FileIO permission is completely lacking, which means that assemblies receiving just this permission set have no access rights to the file system.

Because each permission typically has a number of states it can be configured to, simply looking at a list of included permission types in a permission set still does not give a full picture of exactly what that permission set would grant to assemblies. For example, the inclusion of the Registry permission type in a permission set may mean that it is set to grant unlimited access rights to write and read from the registry, or it may only grant read rights to a few locations. Consequently, you have to view the state of the individual permissions included in a permission set to truly find out what the permission set grants. To do so, just right-click the permission in question and select the View Permission option.

Creating a New Permission Set

The tool includes a wizard that helps you build a new permission set from permission types that ship with the .NET Framework or even from custom written permissions.

To start that wizard, right-click the Permission set node under the policy level in which you want to create the new permission set and then select the New option.

You will first need to enter the new permission set's name and a description. Because permission sets are referenced from code groups by their name, you must enter a name that is not already used by another permission set at that policy level. Alternatively, you can import a permission set from its XML serialization.

NOTE

The description is optional, but you should get in the habit of including description annotations wherever you can. This will make it easier to find any problems with security policy later.

After a name and description have been chosen, you will be presented with the wizard page shown in Figure 18.21.

Figure 18.21. Adding permissions to a new permission set.

To add a permission that ships in the .NET Framework, simply select the permission in question and then click the Add button. You will be prompted to fill in the necessary properties for the permission (such as file paths and read/write rights for the FileIO permission). If you change your mind about the inclusion of a particular permission, simply use the Remove button to put a permission in the permission set back into the Available Permissions category. You can also add in a custom authored permission by using the Import button on this wizard page.

Building the right permission sets that express exactly the level of trust you need in your administrative scenarios can be an art. Think carefully about what permissions to include; the more you include, the more potential security holes you may open.

Be especially wary of giving out anything more than execution rights on the security permission, any FileIO or registry rights, and reflection emit rights.

Editing a Permission Set

It is quite easy to change an arbitrary permission set, with the exception of the permission sets shipping with the .NET Framework. Except for the Everything permission set, no permission set that ships with the .NET Framework can be edited. However, any user-defined permission set is freely changeable .

To edit a permission set (such as the Everything permission set or any user-defined permission sets), simply right-click it and select the Change Permission Set option. This will return you to the Permission Selection Wizard page (see Figure 18.21). To change the state of a permission already included in a permission set, simply select the permission and click Properties. To add or remove further permissions, use the Add and Remove buttons .

CAUTION

If you are modifying a permission set because one code group referencing it gives the wrong permissions, please make sure that no other code group in that policy level references that permission set. If so, you must be very careful that fixing a policy problem for some assemblies will not create one for another set of assemblies.

Duplicating a Permission Set

Instead of starting from scratch when creating a new permission set, you could also make a duplicate of an already existing one and modify the copy until it fits your needs. This may be much faster than using the New option if there is already a permission set quite close to the permission set you have in mind.

This option also greatly helps get around the restriction that the permission sets the .NET Framework ships with cannot be modified; simply make a copy of an immutable permission set and change the copy. This can come in handy if you want to slightly alter what the default policy grants to various zones. For example, if you do not want the Intranet zone to grant unlimited user interface rights, simply duplicate the LocalIntranet permission set, modify the UserInterface permission in it, and have the Intranet code group point at your modified permission set.

To duplicate a permission set, simply right-click it and select the duplicate option. You will probably want to change the name to something more suitable than something starting with "Copy of".

Renaming a Permission Set

You can rename a permission set by right-clicking it and selecting the Rename option. This feature is not available for the permission sets that ship with the .NET Framework (except for the Everything permission set).

NOTE

You would break a code group if you changed the name of a permission set that is referred to by that code group. For that reason, the tool will search the code group hierarchy and only allow you to change the name of a permission set it is not referenced.

Copying a Permission Set Between Policy Levels

You can copy a permission set from one policy level's folder of known permission sets to another policy level's folder of known permission sets by dragging and dropping the respective permission sets into the target permission set folder.

NOTE

If you have copied a code group to a policy that does not contain the permission set referenced by that code group, you do not need to manually copy the referenced permission set over. The tool will automatically copy the referenced permission set to the target policy level's permission set folder if the referenced permission set name is not known at that policy level.

Dealing with Custom Permissions and Permission Sets

The .NET Framework security system is fully extensible and allows for, among other things, the inclusion of custom security permissions and custom security permission sets.

It may become necessary to include custom permissions in security policy when the built-in permissions do not cover a particular resource, such as an enterprise-specific database system with time share properties.

To include a custom permission in a permission set, click the Import button on the wizard page used to add permissions to a permission set (see Figure 18.21). By choosing to import a custom permission, you will need to browse to an XML file containing the XML serialization of the custom permission. The format for all custom permission XML files is as follows:

 <IPermission class="fully qualified Class name of permission, assembly name containing custom permission, Version=version of assembly, Culture=culture value, PublicKeyToken="strong name public key token of assembly"                                  version="1"      [custom permission attributes]  >      [custom permission XML] </IPermission> 

If the file you browse to does not have this general format, the import will fail. Please see the custom permission vendor or author's documentation for more detail on how to change permission state using the permission's XML serialization.

Not only permissions, but whole permission sets can be custom written security objects. To create a custom-named permission set in security policy, click the Import a Permission Set from an XML File button on the start page of the new Permission Set Wizard (right-click the permission set folder and select New (see Figure 18.22).

Figure 18.22. Creating a custom named permission set.

CAUTION

You have to add the assembly implementing the custom permission or permission set, as well as all assemblies it depends on, to the policy assemblies list in the policy level to which you are importing the custom permission or permission set. Please see the next section, "Policy Assemblies."

Policy Assemblies

Besides a code group hierarchy and the named permission sets, every policy level also contains a list of so-called policy assemblies. These are assemblies that either implement a security object (such as a membership condition, permission, permission set, or code group) directly or that these assemblies depend on. In other words, this list should contain the transitive closure of assemblies implementing custom security types.

For all security objects that ship with the .NET Framework (such as the FileIO permission type), all the right entries into this list have already been made; you do not need to worry about changing entries here if you are not using custom security objects. However, if you are adding custom security objects (such as customer membership conditions, code groups, permissions, or permission sets), you must enter the assembly or assemblies implementing the custom security object and all assemblies on which that implementing assembly (or assemblies) depend. Typically, the documentation from the vendor of the custom security object should let you know what these assemblies are and how to find them.

NOTE

You may ask why this list is necessary. Consider the following scenario. You have implemented a custom permission P in assembly A and have referenced P from a code group in machine policy. You are then starting up assembly B. Security policy is evaluated for B. It so happens that B's evidence matches the code group from which you reference P. The security code now tries to instantiate P accessing assembly A in which P is implemented. However in doing so, A itself causes a security policy resolution for it to happen, and it turns out that A also matches the new code group. A circular security policy evaluation dependency ensues. Assembly A waits to finish security policy evaluation until assembly A has been evaluated. To break this possible dead-lock, the policy assemblies list has been introduced, short circuiting any policy evaluation for the assemblies in that list for that policy level.

You can access the policy assembly list for a policy level by clicking the Policy Assemblies folder. If you are viewing this list for the first time, click the View Policy Assemblies link. You will then see the list of assemblies that are currently "registered" for the implementation of security types at that policy level (see Figure 18.23).

Figure 18.23. The Policy Assemblies list.

To add an assembly to this list, just right-click the Policy Assemblies folder and choose the Add option. You will then be able to select an assembly from the .NET Framework global assembly cache.

TIP

You need to have added the assembly you want to include in the Policy Assemblies list to the GAC (Global Assembly Cache) first. To do so, right-click on the Assembly Cache node in the main tree view of the tool and select the Add option. That will allow you to browse to the assembly you want to add to the cache. The assembly must be strong name signed for it to be added to the cache.

Adding an assembly to this list has the effect of giving it a full trust policy resolution at that policy level. If an assembly is listed in the Policy Assemblies lists of all three administrable policy levels, it will receive full trust to access all protected resources by the policy system. But again, this only is the case if it is present in all lists. If your goal is to give an assembly or set of assemblies full trust to access all protected resources, you should use the Trust Assembly Wizard or manipulate the code group hierarchy, not use this list.

If you want to delete an assembly from the Policy Assemblies list, right-click the respective assembly and select Delete.

CAUTION

The only reason why you should ever want to delete entries from the Policy Assemblies list is if you have excluded custom security objects from a policy level and the respective assemblies implementing the custom security object are no longer needed. If you delete assemblies that implement or are needed for the implementation of a security type at that policy level, you can cause the security system to deadlock. Be very careful when deleting any entry from this list!

Undoing a Change in the Policy Tree

You can undo the latest policy change you have made to a policy level by selecting the policy level, right-clicking it, and then choosing the Undo option. Policy changes are cached on a per-policylevel basis, so you can undo the latest change you made in machine policy, even though you have just edited enterprise policy.

NOTE

The tool will lose the per-policy level cache of latest policy changes when you shut it down.

for RuBoard