The permission classes provided by the framework should be adequate for most of the things you do. However, if you feel that you have a resource that must be protected and you think that there isn't a suitable class in the framework, then you can create your own permission class and extend CAS policy to use it.

There are two types of permissions: Code Access Security (CAS) permissions and non-CAS permissions. Both type of permission classes must implement IPermission so that permissions can be combined in permission sets and demands can be made. If you create your own permission class then you should make it sealed so that there is no possibility of a derived class overriding your security checks. Furthermore, permission classes should be serializable. If you want to provide declarative security then you must provide a security attribute based on your permission class. Note that if you want to have assembly security requests, link demands or inheritance demands then you must have an attribute class.

Non-CAS permissions are granted based on some general information not associated with a specific assembly and so when a demand is made the check is made on this general information and a stack walk is irrelevant. In general, you will implement a permission class and an attribute class so that you can perform declarative and imperative demands. The attribute class will create an instance of the permission class on which the runtime will invoke Demand.

The non-CAS permission object is created in an assembly through its code, this is done in two ways: by creating an instance of the permission class or by using the associated attribute. Your code calls Demand (or the runtime will call it for you on the permission object created for the attribute) and this method uses whatever information it has to determine if the demand succeeds. A non-CAS permission class must not be derived from CodeAccessPermission, because this class has the infrastructure for performing stack walks. IPermission is derived from ISecurityEncodable and so the permission class should implement the methods from this interface: ToXml and FromXml. These methods are used to write the permission to, and initialize a permission object from XML when you use declarative security.

Finally, a non-CAS permission should implement IUnrestrictedPermission and provide a constructor that takes a PermissionState parameter. This interface is used in the situation when there are unrestricted permissions, and contains a method called IsUnrestricted. The constructor with a PermissionState parameter naturally goes with IUnrestrictedPermission because IsUnrestricted indicates whether the permission is unrestricted.

Implementing an attribute permission class is similar for CAS and non-CAS permissions. In both cases you should derive from CodeAccessPermissionAttribute, the most important method of this is CreatePermission which will create an instance of a corresponding permission class. In addition, your class must have a single constructor that takes a SecurityAction parameter which should be passed to the base class constructor.

Start by creating a new library assembly (lib.cs):

This is a resource that will be protected by the custom permission. The code that uses it is simple (app.cs):

This creates a new ProtectedData object and accesses the Data object through the getter and the setter. You can compile this code and run it to convince yourself that it works.

In this example the permission class will restrict access to the object to certain times of the day. If the time is within the restricted time then the demand will succeed, otherwise a security exception will be thrown. Since all assemblies in the stack will measure the same time it makes no sense to perform a stack walk: if one assembly has this permission then all the other assemblies will have this permission too.

The permission object must hold the acceptable time span and it will also have a flag to indicate if the permission is unrestricted. These values will be set up by the constructors:

The permission assembly must be put into the GAC. The reason is that in v1.1 of the framework the attribute object is created at compile time to obtain information about the permission object, and so the attribute assembly and the permission assembly, must be accessible to the compiler. The only place that you can guarantee this is if the permission assembly is in the GAC. This means that the assembly must be strong named and since the permission assembly could be accessed by partially trusted assemblies the assembly must have [AllowPartiallyTrustedCallers].

The first constructor takes a PermissionState and if this indicates that the permission is unrestricted then anyone can have the permission at any time; if this is not unrestricted then no access is allowed. The second constructor allows you to set the times that the permission demand will succeed. To make the calculations simple, the times are expressed in 24-hour notation and we do not allow time periods that traverse midnight.

Your permission class needs to implement Union, Intersect and IsSubsetOf to support combining permissions. For this permission it gets a bit complicated because the intersection has to be the time common to both permissions, the union has to be the time covered by both, and the subset test must make sure that the time of the current permission is entirely within the time of the provided permission.

This must return a permission object that represents the intersection of both the current object and the one passed. The intersection is the data common to both, and in this case, it is the time where the two objects overlap. If the passed object is null then we cannot return a permission object, and if the wrong type of permission object is passed then there has been some mistake so an error is thrown. If one of the permission objects is unrestricted then the intersection of the two is the time covered by the other object. If they are both restricted then the time that is common to both is calculated by determining latest of the start times of the two and the earliest of end times of the two. If the two time spans do not intersect then a permission object with no access is returned.

Here the returned permission object has the contiguous time represented by both, if the two do not overlap then no access is given.

This object is a subset of the passed object only if the times overlap. If a null object is passed then you cannot create a subset and hence false is returned.

Permissions must be serializable because permission sets will be stored in the security configuration files. Thus the system will need to serialize an object to XML or initialise one from XML using these two methods:

The final task is to implement Demand to check to see if the current time is within the allowable time:

If the permission object is unrestricted then it is immaterial what time it is because access is always allowed; similarly, if no access is allowed there is no need to test the time. Finally, the time is obtained and tested to see if it is within the limits specified. The final code can be found here.

Compile this code and insert it into the GAC and add full trust:

Now go back to the ProtectedData class and make these changes:

The code demands an appropriate permission. Compile the code:

Now run the code. If you run this code between 10am and 5pm you'll find that it will work with no exceptions. If you run the code between 8am and 10am or between 5pm and 6pm you'll find that you'll get an exception when trying to write to the property. If you call this code before 8am or after 6pm then the exception will be thrown when you try to read the property. Of course, I know that you will be a manager and will be reading this at work, so this code will always work <g> therefore to test this code correctly you'll have to change the times in the permission objects.

Declarative demands are simple to implement for non-CAS permission. To do this add the following class to timeperm.cs.

The constructor must have a SecurityAction parameter, so any other data required by the permission object must be assigned using properties. Because of this the attribute must have some failsafe mechanism to make sure that valid data is used to create the ProtectedDataPermission object. In this case, the startTime and endTime fields are initialised with -1 to indicate that they do not have valid values. CreatePermission checks these values and if they are invalid then the ProtectedDataPermission object is created to prevent any access. Now edit lib.cs to use the attribute:

Compile the permission assembly and add it to the GAC, then compile the library and the process:

Now run the application to show that you have the same behaviour as before: the attributes specify when you can access the property.

Before doing anything else, use ILDASM to view the property get and set methods, for example here's the get method:

As you can see there is a metadata CAS demand for an empty permission set and a non-CAS demand for ProtectedDataPermission. This information is obtained at compile time by the compiler by creating an instance of ProtectedDataPermission, initializing it with the information in the attribute and then calling ToXml. At runtime this XML is extracted from metadata and an instance of the permission type (ProtectedDataPermission) is created and then initialized with the XML by passing it to FromXml.

Finally, clean up this example:

• remove full trust from timeperm (select the assembly in the Policy Assemblies node, right click and select Delete, or use caspol -rf timeperm.dll)
• remove the evidence assembly from the GAC (gacutil -u timeperm).

A CAS permission is granted based on the identity of the assembly, so a separate check must be made on each assembly by policy to determine if it can have the permission. There are two places where the permission object is created, the most obvious place is within your code: you create an instance to perform a demand (or one of the stack walk modifiers) or the runtime creates an instance when it sees the associated attribute. The other place where the CAS permission object is created is when the runtime creates a permission set for an assembly via policy based on the evidence of the assembly. When a demand is made and a stack walk is performed the granted permissions will be compared with the permission object created in (or for) your method. If the method's permission object is a subset of the equivalent permission object in the granted permission set then the permission demand succeeds. Clearly IPermission.IsSubsetOf is vital to the way that stack walks work.

The framework provides the CodeAccessPermission class and CodeAccessSecurityAttribute class with common code that you can use as base classes for your CAS permission. Extending CAS permissions requires deriving from these classes and overriding their members to handle your resource. Do not be tempted to implement Demand yourself because a demand for a CAS permission should initiate a stack walk. The framework classes do this by calling an internal class called CodeAccessSecurityEngine and since it is internal to mscorlib you will not have access to this class.

This example will develop a CAS permission to control access to a class that gives you information about the disks on your machine. Before showing the code I want to have a short rant about the support in v1.1 framework for disk information. The System.IO namespace should have a class to give information about the disks on your machine, but it doesn't (this is the case for 1.1, for 3.0/2.0, see the box below). The only information you can get about the drives on your machine is through Directory.GetLogicalDrives and Environment.GetLogicalDrives. These have the same code (a wrapper around the Win32 GetLogicalDrives function in kernel32.dll) with one important difference: the former demands a SecurityPermission for UnmanagedCode whereas the latter demands unrestricted EnvironmentPermission.

To get more information about a disk MSDN library recommends that you use the WMI classes in System.Management. This is typical of the woolly thinking from Microsoft about .NET. There are many unmanaged functions in kernel32.dll that you can use through platform invoke (for example, GetDiskFreeSpaceEx) and since kernel32.dll will be automatically loaded in your process as part of the .NET runtime, calling these methods comes with little performance cost. However, the WMI classes are a different case altogether. Firstly, WMI is a COM technology so that the System.Management classes will have to perform COM interop. COM interop is equivalent in performance terms to platform invoke, so this behaviour of the WMI classes is no worse than calling the Win32 disk functions yourself. The big problem with WMI is that the COM objects are implemented by a COM local server which means that they are implemented in another process and so to access them requires interprocess communication and COM marshalling between apartments. All this adds up to far worse performance than calling a DLL that is already in your process. Whoever decides to recommend using WMI when a Win32 function exists clearly isn't thinking straight.

Here's a class to get the amount of free space on a disk given its name (lib.cs):

GetDiskFreeSpaceEx will access the disk to determine how large it is and how much is free. The problem is that removable drives, like floppy drives or CD drives, may not have disks in them. If this occurs for then a dialog will be displayed requesting that you put a disk in the drive. The call to SetErrorMode with a value of 1 will prevent this dialog being shown and will set the last error value. Setting SetLastError to true in the [DllImport] attribute means that your code can call GetLastWin32Error to get this error value.

The library has been signed and has [AllowPartiallyTrustedCallers] so that a strong named, partially trusted assembly can call it.

So that you can test this later you'll need to call it from a partially trusted assembly, caller.cs, that just acts as an intermediary:

This has a strong name so that later on in this section you can download this assembly so that it gets partial trust. The code that uses this library is simple (app.cs):

Compile this code and confirm that it will return the sizes of the disks on your machine:

Clearly to call GetDiskFreeSpaceEx your code must have UnmanagedCode permission. However, this permission means that you will have access to every Win32 method. Just because your code has access to (for example) the method to access environment variables should your code also have access to information about your disks? Therefore, it makes sense to provide a separate permission for accessing information about disk information. Furthermore, if your assembly has this permission it will give access to information that you may not want other assemblies to have, so this permission should initialise a stack walk to make sure that all assemblies have this permission. Thus, this is an ideal candidate for a CAS permission.

Start by creating a library called diskperm.cs, as explained earlier, for v1.1 of the framework the permission assembly must be in the GAC, and it must allow access to partial trust callers.

The enumeration defines what the permission object allows: to get the size of the disk, get its name, or get the type of the disk. The DiskInfo object only gives information about the size of the disk, so the other values can be used for future expansion. The permission object must implement a constructor with PermissionState and it makes sense to have a constructor to initialise the object according to the access required:

Since DiskAccess is a bitmap (hence [Flags]) calculating the intersection and union are straightforward:

The methods to serialize and deserialize to XML are also straightforward:

The final method is to determine if the current object is a subset of the object passed as a parameter. Clearly, if the passed object has no access (None) then the test should fail. Conversely, if the passed object has All access then the test should succeed (again, except if the current object has None). If the two have the same value (except for None) then the test should succeed. Here's the code:

The next task is to add an attribute class, this is similar to the case with non-CAS permissions:

The final code can be found here. Compile the assembly and put it in the GAC:

Finally, you can use the attribute in the library to start a demand. Add a using statement for System.Security.Permissions and then add the following:

The attribute demands our custom permission, but notice the Assert. The Assert is there because the call through platform invoke will require the UnmanagedCode permission and normally this would start a stack walk. If this assembly is called by a partially trusted assembly (as we expect it to be) the demand for this permission will fail. The Assert will stop this stack walk and allow the call to be made to GetDiskFreeSpaceEx. Note that this is not opening a security hole because the demand for UnmanagedCode will be replaced with a demand for DiskPermission, and the Assert will only be applied for the scope of the method.

You can now compile this code to create the final application.

An assembly gets a CAS permission through policy and so you must add this permission to an appropriate policy. You'll want to add a permission based on the new permission, however, the configuration tool does not know about the permission class and so you cannot use the usual wizard interface. Instead, you have to do it through an XML file.

Create the following file (diskPerm.xml):

This XML identifies the permission with a fully qualified name, but since it will be used as part of the security policy the assembly (diskperm) must be fully trusted. To do this open the configuration tool, select the Policy Assemblies node and through the context menu select Add.... This will list all the assemblies in the GAC and so from this select the diskperm assembly. (You can also do this on the command line with caspol -af diskperm.dll)

Now you can add the new permission set. To do this select the Machine policy, then open the Permission Sets node and from the context menu select New. This will open a new dialog with two options, select the second one, Import a permission set from an XML file and then click on the Browse button. Select the XML file that you created, click on Open and then Finish. If you get a dialog saying The XML is invalid or does not contain a permission set then there is an error in the file. Here are some things to check:

• Check that the XML is well formed, that is, each element has a closing tag.
• Check that the assembly has a valid name, in particular, pay attention to the PublicKeyToken
• Check that the name of the assembly is not split over two lines
• Check that the assembly is in the GAC

You should find that a new permission set will be added to the policy:

Now you need to get this permission allocated to your assembly. Since caller has a strong name we can deploy it to the local web server and use a configuration file to download it from that server. Create a new code group for this library so that libraries with the same strong name as caller will get DiskSizePermission. To do this, open Code Groups for the policy, then select All_Code and from the context menu select New. Give this a name (DiskPermSize) then click on Next. On the next page select Strong Name for the condition, click on Import and browse for, and select caller.dll. Click on OK, then Next and from the permission set dropdown box select DiskSizePermission. Click on Next and then Finish.

You can now use the Evaluate Assembly (on the context menu of Runtime Security Policy) to check that the assembly will get the required permission set (at this point simply use the Browse button to locate the assembly on the hard disk). Since the DiskPermSize code group does not have the Exclusive property checked it means that assemblies that satisfy the strong name condition will get  DiskSizePermission and the other permission sets assigned by policy. This is intentional: we want to add a permission, not replace permissions.

Now we need to make the caller assembly partially trusted (the full details are outlined in the Fusion workshop). To do this move the assembly to a folder under the IIS root folder (move caller.dll \inetpub\wwwroot\bin). Now open the application under the Applications node in the configuration tool and select Configured Assemblies. From the context menu select Add, select the top option and click on Choose Assembly and select caller. Finally click on Select and then Finish and the property pages will be shown for the library. Select the Codebases tab and in the left hand column add the version 1.0.0.0 and next to that add the URI http://localhost/bin/caller.dll. Finally click on OK. This creates the following configuration file:

Now you have set up a code group so that the caller assembly will get the DiskSizePermission permission. You can test this out by running the application and confirming that it will work as expected. Are you convinced that the code has the permission? To show that the permission is being granted, edit the code group you just added and change the granted permission set to Nothing. To do this, select the DiskPermSize code group and from the context menu select Properties; click on the Permission Set table and from the Permission set dropdown box select Nothing. Select OK. Run the application again and this time you'll get the following:

Finally, clean up this example:

• remove the code group DiskPermSize and the permission set DiskSizePermission using the configuration tool (or on the command line: caspol -rg DiskPermSize and caspol -rp DiskSizePermission)
• remove full trust from diskperm (select the assembly in the Policy Assemblies node, right click and select Delete, or use caspol -rf diskperm.dll)
• remove the diskperm assembly from the GAC (gacutil -u diskperm).

Errata

If you see an error on this page, please contact me and I will fix the problem.

Page Eight