The purpose of FxCop is to analyze an assembly and produce output that pinpoints code features that violate the set of recommended best practices. To illustrate how it works, let's create an assembly from the code in Listing 15-1 and run it through FxCop. The program is a simple console application that accepts an input string, reverses it, and prints it. A simple menu permits the user to specify whether she wants to reverse a string or quit.

To test with FxCop, compile the program and pass the assembly to FxCop:

C:/> csc fxtest.cs
C:/> fxcopcmd  /file:fxtest.exe  /out:fxoutput.txt

Due to the length of the output, it's better to direct it to a file rather than display it.

//fxtest.cs
using System;
using System.Text;
namespace FxTesting
{
   public class TestApp 
   {
      static void Main()
      {
         string msg;
         string oper="";
         while(oper !="Q")
         {
            Console.WriteLine("(R)everse, (Q)uit");
            oper= Console.ReadLine();
            oper = oper.ToUpper();
            if(oper=="R"){
               Console.WriteLine("Enter phrase to reverse:");
               msg= Console.ReadLine();
               if(msg.Length>1) msg= Reverse(msg);
               Console.WriteLine(msg);
         }
      }
   }
   // Function to reverse a string
   public static String Reverse(String stringParameter)
   {
      if(stringParameter.Length==1)
      {
         return stringParameter;
      }
         else
         {
            return Reverse(stringParameter.Substring(1)) + 
                           stringParameter.Substring(0,1);
         }
      }
   }
}

The output is serialized as XML that contains Message tags, describing each occurrence where the code does not conform to the recommended practices. Here is an example of the raw code comprising one message:

<Message TypeName="AssembliesShouldHaveValidStrongNames" 
   Category="Microsoft.Design" CheckId="CA2210" Status="Active" 
   Created="2005-01-12 02:41:07Z" FixCategory="NonBreaking"> 
   <Issue Name="NoStrongName" Certainty="95"  
      Level="CriticalError">Sign 'fxtest' with a strong name key.
   </Issue>
</Message>

Let's look at the analysis FxCop produces for the fxtest assembly. For brevity, only the TypeName values from the XML are listed. Beneath each is a description of the code changes that will eliminate the message:

A review of the output shows that the assembly recommendations (1 through 5) are oriented toward components that will be stored in libraries and used by other code. As one would expect, the emphasis is on how component code interacts with other code. In general, security and type visibility is of more importance here than in general application development. Recommendations 6 and 7 promote more efficient code, whereas rule 8 is a subjective naming convention.

Many of the rules are overly restrictive for most programming environments, and you'll want to disable them. However, it is beneficial to be aware of them. They represent a set of best practices that have evolved with .NET. Even if you do not incorporate them in your code, understanding the reasoning behind them will deepen your knowledge of .NET.

The first step in creating a strong name is to create a pair of public and private encryption keys. During compilation, the private key is used to encrypt the hashed contents of the files contained in the assembly. The encrypted string that is produced is the digital signature that “signs” the assembly. It is stored in the manifest, along with the public key. Here are the steps to create and use a strongly named assembly:

Figure 15-3 summarizes the overall process. Note how decryption works. The decrypted signature yields a hash that should match the output when a new hash is performed on the assembly. If the two match, you can be sure that the private key associated with the public key was used for the original signing, and that the assembly has not been tampered with—changing even one bit will result in a different hash.

Figure 15-3. Using private and public keys to sign and verify a strong assembly

Core Note

A digital signature is not the same thing as a digital certificate. The digital signature in a strongly named assembly tells you nothing about who created the assembly, whereas a certificate contains the identity information that is used to authenticate the certificate publisher. Refer to documentation on Authenticode to learn how to obtain and use a certificate with an assembly.

It is imperative that the private key generated using Sn.exe (or some other process) not be compromised, because it is how an organization uniquely signs its software. If another party has access to the key, consumers cannot trust the ownership of the assembly.

One measure to secure the key is to limit its availability to developers, or withhold it altogether. During the development stage, developers are given only the public key. Use of the private key is delayed until it is necessary to sign the final software version. Delayed signing requires different steps than are used for creating a strongly named assembly:

Because an assembly references another strongly named assembly using its public key, there is no need to rebuild assemblies dependent on this one.

The Global Assembly Cache is a special directory set aside where strongly named assemblies can be stored and located by the CLR. As part of resolving references at load time, the CLR automatically looks in the GAC for the requested assembly. The obvious advantage of storing assemblies in the GAC is that they are located in a central, well known location where they can be located and shared by multiple applications. A less obvious advantage is that the strong name signatures for assemblies in the GAC are verified only when installed in the GAC. This improves the performance of applications referencing these assemblies, because no verification is required when loading the assembly.

Physically, the GAC is a Microsoft Windows directory located on the following path:

C:winntassembly

You can view its contents using a shell extension (ShFusion.dll) that is added to Windows Explorer as part of the .NET Framework installation. Each entry displays an assembly's name, type, version number, and public key token. By clicking an assembly entry, you can bring up a context menu that permits you to display the assembly's properties or delete it.

The easiest way to install a strongly named assembly into the GAC (or uninstall one) is to use GACUtil.exe, a command-line utility that ships with .NET SDK. Here is the syntax for performing selected operations:

There are a couple of drawbacks to storing an assembly in the GAC. First, it is difficult to reference during compilation due to the verbose GAC subdirectory naming conventions. An alternative is to compile referencing a local copy of the assembly. Then, remove the local assembly after compilation is completed.

Another possible drawback stems from the fact that an assembly cannot be copied into the GAC. If your application requires an assembly in the GAC, it eliminates deploying an application by simply copying files to a client's machine. Deployment issues are discussed in the last section of this chapter.

A major benefit of using strongly named assemblies is that the CLR uses the assembly's version information to bind assemblies that are dependent on each other. When such an assembly is loaded, the CLR checks the version number of referenced assemblies to ensure they have the same version numbers as recorded in the calling assembly's manifest. If the version fails to match (usually because a new version has been created), an exception is thrown.

[assembly: AssemblyVersion("1.0.0.0")]

<major version>.<minor version>.<build number>.<revision>

[assembly:AssemblyVersion("2.3.")]     yields 2.3.0.0
[assembly:AssemblyVersion("2.3.*")]    yields 2.3.1830,4000

[assembly: AssemblyKeyFile("Keylb.snk")]
[assembly: AssemblyVersion("1.0.*")]

Console.WriteLine(Assembly.GetExecutingAssembly().GetName());

fxtest, Version=1.0.1839.24546, Culture=neutral, 
   PublicKeyToken=1f081c4ba0eeb6db

A permission is the right to access a resource or perform some action. An assembly is assigned a permission when its evidence matches the evidence requirements for a permission set. Figure 15-5 illustrates how permissions come into play when an assembly attempts to access a resource. In this case, assembly A calls assembly B, which creates a FileStream object and attempts to use its Write method. The code in the .NET Framework Class Library that implements this method demands that the calling assembly have permission to perform file I/O. Moreover, it requires that all assemblies further up the call stack also have this permission. This check—known as walking the call stack—ensures that an assembly that does not have a required permission cannot use one that does to illegally perform an operation.

Figure 15-5. An assembly must have permission to perform file I/O

Because both Assembly B and Assembly A possess the FileIO permission, the write operation is permitted. An exception of type System.Security.SecurityException is thrown if either assembly does not have the requisite permission.

Permissions are often interrelated: for example, the permission to write to a file requires an accompanying permission to access the directory containing the file. To avoid having to grant and deny all permissions on an individual basis, .NET includes a PermissionSet class that allows a collection of permissions to be treated as a single entity for the purpose of denying or granting permissions.

As we shall see, permission sets can be created and applied programmatically by creating and adding individual permission objects to a PermissionSet collection. An alternate approach is to use the .NET Configuration tool to create permission sets and assign them to code groups. To encourage this approach, .NET includes predefined permission sets.

Named Permission Sets

.NET provides seven built-in or named permission sets. They range from the most restrictive Nothing, which prevents an assembly from loading, to the least restrictive Full-Trust, which permits unrestricted access to all of the permissions listed in Table 15-1. Here they are in ascending order of trust:

• Nothing. Prevents an assembly from being loaded. This is used primarily when the code is deemed untrustworthy because its origin cannot be determined.

• Execution. Permits code to load and run, but little else. It cannot access external resources. Such code is useful only for making calculations.

• Internet. Allows code to display and implement a user interface. By default, .NET grants this permission to all code coming from the Internet. Its permissions include the ability to open a file, perform safe printing, create safe top-level and subwindows, and connect to the originating site using HTTP or HTTPS.

• LocalIntranet. Specifies the default permissions for code originating in the local intranet. In addition to the permissions granted the Internet set, its permissions include unrestricted access to FileDialogs, default printing privileges, and unrestricted user interface access.

• Everything. Grants all permissions except permission to skip verification, because this is needed to verify the code is type-safe.

• FullTrust. Grants access to all built-in permissions. All code running on the local machine is given this by default.

Table 15-1. Built-in Permission Classes

Namespace	Class Name	Controls Permission To:
System.Security.Permissions	Environment	Access user and OS environment variables
	FileDialog	Access files or folders using a file dialog box.
	FileIO	Access files or folders.
	IsolatedStorage	Configure isolated storage and set quota on size of user's store.
	KeyContainer	Access key containers. A key container is an area within a key database that contains key pairs used for cryptography.
	Reflection	Access metadata using Reflection commands.
	Registry	Access system registry.
	Security	Access security permissions.
	Store	Stores containing X.509 certificates. X.509 is a standard for public key certificates. Most commonly used for securing transmission of data over Internet.
	UI	User interfaces and the clipboard.
System.Net	Dns	Domain name servers.
	Socket	Connect or accept connects at a specified socket. A socket is an address designated by a port # and IP address.
	Web	Connect to or from a Web host.
System.Drawing	Printing	Access printers.
System.Data.Common	DBData	Access data using a data provider.
System.Data.SqlClient	SqlClient	Use SQL Server data provider.
System	EventLog	Write to or browse a machine's event log.
System.ServiceProcess	ServiceController	Access to control or browse a machine's services.
System.Messaging	MessageQueue	Access the message queue.

Figure 15-6 lists the most interesting permission sets along with the individual permissions they contain. These sets cannot be modified; however, they can be copied and used as a base set for creating a custom permission set.

Figure 15-6. Permissions associated with selected named permission sets

[PermissionSet(SecurityAction.Demand,Name="LocalIntranet")]
public string GetTitle()  // Requires LocalIntranet
{}

.NET Built-in Security Permissions

The individual permissions shown in Figure 15-5 are implemented in .NET as built-in permission classes. In addition to being accessed by the security configuration tools, they can also be accessed by code to implement a finer-grained security than can be configured using administrative tools.

Table 15-1 summarizes the more important built-in permission classes.

All permission classes inherit and implement the interfaces shown in Figure 15-7. Of these, IPermission and IStackWalk are the most useful. IPermission defines a Demand method that triggers the stack walk mentioned earlier; IStackWalk contains methods that permit a program to modify how the stack walk is performed. This proves to be a handy way to ensure that a called component does not perform an action outside of those that are requested. We'll look at these interfaces in more detail in the discussion of programmatic security.

Figure 15-7. Interfaces inherited by permission classes

To qualify as a member of a code group and assume its privileges, an assembly must provide evidence that matches the evidence membership requirements of the code group. This evidence is based on either the assembly's origin or its signature. The origin identification includes Site, Url, and Zone evidence; the signature refers to an assembly's strong name, its digitally signed certificate (such as X.509), or a hash of the assembly's content. The Common Language Runtime provides seven predefined types of evidence. They are referred to by names used in the security administrative tools:

In addition to these, there is also a blank evidence known as All Code evidence that is used by an administrator to create a code group that matches all assemblies.

The CLR maintains evidence in an instance of the Evidence collection class. This object contains two evidence collections: one for the built-in host evidence and another for user-defined evidence. This evidence is made available to security policy, which then determines the permissions available to the assembly. You can use reflection to view evidence programmatically. In this example, we view the evidence for an assembly, movieclient.exe, which is located on the local machine (the assembly's source code is presented later in this section):

using System;
using System.Reflection;
using System.Security.Policy;
class ClassEvidence
{
   public static void Main()
   {
      Assembly ClientAssembly;
      // (1)Load object to reference movieclient assembly
      ClientAssembly = Assembly.Load("movieclient");
      // (2) Evidence is available through Evidence property
      Evidence ev = ClientAssembly.Evidence;
      // (3) Display each evidence object
      foreach (object ob in ev) 
      {
         Console.WriteLine(ob.ToString());
      }
   }
}

Output from the program reveals the Zone, Url, Strong Name, and Hash evidence associated with the assembly. No Site evidence is present because the assembly's Url origin is defined by a file:// rather than an http:// format. Application Directory evidence is also missing because it comes from the host application, not the assembly's metadata.

<System.Security.Policy.Zone version="1">
   <Zone>MyComputer</Zone>
</System.Security.Policy.Zone>

<System.Security.Policy.Url version="1">
   <Url>file://C:/movieclient.EXE</Url>
</System.Security.Policy.Url>

<StrongName version="1"
            Key="002400... 8D2"
            Name="movieclient"
            Version="0.0.0.0"/>

<System.Security.Policy.Hash version="1">
   <RawData>4D5A90000300000004000000FFFF0000B80
   </RawData>
</System.Security.Policy.Hash>

A .NET security policy defines how assembly evidence is evaluated to determine the permissions that are granted to the assembly. .NET recognizes four policy levels: Enterprise, Machine, User, and Application Domain. The policy-level names describe their recommended usage. Enterprise is intended to define security policy across all machines in the enterprise; Machine defines security for a single machine; User defines security policy for individual users; and Application Domain security is applied to code running in a specific AppDomain. Enterprise, Machine, and User policies are configured by an administrator. AppDomain policy, which is implemented only programmatically and used for special cases, is not discussed.

Despite their names, policies can be configured in any way an administrator chooses. The User policy could be set up to define enterprise security and the Machine policy to define user security. However, an administrator should take advantage of the names and use them to apply security to their intended target. As you will see in the discussion of the .NET Framework Configuration Tool (see “The .NET Framework Configuration Tool” on page 704), the security policy is granular enough to allow custom security policies on individual machines and users.

How .NET Applies Security Policies

Each security policy level is made up of one or more code sets. Each code set, in turn, contains a set of permissions that are mapped to a specific evidence type. Figure 15-8 illustrates how code sets and policy levels are combined to yield a permission set for an assembly.

Figure 15-8. A permission set is created from the intersection of policy level permissions

The .NET security manager is responsible for evaluating evidence and policy to determine the permissions granted. It begins at the enterprise level and determines the permissions in it that can be granted to the assembly. In this example, enterprise contains three code groups—two of which the assembly's evidence satisfies. The logical union of these permissions produces the permission set at this level. The other two policy levels are evaluated in the same way, yielding their associated permission set. The logical intersection of the three permission sets produces the permission set that is assigned to the assembly. In this case, the final set consists of permissions 2 and 5—the only permissions present on each level.

Physically, each policy level is stored as a configurable XML file that defines a hierarchy of code groups for the policy. The Enterprise policy file, enterprisec.config , and the Machine policy file, security.config^[3], are stored in the same folder on a Microsoft Windows system:

<Windows Directory>Microsoft.NETFramework<Version>config

The User policy file is named security.config and is located on the path

<Documents and Settings><User Name>Application DataMicrosoft
      CLR Security Config<Version>

Listing 15-2 contains an extract from the Machine policy file that illustrates the file layout. It comprises four major sections:

The code group section is structured as a multi-level hierarchy, with the conditions for granting permissions becoming more restrictive at each lower level.

<SecurityClasses>
   <SecurityClass Name="WebPermission"
         Description="System.Net.WebPermission, System, 
         Version=2.0.3600.0, Culture=neutral, 
         PublicKeyToken=b77a5c561934e089"/>
   <SecurityClass Name="EventLogPermission" 
         Description="System.Diagnostics.EventLogPermission, 
         System, Version=2.0.3600.0, Culture=neutral, 
         PublicKeyToken=b77a5c561934e089"/>
   ...
</SecurityClasses>
<NamedPermissionSets>
   <PermissionSet class="NamedPermissionSet" 
         version="1"
         Name="LocalIntranet"
         Description="Default rights given to applications on 
         the local intranet">
      <IPermission class="EnvironmentPermission"
         version="1" Read="USERNAME"/>
      <IPermission class="FileDialogPermission"
         version="1" Unrestricted="true"/>
   ...
</PermissionSet>
...
</NamedPermissionSets>
<CodeGroup class="UnionCodeGroup"
         version="1"
         PermissionSetName="Nothing"
         Name="All_Code"
         Description="Code group grants no ...">
       <IMembershipCondition class="AllMembershipCondition"
         version="1"/>
   <CodeGroup class="UnionCodeGroup"
         version="1"
         PermissionSetName="FullTrust"
         Name="My_Computer_Zone"
         Description="Code group grants ...">
         ...
   </CodeGroup>
   ... additional code groups here
</CodeGroup>
<FullTrustAssemblies>
   <IMembershipCondition class="StrongNameMembershipCondition"
         version="1"
         PublicKeyBlob="00000000000000000400000000000000"
         Name="mscorlib.resources"
         AssemblyVersion="Version=2.0.3600.0"/>
   <IMembershipCondition class="StrongNameMembershipCondition"
         version="1"  
         PublicKeyBlob="00000000000000000400000000000000"
         Name="System"
         AssemblyVersion="Version=2.0.3600.0"/>
   ...
</FullTrustAssemblies>

.NET provides two ways to work with these policy files: a command-line Code Access Security Policy (caspol) and a graphical Configuration tool (MSCorCfg.msc). Both can be used to modify the default configuration, create custom code groups, create custom permission sets, and export policies to be deployed with an application. We'll look at both tools in this section, with an emphasis on the Configuration tool because its visual interface makes it more popular and easier to learn than the command-line approach.

On a Microsoft Windows system, you start the Configuration tool by selecting Microsoft .NET Framework Configuration from the Administrative Tools folder or by selecting Run and typing MSCORCFG.MSC. The program interface consists of a window divided into two panes. As shown in Figure 15-9, the left side contains a tree structure comprising multiple folders. Of these, the Runtime Security Policy folder expands to display a hierarchy of security information.

Figure 15-9. Interface for the .NET Framework Configuration tool

At the top level of the hierarchy are the three folders representing the Enterprise, Machine, and User policies. Beneath each of these are folders that contain code groups, permission sets, and policy assemblies. This hierarchy is, of course, simply a visual representation of the underlying XML policy files. You can observe this by comparing the raw XML tags in Listing 15-2 with the items displayed under the Machine policy.

The Default Configuration Policies

The Enterprise and User policies contain a single default code group named All_Code. If you click it, you'll see this description in the right panel:

“Code group grants all code full trust and forms the root of the code group tree.”

Specifically, this code group binds All Code evidence with the FullTrust permission set. Recall that all assemblies qualify as members of code groups that use All Code evidence and that the FullTrust permission set offers unrestricted permissions. The net effect of binding these two is to create Enterprise and User policies that offer unlimited permissions to all assemblies. In other words, these two policies offer no security at all by default.

Core Note

The code groups provided by .NET are named after the evidence they represent. Because no two code groups may have the same name, custom code groups must use a modified naming convention.

The Machine security policy is far more interesting and instructive. At its root is the All_Code code group. Unlike the other two policies, it binds All Code evidence to the Nothing permission set, which means the code group grants no permissions. To find the permissions, you must look to the code groups nested beneath this root. The first level contains six groups: My_Computer_Zone, LocalIntranet_ Zone, Internet_Zone, Restricted_Zone, Trusted_Zone, and Application_ Security_Manager. All except Restricted_Zone have one or more child code groups. Let's look at how default permissions are granted for two of these: My_Computer_Zone and LocalIntranet_Zone. To view details about the other code groups, simply right-click their name to bring up a properties window.

My_Computer_Zone Code Group

This code group grants the FullTrust permission set to assemblies that satisfy the My Computer zone evidence. Its two child code groups grant FullTrust to assemblies that have Strong Name evidence containing either the Microsoft public key or the ECMA public key, also known as the Standard Public Key.^[4] It is important to understand that an assembly can satisfy the Strong Name evidence without satisfying the My Computer zone evidence. This is because .NET evaluates child code groups even if the conditions for the parent group are not satisfied. Conversely, a code group's properties can be set to instruct .NET not to evaluate child groups if the conditions of the parent code group are satisfied.

LocalIntranet_Zone Code Group

This code group grants the LocalIntranet permission set to assemblies that satisfy the Local Intranet zone evidence—any computers on the same local area network as the machine on which the host code runs. This code group has two child code groups: Intranet_Same_Site_Access and Intranet_Same_Directory_Access. The former permits code to access the site of its origin; the latter permits code to access its original install directory. The practical effect of these permissions is to permit code to perform I/O on its local storage.

To illustrate how to use the Configuration tool, we'll create a new permission set and assign it the Reflection and Execution permissions. Next, we'll create a code group that maps the new permission set to Url evidence that specifies a directory on the local machine. The effect is to grant the Reflection permission to any assembly that runs from this directory.

For testing, we'll create a simple application that uses reflection to access a private field in this assembly's class:

// (movieclass.dll) Will use reflection to access this class
using System;
public class Movies
{
   private int ID;
   private string Director;
   public string title;
   public string year;
}

Listing 15-3 contains the code that accesses the private Director field. This is done by calling the Type.GetField method and passing as arguments the field name and flags that request access to a private field in a class instance.

// configtest.cs
using System;
using System.Reflection;
class ClassEvidence
{
   public static void Main()
   {
      Assembly ClientAssembly;
      ClientAssembly = Assembly.Load("movieclass");
      // Get the desired Type in the Assembly
      Type myType = ClientAssembly.GetType("Movies");
      // Get the FieldInfo for private field "Director".
      // Specify nonpublic field and instance class.
      // Accessing private members requires Reflection 
      // Permission.
      FieldInfo myFieldInfo = myType.GetField("Director", 
            BindingFlags.NonPublic | BindingFlags.Instance);
      if (myFieldInfo !=null) 
         Console.WriteLine("Field: {0} Type: {1}", 
                           myFieldInfo.Name, 
                           myFieldInfo.FieldType);
      {
         // output: Field: Director  Type: System.String
      } else {
         Console.WriteLine("Could not access field.");
      }
   }
}

C:>caspol –rsp c:casconfigtest.exe

C:>caspol –rsg c:casconfigtest.exe

Level = Enterprise
Code Groups:
1.  All code: FullTrust

Level = Machine
Code Groups:
1.  All code: Nothing
   1.1.  Zone - MyComputer: FullTrust
   1.6.  Url - file://C:/cas/*: Reflection (Exclusive)

Level = User
Code Groups:
1.  All code: FullTrust

C:>caspol –m -lp

C:>permcalc c:casconfigtest.exe

Including permission attributes in code is referred to as declarative security, and it serves two primary purposes: When applied at the assembly level, the attribute serves to inform the runtime which permissions the assembly requires—or does not require—to function; when applied at the class or method levels, it protects resources by demanding that callers possess specific permissions to access a resource through the current assembly. Attributes used for this latter purpose trigger or modify a stack walk that verifies all assemblies in the call chain can access the called assembly. We'll examine this in “Programmatic Security” on page 715. For now, the focus is on how to use assembly-level attributes to adjust security within a program.

Although the term request is broadly used to describe the use of permission attributes, it's better described as a way for an assembly to publish (in metadata) its permission requirements. The effectiveness of including permission attributes in code is governed by three rules:

Despite the fact that you do not have to include permission requests in your code, there are important reasons for doing so:

For a full trust environment where code has unrestricted permissions—typically in-house applications—security is not a significant factor, and it may not be necessary to apply security attributes. However, if you operate in a security-conscious environment or are creating components for use by other software, you should include security attributes as a means of providing self-documenting security.

[assembly : PermissionAttribute(
               SecurityAction.membername, 
               PermissionAttribute property)
] 

//place on line preceding: class ClassEvidence 
 [assembly : ReflectionPermission(
              SecurityAction.RequestMinimum, 
              Flags=ReflectionPermissionFlag.TypeInformation)
]

SecurityAction.RequestMinimum

Flags = ReflectionPermission-
Flag.TypeInformation

SecurityAction.RequestMinimum

Flags = ReflectionPermission-
Flag.ReflectionEmit

SecurityActionRequestOptional

Flags = ReflectionPermission-
Flag.ReflectionEmit

The .NET Configuration tool provides a broad stroke approach to defining security for a computing environment. In most cases, this is satisfactory. If two assemblies come from the same security zone, it usually makes sense to grant them the same permissions. However, suppose you are developing components for clients with an unknown security policy, or you are using third-party components whose trustworthiness is unknown. In both cases, programmatic security offers a way to enforce security specifically for these components.

Programmatic security is implemented by using .NET permission classes to control and enforce security on a calling assembly or a called assembly. This is an important point: The calling assembly can override permissions granted by the CAS and prevent the assembly from accessing a resource; conversely, a called assembly can refuse to perform an operation unless the calling assembly—or assemblies—has permissions it requires. The key to implementing programmatic security is a mechanism known as a stack walk.

Stack Walk

As mentioned earlier in the chapter, a stack walk refers to steps the CLR follows to verify that all methods in a call stack have permission to perform an operation or access a system resource. This ensures that an immediate client with the proper permissions is not called by malicious code further up the stack that does not have permission.

As shown in Figure 15-10, a stack walk is triggered when code invokes a permission's Demand method. This method is inherited from the IPermission interface (refer to Figure 15-7), which includes other methods such as Intersect and Union that allow permission objects to be logically combined.

Figure 15-10. Invoking the Permission.Demand method triggers a stack walk

The Demand method is used extensively throughout the .NET Framework to ensure that applications requesting operations such as file I/O or database access have the proper permissions. Although most calls to the Framework Class Library (FCL) are protected in this way, it can still be useful to demand a stack walk within your code. You may want to apply even stricter permission requirements than the FCL demands, or you may want to ensure that a lengthy operation has all the required permissions before it is launched.

To provide a simple illustration, let's create a component that returns information about a requested movie from our Films database (see Chapter 11). Listings 15-4 and 15-5 contain the component and client code, respectively. For brevity, the ADO.NET code is excluded, but is available as downloadable code.

Because the SqlClient permission is required to access a SQL Server database, the component includes the following code to ensure that the calling assembly has this permission:

SqlClientPermission sqlPerm= 
      new SqlClientPermission(PermissionState.Unrestricted);
sqlPerm.Demand();  // Trigger stack walk

The code simply creates an instance of the desired permission class and calls its Demand method. There is no limit on the number of permission objects that can be created and used to demand a stack walk. However, it is an expensive process and should be used judiciously.

Example 15-4. Component to Illustrate Code Access Security

// filmcomponent.cs  (.dll)
using System.Data.SqlClient;
using System;
namespace moviecomponents
{
   public class MovieData
   {
      // Return MovieProfile object
      public static MovieProfile GetMovie(string movietitle)
      {
         // Return null if movie not found
         MovieProfile mp = null; 
         // Demand SqlClient permission from methods on call stack
         SqlClientPermission sqlPerm= new 
               SqlClientPermission(PermissionState.Unrestricted);
         sqlPerm.Demand();
         //*** Code here to query database for movie information
         //*** Requires SqlClient permission
         return mp;
      }
   }
   public  class MovieProfile
   {
      private string pTitle;
      private int pYear;
      private int pRank;
      private string pOscar;
      public MovieProfile(string title, int year, 
                          int afiRank, string bestFilm)
      {
         pTitle= title;
         pYear = year;
         pRank = afiRank;
         pOscar = bestFilm;
      }
      // Readonly properties
      public string Title
      {
         get{return pTitle;}
      }
      public int Year
      {
         get{return pYear;}
      }
      public int Ranking
      {
         get{return pRank;}
      }
      public string BestPicture
      {
         get{return pOscar;}
      }
   }     // class
}       // namespace

Example 15-5. Assembly to Access Film Component

// movieclient.cs  (.exe)
using System;
using moviecomponents;
namespace MovieClient
{
   class MovieMgr
   {
      static void Main(string[] args)
      {
         string myMovie;
         if(args.Length>0) 
         {
            myMovie= args[0];
            // Call component to fetch movie data
            MovieProfile mp = MovieData.GetMovie(myMovie);
            if(mp==null)
            {
               Console.WriteLine("Movie not found");
            }
            else
            {
               Console.WriteLine("Year:{0} AFI Rank: {1}",
                                 mp.Year, mp.Ranking);
            }
         }
      }
   }    // class
 }     // namespace

This code can be tested from the command line. Compile both the component and client. Then, run the client by passing it the movie name as a parameter:

C:>csc /t:library filmcomponent.cs
C:>csc /r:filmcomponent.dll movieclient.cs
C:>movieclient casablanca
Year: 1942  AFI Rank:2

Because code running on a local machine has unrestricted permissions (by default), the stack walk verifies that movieclient has the necessary permission. To make the example more interesting, let's run the client when it does not have the SqlClient permission. The easiest way to remove this permission is by adding an assembly-level permission attribute that explicitly refuses the permission. You do this by passing the SecurityAction.RequestRefuse enumeration to the constructor of the permission attribute you do not want granted to the assembly. To refuse the SqlClient permission, place this statement before the namespace statement in the client code:

[assembly : SqlClientPermission(SecurityAction.RequestRefuse)]

Building and running the modified SqlClient results in a security exception being thrown.

Stack Walk Modifiers

Just as a called assembly has the rights to initiate a stack walk, the objects on the call stack have the right to modify the behavior of the stack walk. For example, they can cause the walk to fail, or stop the walk at the current object so that it does not check objects further up the stack. These capabilities have significant security implications: inducing a stack walk failure is a way for a client to restrict what actions a called assembly may perform; and terminating a stack early can improve performance by eliminating unnecessary steps in a repeated stack walk.

The ability to modify a stack walk is provided by methods in the IStackWalk interface (refer to Figure 15-7) that all permissions must implement. This interface defines the Demand method that initiates a stack walk, and three other methods, Assert, Deny, and PermitOnly, that modify a stack walk's normal operation. Assert stops the stack walk at the current stack frame; Deny causes the walk to fail; and PermitOnly specifies the only permission that an object will allow a stack walk to verify.

To demonstrate these methods, let's modify the code in Listing 15-5 to implement each method. First, we add namespaces so that we can access IStackWalk and the permission:

using System.Security;
using System.Data.SqlClient;
using System.Security.Permissions;

Then, the code is changed to create an IStackWalk object that is set to the permission being checked by the stack walk—in this case, SqlClientPermission:

myMovie= args[0];
//
IStackWalk stackWalker;
stackWalker = new 
      SqlClientPermission(PermissionState.Unrestricted);
stackWalker.Deny();      // Deny use of SqlClient by GetMovie
// Call component to fetch movie data
try{ 
   MovieProfile mp = MovieData.GetMovie(myMovie);

In our first example, we call the permission's Deny() method that causes the stack walk's verification of the SqlClient permission to fail. Filmcomponent cannot access the database and throws an exception.

Now, replace the call to Deny with a call to Assert. Assert prevents the stack walk from continuing further up the code stack—unnecessary in this case because there is no other object on the stack. The stack walk succeeds because movieclient has the required permission, and database access is permitted.

Core Note

On the surface, the use of Assert seems to undermine the reason for a stack walk—to ensure that all objects on the call stack have a required permission. To make sure the method is not used to hide potentially malicious code on the call chain, .NET requires that the asserting code have a special security permission before it can assert; then, as added protection, it triggers a stack walk when code makes an assertion that verifies that all code above it has the asserted permission.

The final way to modify the stack walk is by using the PermitOnly method to indicate specific permissions that the code is willing to let the called assembly use. In the current example, the calling assembly has unrestricted permissions; the component filmcomponent has need for only the SqlClient permission. By using PermitOnly to specify this permission, movieclient thwarts any stack walks that attempt to verify other permissions.

An assembly may be required to call multiple components, each with its own permission requirements. You may need to permit SQL access for one and file I/O for another. If you call PermitOnly a second time to override the first call, an exception is thrown. Instead, you must clear the effects of the first call by calling CodeAccessPermission's static RevertPeritOnly method; then, you call PermitOnly with a new permission. The following segment could be added to our code to remove SqlClient as the only allowed permission, and replace it with the Reflection permission.

// Remove effects of previous PermitOnly call
CodeAccessPermission.RevertPermitOnly();
stackWalker = new ReflectionPermission(
      ReflectionPermissionFlag.TypeInformation);
// Allow stack walk to verify Reflection permission only
stackWalker.PermitOnly();
// Now call a method that requires Reflection

// Imperative Security
SqlClientPermission sqlPerm= new 
      SqlClientPermission(PermissionState.Unrestricted);
sqlPerm.Demand();  

// Declarative Security 
[SqlClientPermission(SecurityAction.Demand)]
public static MovieProfile GetMovie(string movietitle){

Almost always included in the list of the top .NET features is the promise of using XCOPY deployment to install your application on client machines. The idea is to create a simple script that uses the XCOPY utility to copy your assemblies and resource files to the specified directories on the client's machine. It is a terrific idea and works—if you have an application with only a few assembly files that can be stored in a local directory. However, there are a lot of installation scenarios where XCOPY does not work: It cannot be used to register a COM component in your application, and it cannot be used to store an assembly in the GAC. In addition, for a professional application, XCOPY does not provide the well-designed interface that customers expect.

The most popular alternative to XCOPY is the Microsoft Windows Installer that ships with most of its operating systems and is also available as a separate download. The installer is an installation service that processes files having a special format (.msi) and performs install operations based on their content. An .msi file is referred to as a Windows Installer Package, and an install can contain more than one of these files.

The easiest way to create an MSI file for your application is using Visual Studio .NET. It has a wizard that steps you through the process. If your application requires special Code Access Security policies, use the Configuration tool to create an install package. To do so, right-click the Runtime Security Policy node and select Create a Deployment Package. The ensuing wizard steps you through the process. You can also create a custom installer by creating a class that inherits from the System.Configuration.Install.Installer class and overrides its Install and Uninstall methods.

Core Note

.NET 2.0 and Visual Studio 2005 introduce a ClickOnce technology that is designed to simplify the installation and update of Windows applications. The idea is to create the application and use VS.NET to “publish” it to a File or Web Server. The location is provided as a URL to users who link to a Web page that provides install instructions. Included with the application is a manifest that describes the assembly and files that comprise the application. This information is used to determine whether an update is available for the application. The update process can be set up to automatically check for updates each time the application is run, or only run when requested.

ClickOnce works for straightforward installations that do not need to access the registry or install assemblies in the GAC. It is also targeted for the Microsoft Windows environment, as it contains shortcuts and an uninstall feature used by Windows. Although VS.NET is the easiest way to publish an application for installation, it can be done manually.

.NET supports two assembly deployment models: private and shared. A private assembly is identified by its file name—without the extension—and is stored locally with other assemblies that it references or that reference it. Shared assemblies are stored in the Global Assembly Cache. Although this is a convenient way to make an assembly available to multiple applications, it does present an installation problem. Recall from the earlier discussion that an assembly cannot be copied into the GAC; instead, a special tool is required to install or “register” it. During code development, the GACUtil.exe utility is used for this purpose. However, this tool is not included with the end-user version of the .NET Framework redistributable package, so there is no assurance that it will exist on the user's machine. Instead, use the Windows Installer.

The easiest way to deploy an application with multiple private assemblies is to place all of the assemblies in the same directory. This home directory, referred to as the application's base directory, is the first place the CLR looks when trying to locate an assembly. However, using a single directory prevents assemblies from being grouped into folders that logically describe their purpose. For example, an application may have a set of assemblies dedicated to graphics and another dedicated to database access. Placing these in Graphics and Data subfolders represents a more logical and easier-to-maintain code deployment.

To see how to set up a meaningful directory structure for an application, let's first look at how the CLR locates private assemblies. This discovery process, called probing, begins with the application's base directory. If the assembly is not located there, it searches for an immediate subdirectory having the same name as the target assembly. For example, if the assembly is myClass, it looks first for the directory myClass.dll and then myClass.exe. The CLR loads the assembly from the first directory in which it locates it.

In our case, we want to use a directory structure that is not based on the name of the assemblies. To force the CLR to extend its probe into other folders, we must add a special <probing> element to the application's configuration file. For an application named myApp.exe, we create a configuration file named myApp.exe.config and store it in the application's base directory. Included in the file is a <probing> tag with a privatePath attribute that specifies the subdirectories (below the base directory) for the CLR to search.

<configuration>
   <runtime>
      <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
         <probing privatePath="graphics;data" />
      </assemblyBinding>
   </runtime>
</configuration>

By default, the specified search paths are relative to the application's base directory. You can also specify an absolute path, but the path must specify a folder below the application's base directory.

The application configuration file in this example is rather simple, and you may choose to build it manually. However, because the file often contains other configuration elements, manual manipulation can quickly become an unwieldy task. As an alternative, you can use the same Configuration tool described in the CAS discussion. It has an Applications folder that can be opened and will lead you through the steps to create a configuration file for a selected assembly. One of its more useful and instructive features is an option to view a list of other assemblies that the selected assembly depends on.

A <codebase> element provides another way to specify the location of an assembly. It differs from the <probing> element in that it can specify any directory on the machine, as well as a location on a file or Web server across a network. The CLR uses the URI information provided by this element to download an assembly the first time it is requested by an application. Notice how <codebase> is used in the following sample configuration file.

The <codebase> element, along with a companion <assemblyIdentity> element, is placed inside the <dependentAssembly> block. The <assemblyIdentity> element provides information about the assembly the CLR is attempting to locate: its simple name, public key token, and culture. The <codebase> element provides the assembly's version number and location where it can be found. If the assembly is not strongly named, the version information is ignored.

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
     <dependentAssembly>
        <assemblyIdentity name="movieclass"
           publicKeyToken="1F081C4BA0EEB6DB"
               culture="neutral" />
        <codeBase version="1.0.0.0"  
                   href="http://localhost/scp/movieclass.dll" />
     </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

The href can also refer to the local file system:

<codeBase version="1.0.0.0" 
                  href="file:///e:movieclass.dll"  />

One of the advantages of using a strongly named assembly is the version binding feature it offers. When Assembly A is compiled against Assembly B, A is bound to the specific version of B used during the compilation. If Assembly B is replaced with a new version, the CLR recognizes this at load time and throws an exception. It is a good security feature, but can make updates to B more time-consuming because all assemblies dependent on it must be recompiled.

A configuration file can be used to override version binding by instructing the runtime to load a different version of the assembly than was originally bound to the calling assembly. This redirection is achieved by adding a <bindingRedirect> element that specifies the original version and the new version to be used in place of it. Here is how the previous configuration file is altered to have a newer version of the movieclass assembly loaded:

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly> 
        <assemblyIdentity name="movieclass"
           publicKeyToken="1F081C4BA0EEB6DB"
               culture="neutral" />
        <bindingRedirect oldVersion="1.0.0.0" 
                         newVersion="2.0.0.0"/>

        <codeBase version="2.0.0.0"  
                   href="http://localhost/scp/movieclass.dll" />

      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Use of the <bindingRedirect> element inside an application configuration file offers a flexible and practical approach to matching applications with new or older versions of a component. For example, both versions of the component can run side by side on the same machine. One application can continue to use the older version, whereas the configuration file of a second application is modified to direct it to the newer component. Moreover, if the second application encounters problems with the new component, the <bindingRedirect> element can be removed and the application will revert to using the original component.

As a final note on deployment, it is good practice to include assembly-level attributes to your assembly to provide useful information to clients that want to examine the properties of your .exe or .dll file. As an example, the attributes in the following code yield the properties shown in Figure 15-11:

using System;
using System.Reflection;
[assembly:AssemblyVersion("2.0.0.0")] 
[assembly:AssemblyCompany("Acme Software")]
[assembly:AssemblyCopyright("Copyright (c) 2005 Stephen Perry")]
[assembly:AssemblyTrademark("")]
// Set the version ProductName & ProductVersion fields
[assembly:AssemblyProduct("Core C# Examples")]
[assembly:AssemblyInformationalVersion("2.0.0.0")]
[assembly:AssemblyTitle("Core C# movieclass.dll")]
[assembly:AssemblyDescription("This is a sample C# class")]
//
public class Movies
{
// ... Remainder of code

Figure 15-11. Attributes provide information identifying an assembly