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




    Customizing the Microsoft  .NET Framework Common Language Runtime
    Customizing the Microsoft .NET Framework Common Language Runtime
    ISBN: 735619883
    EAN: N/A
    Year: 2005
    Pages: 119

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net