The Host Protection Categories

The host protection categories are defined by the HostProtectionResource enumeration from the System.Security.Permissions namespace:

[Flags, Serializable]    public enum HostProtectionResource    {        None                        = 0x0,        Synchronization             = 0x1,        SharedState                 = 0x2,        ExternalProcessMgmt         = 0x4,        SelfAffectingProcessMgmt    = 0x8,        ExternalThreading           = 0x10,        SelfAffectingThreading      = 0x20,        SecurityInfrastructure      = 0x40,        UI                          = 0x80,        MayLeakOnAbort              = 0x100,        All                         = 0x1ff,    }

Given that host protection has initially been designed with SQL Server 2005 in mind, the best way to understand the motivation behind the host protection categories is to think of them in the context of the SQL Server programming model. Two aspects of the SQL Server programming model drove the definition of these categories: reliability and scalability. Recall from Chapter 11 that the basis of the CLR's reliability design in .NET Framework 2.0 is the ability to shut down an application domain without leaking any resources, so one of the host protection categories (MayLeakOnAbort) is used to annotate code that cannot be guaranteed to free all resources when an application domain is unloaded. In addition, many of the host protection categories are aimed at preventing an add-in from inadvertently limiting the scalability of the host process. The SQL Server scheduler is highly tuned toward providing the highest degree of scalability possible. Any attempts by an add-in to block synchronizing access to shared state, or to affect how threads behave in the process, can limit the ability of SQL Server to scale. SQL Server add-ins such as user-defined types and stored procedures that are written in native code (using the T-SQL programming language) don't have the ability to perform operations that limit scalability in this way. Many of the host protection categories are designed to ensure that SQL Server add-ins written in managed code don't have those capabilities either.

The next several sections describe the individual host protection categories in detail. For each category, I describe the motivation for the category and the characteristics of the .NET Framework APIs that belong to that category. Each section also includes a full list of the .NET Framework APIs that belong to the particular category.

Synchronization

The synchronization host protection category includes APIs that allow an add-in to synchronize access to a particular resource explicitly across multiple threads. For example, many of the collection classes in the System.Collections namespace have a method called Synchronized that returns an instance of the collection to which only one thread can have access at a time. In addition, the System.Threading namespace includes several types that can be used to create and hold various types of operating system locks such as mutexes and semaphores. Synchronizing access to a resource means that at least one thread must wait if multiple threads are trying to access the resource simultaneously. Waiting on a resource limits scalability and should be avoided when possible in scenarios requiring high throughput. Hosts can block access to the APIs in the synchronization category to prevent an add-in from limiting scalability by waiting for access to a resource. In addition, synchronization can also hurt both scalability and reliability by causing the host to terminate an entire application domain instead of just an individual thread. Chapter 11 discusses how a host can specify policy that will cause the CLR to unload an entire application domain when a thread that is holding a lock receives a ThreadAbortException, for example.

The set of .NET Framework APIs that belongs to the synchronization host protection category is listed in Table 12-1.

Table 12-1. Properties and Methods with the Synchronization HostProtectionAttribute

Type	Property or Method
System.Collections.ArrayList	Synchronized
System.Collections.Generic.SortedDictionary<K, V>	SyncRoot { get }
System.Collections.Generic.Stack<T>	SyncRoot { get }
System.Collections.Hashtable	Synchronized
System.Collections.Queue	Synchronized
System.Collections.SortedList	Synchronized
System.Collections.Stack	Synchronized
System.IO.TextReader	Synchronized
System.IO.TextWriter	Synchronized
System.Threading.AutoResetEvent	All methods and properties
System.Threading.EventWaitHandle	All methods and properties
System.Threading.Interlocked	All methods and properties
System.Threading.ManualResetEvent	All methods and properties
System.Threading.Monitor	All methods and properties
System.Threading.Mutex	All methods and properties
System.Threading.ReaderWriterLock	All methods and properties
System.Threading.Semaphore	All methods and properties
System.Threading.Thread	Start Join SpinWait ApartmentState { set } TrySetApartmentState { set } SetApartmentState BeginCriticalRegion EndCriticalRegion
System.Threading.ThreadPool	All methods and properties
System.Threading.Timer	All methods and properties
System.ComponentModel.AttributeCollection	All methods and properties
System.ComponentModel.ComponentCollection	All methods and properties
System.ComponentModel.EventDescriptorCollection	All methods and properties
System.ComponentModel.ISynchronizeInvoke	BeginInvoke
System.ComponentModel.PropertyDescriptorCollection	All methods and properties
System.Diagnostics.TraceListener	All properties and methods
System.Data.TypedDataSetGenerator	All properties and methods
System.Xml.XmlDataDocument	All properties and methods
System.Diagnostics.Process	All properties and methods
System.Text.RegularExpressions.Group	Synchronized
System.Text.RegularExpressions.Match	Synchronized
System.Diagnostics.EventLog	SynchronizingObject
System.Diagnostics.PerformanceCounter	All properties and methods
System.Diagnostics.PerformanceCounterCategory	All properties and methods
System.Timers.Timer	All properties and methods

Shared State

The sharing of state between threads is related to synchronization in that access to the shared state must be synchronized for that state to remain consistent, so the shared state host protection category exists for many of the same reasons that the synchronization category does. The most obvious example of an API that allows you to share state between threads is the AllocDataSlot (and related) APIs on System.Threading.Thread. These APIs essentially provide a managed-code view of the thread local store feature of Win32.

The complete set of APIs in the shared state category is listed in Table 12-2.

Table 12-2. Properties and Methods with the SharedState HostProtectionAttribute

Type	Property or Method
System.Threading.Thread	AllocateDataSlot AllocateNamedDataSlot FreeNamedDataSlot GetData SetData
System.Diagnostics.Debug	Listeners { get }
System.Diagnostics.Trace	Listeners { get }
System.Data.TypedDataSetGenerator	All properties and methods
System.Diagnostics.Process	All properties and methods
System.Diagnostics.ProcessStartInfo	All properties and methods
System.Diagnostics.PerformanceCounter	All properties and methods
System.Diagnostics.PerformanceCounterCategory	All properties and methods

External Process Management

The external process management category contains APIs that add-ins can use to manipulate processes other than the host process itself. The APIs in this category can't affect the integrity or the reliability of the host process specifically, but they can have an indirect effect through the ability to create and manipulate other processes on the system. For example, SQL Server runs best when it is one of just a few processes on a system and it can therefore take advantage of the majority of the system's resources, including memory. The presence of many other processes competing for the same resources can adversely affect SQL Server performance. The Process class in the System.Diagnostics namespace is a great example of a class that can be used to affect other processes. Process has methods that allow an add-in to create and kill processes, interact with processes through the standard input and output streams, and so on.

Table 12-3 lists the types in the external process management category.

Table 12-3. Properties and Methods with the ExternalProcessMgmt HostProtectionAttribute

Type	Property or Method
System.ComponentModel.LicenseManager	All properties and methods
System.Diagnostics.Process	All properties and methods

Self-Affecting Process Management

Whereas the APIs in the external process management category cannot affect the host's process directly, the APIs in the self-affecting process management category can, so the APIs in this category can directly affect the stability of the host.

The APIs in the self-affecting process management category are all in the System.Diagnostics namespace and are all either on the Process class or its relatives. The self-affecting process APIs allow an add-in to affect characteristics of the host process, including its priority and the processor affinity of threads running in the process. The full list of self-affecting process APIs is given in Table 12-4.

Table 12-4. Properties and Methods with the SelfAffectingProcessMgmt HostProtectionAttribute

Type	Property or Method
System.Diagnostics.Process	All properties and methods
System.Diagnostics.ProcessStartInfo	All properties and methods
System.Diagnostics.ProcessThread	All properties and methods

Self-Affecting Threading

Whereas the APIs in the self-affecting process management category can directly affect various aspects of the host's process, the APIs in the self-affecting threading category can affect specific threads running within the host process. Examples of APIs in this category are those on System.Threading.Thread that allow a thread's priority to be altered, its COM apartment state to be set, and so on.

As I mentioned in the beginning of this chapter, the line between which APIs are blocked using CAS and which are blocked using host protection can often be blurry. For example, the System.Threading.Thread.Abort method can clearly be used to affect the threads in a process, so you'd expect Abort to be annotated with HostProtectionAttribute, identifying it as belonging to the self-affecting threading category. It is not, however. Instead, to be called, Abort demands a CAS permission (SecurityPermission.ControlThread). In this particular case, Abort was not annotated with HostProtectionAttribute because it already has a CAS demand. There are many cases in which a method or type that was protected using CAS wasn't annotated with HostProtectionAttribute even though it logically belonged to one of the host protection categories, so a host must use a combination of CAS, as described in Chapter 10, and host protection to ensure that no inappropriate APIs can be used in the process.

The list of APIs in the self-affecting threading category is given in Table 12-5.

Table 12-5. Properties and Methods with the SelfAffectingThreading HostProtectionAttribute

Type	Property or Method
System.Security.Principal.WindowsImpersonationContext	All properties and methods
System.Threading.Thread	Priority { set } IsBackground { set } ApartmentState { set } TrySetApartmentState { set } SetApartmentState

External Threading

The external threading category contains those APIs that can affect threads in the host process but cannot directly impact the host's stability. In most cases, the external threading APIs are those that allow an add-in to start an asynchronous operation such as reading from a network socket or a file.

Many of the types in the System.Threading namespace are also included in the external threading category, as shown in Table 12-6.

Table 12-6. Properties and Methods with the ExternalThreading HostProtectionAttribute

Type	Property or Method
System.ICancelableAsyncResult	Cancel
System.IO.FileStream	BeginRead BeginWrite
System.IO.Stream	BeginRead BeginWrite
System.Threading.AutoResetEvent	All methods and properties
System.Threading.CancellationRegion	SetNonCancelable SetCancelable
System.Threading.CancellationSignal	CancelSynchronousIO
System.Threading.EventWaitHandle	All methods and properties
System.Threading.Interlocked	All methods and properties
System.Threading.ManualResetEvent	All methods and properties
System.Threading.Monitor	All methods and properties
System.Threading.Mutex	All methods and properties
System.Threading.ReaderWriterLock	All methods and properties
System.Threading.Semaphore	All methods and properties
System.Threading.Thread	Start Join SpinWait AllocateDataSlot AllocateNamedDataSlot FreeNamedDataSlot GetData SetData CurrentUICulture { set } Name { set } BeginCriticalRegion EndCriticalRegion
System.Threading.ThreadPool	All methods and properties
System.Threading.Timer	All methods and properties
System.ComponentModel.ISynchronizeInvoke	BeginInvoke
System.Data.ProviderBase.DbConnectionInternal	BeginOpen
System.Data.SqlClient.SqlCommand	BeginExecuteNonQuery BeginExecuteXmlReader BeginExecuteReader
System.Data.SqlClient.SqlConnection	BeginOpen
System.Data.SqlClient.SqlDependency	All constructors
System.Net.Authenticator	BeginAuthenticate BeginAcceptAuthRequest
System.Net.Dns	BeginGetHostByName BeginResolveToAddresses BeginResolve
System.Net.FileWebRequest	BeginGetRequestStream BeginGetResponse
System.Net.FtpWebRequest	BeginGetRequestStream BeginGetResponse
System.Net.HttpListener	BeginGetContext
System.Net.HttpWebRequest	BeginGetRequestStream BeginGetResponse
System.Net.IPAddress	BeginResolveToAddresses
System.Net.Mail.SmtpClient	SendAsync
System.Net.NetworkInformation.Ping	SendAsync
System.Net.Security.NegotiateStream	BeginClientAuthenticate BeginServerAuthenticate BeginRead BeginWrite
System.Net.Security.SslStream	BeginClientAuthenticate BeginServerAuthenticate BeginRead BeginWrite
System.Net.Sockets.NetworkStream	BeginRead BeginWrite
System.Net.Sockets.Socket	BeginSendFile BeginConnect BeginDisconnect BeginSend BeginSendTo BeginReceive BeginReceiveFrom BeginAccept
System.Net.Sockets.TcpClient	BeginConnect
System.Net.Sockets.TcpListener	BeginAcceptSocket BeginAcceptTcpClient
System.Net.Sockets.UdpClient	BeginSend BeginReceive
System.Net.WebClient	OpenReadAsync OpenWriteAsync DownloadStringAsync DownloadDataAsync DownloadFileAsync UploadStringAsync UploadDataAsync UploadFileAsync UploadValuesAsync
System.Net.WebRequest	BeginGetResponse BeginGetRequestStream

Security Infrastructure

There are only two types in the security infrastructure host protection category, as shown in Table 12-7. These types allow an add-in to manipulate different aspects of the underlying Windows security system, including how impersonation is done and how security principals are managed.

Table 12-7. Properties and Methods with the SecurityInfrastructure HostProtectionAttribute

Type	Property or Method
System.Security.Principal. WindowsImpersonationContext	All properties and methods
System.Security.Principal.WindowsPrincipal	All properties and methods

User Interface

The number of types and methods in the user interface category is surprisingly small given the breadth of UI-related class libraries in the .NET Framework. There are two reasons for this. First, many of the types that allow the display of user interface are already protected by CAS permissions. In many cases, those types have not been annotated with HostProtectionAttribute as well. Also, recall that only the .NET Framework assemblies that SQL Server 2005 allows in its process have been annotated with the HostProtectionAttribute. This automatically eliminates System. Windows.Forms, one of the primary class libraries for building applications with user interfaces. As it stands in .NET Framework 2.0, only the user interfacerelated classes in the System.Console class are included in the user interface host protection category, as shown in Table 12-8.

Table 12-8. Properties and Methods with the UI HostProtectionAttribute

Type	Property or Method
System.Console	Error { get } In { get } Out { get } Beep ReadKey KeyAvailable { get } OpenStandardError OpenStandardInput OpenStandardOutput SetIn SetOut SetError Read ReadLine WriteLine Write

"May Leak on Abort"

As discussed in Chapter 11, the ability to unload an application domain without leaking any resources is a core concept in the CLR's design to provide a system that can execute predictably in scenarios requiring high availability. The "may leak on abort" host protection category is used to identify those types and methods that are not guaranteed to be leakproof when an application domain is unloaded. A type or method can leak resources if it doesn't adhere to the guidelines for writing reliable managed code that were outlined in Chapter 11. For example, if a type maintains a handle to an operating system resource without wrapping it using the SafeHandle class, the CLR cannot guarantee that the handle will not be leaked in all abort and shutdown scenarios. Hosts should be aware that they must block the "may leak on abort" host protection category if they require a highly available system.

The list of methods and types that can leak resources on abort or shutdown is given in Table 12-9.

Table 12-9. Properties and Methods with the MayLeakOnAbort HostProtectionAttribute

Type	Property or Method
System.Reflection.Assembly	Load(byte[] rawAssembly,...) LoadFile LoadModule
System.Reflection.Emit.AssemblyBuilder	All properties and methods
System.Reflection.Emit.ConstructorBuilder	All properties and methods
System.Reflection.Emit.CustomAttributeBuilder	All properties and methods
System.Reflection.Emit.EnumBuilder	All properties and methods
System.Reflection.Emit.EventBuilder	All properties and methods
System.Reflection.Emit.FieldBuilder	All properties and methods
System.Reflection.Emit.MethodBuilder	All properties and methods
System.Reflection.Emit.MethodRental	All properties and methods
System.Reflection.Emit.ModuleBuilder	All properties and methods
System.Reflection.Emit.PropertyBuilder	All properties and methods
System.Reflection.Emit.TypeBuilder	All properties and methods
System.Reflection.Emit.UnmanagedMarshal	All properties and methods