Customizing the Microsoft .NET Framework Common Language Runtime

As the managed code programming model becomes more widely adopted both within Microsoft and in the community in general, the range of capabilities available through managed class libraries will continue to grow. This trend will become even more apparent in future versions of the Microsoft Windows operating system when more and more of the existing Microsoft Win32 API is superseded with managed class libraries. However, not all of the capabilities available to add-ins through managed class libraries are appropriate in all hosting scenarios. For example, the ability to display a user interface doesn't fit at all in server scenarios, and the ability to call a managed API that will cause the process to exit isn't appropriate in hosting scenarios that require long process lifetimes.

What's required is a mechanism for an extensible application to block certain categories of functionality that don't fit with its overall programming model. The CLR hosting interfaces offer a feature called host protection that is designed specifically for this purpose. Because host protection is exposed through the CLR hosting interfaces, your application must be a full CLR host to use the feature.

The host protection feature identifies categories of functionality that are deemed of interest in various hosting scenarios. Hosts can then indicate that certain categories of functionality are not allowed within the host's process. Examples of host protection categories in Microsoft .NET Framework 2.0 include the ability to share state or perform synchronization across threads, the ability to affect the host's process or any of its threads, the ability to display user interface, and so on.

Given the identification of the host protection categories, two steps are necessary to enable a host to prevent categories of functionality from being used in their process. First, the .NET Framework class libraries must be annotated with a custom attribute called the HostProtectionAttribute that identifies which APIs belong to which categories. For example, the System.Threading.Thread class has several methods that would allow an add-in to affect how threads are created and used within a process. These members have all been marked with the HostProtectionAttribute, indicating that they belong to the threading category. HostProtectionAttribute is typically applied to types and members, but can also be applied to entire assemblies, value types, and delegates as well. Also, members of interfaces can also be annotated. In this case, all implementations of those methods in derived classes are automatically considered annotated as well. The annotation of the .NET Framework class libraries has been done as part of the version 2.0 release. The host must then enable host protection by indicating which categories of functionality should be blocked. This is done using the host protection manager in the CLR hosting interfaces. Specifically, the host asks the CLR for an interface of type ICLRHostProtectionManager through which it tells the CLR which categories should be blocked.

The host protection feature in its current form has been designed specifically with the requirements of the Microsoft SQL Server 2005 host in mind. This design is apparent in two ways. First, the host protection categories that have been defined in .NET Framework 2.0 are designed specifically to meet the needs of the SQL programming model. Second, not all of the .NET Framework class libraries have been annotated with the HostProtectionAttribute. Only those assemblies that SQL Server 2005 allows in its process have been annotated. (SQL Server uses an assembly loading manager to restrict which .NET Framework assemblies can be loaded, as described in Chapter 8.) The methods and types in an assembly that has not been annotated cannot be blocked using host protection. As time goes on, I expect both that the number of host protection categories will be expanded to meet the needs of other hosts and that the number of managed code libraries that are annotated with HostProtectionAttribute will increase. Nevertheless, if your hosting requirements are similar to those of SQL Server, you might find the current host protection categories adequate.

The goals of host protection are often confused with the goals of Code Access Security (CAS) for obvious reasonsboth are techniques used to prevent a particular class or method from being used in a process. However, the motivation behind these two features is quite different. CAS is about protecting your process and the machine on which it is running from malicious access to protected resources, whereas host protection is merely about enforcing specific characteristics of a given host's programming model. The difference between CAS and host protection can best be seen by looking at the consequences that could occur were each feature to be compromised. A vulnerability in CAS (or its use) results in unauthorized access to a protected resource, or a security vulnerability. In contrast, compromising host protection results only in a violation of the programming model. Such a violation can cause the host to perform poorly or even to crash, but it does not allow unauthorized access to a protected resource. There is one case in which CAS and host protection are directly related, however. When a host specifies that certain categories of functionality should be blocked, those categories are blocked only for partially trusted assemblies. Assemblies granted full trust are exempt from host protectionthey can use any API they want.

This chapter describes how to use host protection to limit the functionality available to the add-ins you load into your extensible application. I start by describing the host protection categories. The description of each category includes a list of the types, methods, and properties that are currently identified as belonging to that category using the HostProtectionAttribute. After the categories are described, I show you how to use ICLRHostProtectionManager to tell the CLR which categories should be blocked.