Contents
Over the past years, I've learned many things from CodeProject ... and now I'm giving back to the CodeProject. Since I didn't find any articles on Code Access Security, here's my one. Enjoy!
I'm not going to bore you with theory, but before we wet our feet, there are some concepts, keywords that you should learn. .NET has two kinds of security:
- Role Based Security (not being discussed in this article)
- Code Access Security
The Common Language Runtime (CLR) allows code to perform only those operations that the code has permission to perform. So CAS is the CLR's security system that enforces security policies by preventing unauthorized access to protected resources and operations. Using the Code Access Security, you can do the following:
- Restrict what your code can do
- Restrict which code can call your code
- Identify code
We'll be discussing about these things through out this article. Before that, you should get familiar with the jargon.
Code access security consists of the following elements:
- permissions
- permission sets
- code groups
- evidence
- policy
Permissions
Permissions represent access to a protected resource or the ability to perform a protected operation. The .NET Framework provides several permission classes, like FileIOPermission (when working with files), UIPermission (permission to use a user interface), SecurityPermission (this is needed to execute the code and can be even used to bypass security) etc. I won't list all the permission classes here, they are listed below.
Permission sets
A permission set is a collection of permissions. You can put FileIOPermission and UIPermission into your own permission set and call it "My_PermissionSet". A permission set can include any number of permissions. FullTrust, LocalIntranet, Internet, Execution and Nothing are some of the built in permission sets in .NET Framework. FullTrust has all the permissions in the world, while Nothing has no permissions at all, not even the right to execute.
Code groups
Code group is a logical grouping of code that has a specified condition for membership. Code from http://www.somewebsite.com/ can belong to one code group, code containing a specific strong name can belong to another code group and code from a specific assembly can belong to another code group. There are built-in code groups like My_Computer_Zone, LocalIntranet_Zone, Internet_Zone etc. Like permission sets, we can create code groups to meet our requirements based on the evidence provided by .NET Framework. Site, Strong Name, Zone, URL are some of the types of evidence.
Security policy is the configurable set of rules that the CLR follows when determining the permissions to grant to code. There are four policy levels - Enterprise, Machine, User and Application Domain, each operating independently from each other. Each level has its own code groups and permission sets. They have the hierarchy given below.
Figure 1
Okay, enough with the theory, it's time to put the theory into practice.
Let's create a new Windows application. Add two buttons to the existing form. We are going to work with the file system, so add the System.IO namespace.
using System.IO;
Figure 2
Write the following code:
private void btnWrite_click(object sender, System.EventArgs e)
{
StreamWriter myFile = new StreamWriter("c:\\Security.txt");
myFile.WriteLine("Trust No One");
myFile.Close();
}
private void btnRead_click(object sender, System.EventArgs e)
{
StreamReader myFile = new StreamReader("c:\\Security.txt");
MessageBox.Show(myFile.ReadLine())
myFile.Close()
}
The version number should be intact all the time, for our example to work. Make sure that you set the version number to a fixed value, otherwise it will get incremented every time you compile the code. We're going to sign this assembly with a strong name which is used as evidence to identify our code. That's why you need to set the version number to a fixed value.
[assembly: AssemblyVersion("1.0.0.0")]
That's it ... nothing fancy. This will write to a file named Security.txt in C: drive. Now run the code, it should create a file and write the line, everything should be fine ... unless of course you don't have a C: drive. Now what we are going to do is put our assembly into a code group and set some permissions. Don't delete the Security.txt file yet, we are going to need it later. Here we go.
.NET Configuration Tool
We can do this in two ways, from the .NET Configuration Tool or from the command prompt using caspol.exe. First we'll do this using the .NET Configuration Tool. Go to Control Panel --> Administrative Tools --> Microsoft .NET Framework Configuration. You can also type "mscorcfg.msc" at the .NET command prompt. You can do cool things with this tool ... but right now we are only interested in setting code access security.
Figure 3
Creating a new permission set
Expand the Runtime Security Policy node. You can see the security policy levels - Enterprise, Machine and User. We are going to change the security settings in Machine policy. First we are going to create our own custom permission set. Right click the Permission Sets node and choose New. Since I couldn't think of a catchy name, I'm going to name it MyPermissionSet.
Figure 4
In the next screen, we can add permissions to our permission set. In the left panel, we can see all the permissions supported by the .NET Framework. Now get the properties of File IO permission. Set the File Path to C:\ and check Read only, don't check others. So we didn't give write permission, we only gave read permission. Please note that there is another option saying "Grant assemblies unrestricted access to the file system." If this is selected, anything can be done without any restrictions for that particular resource, in this case the file system.
Figure 5
Now we have to add two more permissions - Security and User Interface. Just add them and remember to set the "Grant assemblies unrestricted access". I'll explain these properties soon. Without the Security permission, we don't have the right to execute our code, and without the User Interface permission, we won't be able to show a UI. If you're done adding these three permissions, you can see there is a new permission set created, named MyPermissionSet.
Creating a new code group
Now we will create a code group and set some conditions, so our assembly will be a member of that code group. Notice that in the code groups node, All_Code is the parent node. Right Click the All_Code node and choose New. You'll be presented with the Create Code Group wizard. I'm going to name it MyCodeGroup.
Figure 6
In the next screen, you have to provide a condition type for the code group. Now these are the evidence that I mentioned earlier. For this example, we are going to use the Strong Name condition type. First, sign your assembly with a strong name and build the project. Now press the Import button and select your assembly. Public Key, Name and Version will be extracted from the assembly, so we don't have to worry about them. Now move on to the next screen. We have to specify a permission set for our code group. Since we have already created one - MyPermissionSet, select it from the list box.
Figure 7
If you haven't messed around with the default .NET configuration security settings, your assembly already belongs to another built-in code group - My_Computer_Zone. When permissions are calculated, if a particular assembly falls into more than one code group within the same policy level, the final permissions for that assembly will be the union of all the permissions in those code groups. I'll explain how to calculate permissions later, for the time being we only need to run our assembly only with our permission set and that is MyPermissionSet associated with the MyCodeGroup. So we have to set another property to do just that. Right click the newly created MyCodeGroup node and select Properties. Check the check box saying "This policy level will only have the permissions from the permission set associated with this code group." This is called the Exclusive attribute. If this is checked then the run time will never grant more permissions than the permissions associated with this code group. The other option is called LevelFinal. These two properties come into action when calculating permissions and they are explained below in detail.
Figure 8
I know we have set lots of properties, but it'll all make sense at the end (hopefully).
Okay .. it's time to run the code. What we have done so far is, we have put our code into a code group and given permissions only to read from C: drive. Run the code and try both buttons. Read should work fine, but when you press Write, an exception will be thrown because we didn't set permission to write to C: drive. Below is the error message that you get.
Figure 9
So thanks to Code Access Security, this kind of restriction to a resource is possible. There's a whole lot more that you can do with Code Access Security, which we're going to discuss in the rest of this article.
According to the documentation, Code Access Security performs the following functions: (straight from the documentation)
- Defines permissions and permission sets that represent the right to access various system resources.
- Enables administrators to configure security policy by associating sets of permissions with groups of code (code groups).
- Enables code to request the permissions it requires in order to run, as well as the permissions that would be useful to have, and specifies which permissions the code must never have.
- Grants permissions to each assembly that is loaded, based on the permissions requested by the code and on the operations permitted by security policy.
- Enables code to demand that its callers have specific permissions. Enables code to demand that its callers possess a digital signature, thus allowing only callers from a particular organization or site to call the protected code.
- Enforces restrictions on code at run time by comparing the granted permissions of every caller on the call stack to the permissions that callers must have.
We have already done the top two, and that is the administrative part. There's a separate namespace that we haven't looked at yet - System.Security, which is dedicated to implementing security.
These are the main classes in System.Security namespace:
| Classes |
Description |
CodeAccessPermission |
Defines the underlying structure of all code access permissions. |
PermissionSet |
Represents a collection that can contain many different types of permissions. |
SecurityException |
The exception that is thrown when a security error is detected. |
These are the main classes in System.Security.Permissions namespace:
| Classes |
Description |
EnvironmentPermission |
Controls access to system and user environment variables. |
FileDialogPermission |
Controls the ability to access files or folders through a file dialog. |
FileIOPermission |
Controls the ability to access files and folders. |
IsolatedStorageFilePermission |
Specifies the allowed usage of a private virtual file system. |
IsolatedStoragePermission |
Represents access to generic isolated storage capabilities. |
ReflectionPermission |
Controls access to metadata through the System.Reflection APIs. |
RegistryPermission |
Controls the ability to access registry variables. |
SecurityPermission |
Describes a set of security permissions applied to code. |
UIPermission |
Controls the permissions related to user interfaces and the clipboard. |
You can find more permission classes in other namespaces. For example, SocketPermission and WebPermission in System.Net namespace, SqlClientPermission in System.Data.SqlClient namespace, PerformanceCounterPermission in System.Diagnostics namespace etc. All these classes represent a protected resource.
Next, we'll see how we can use these classes.
You can use two different kinds of syntax when coding, declarative and imperative.
Declarative syntax
Declarative syntax uses attributes to mark the method, class or the assembly with the necessary security information. So when compiled, these are placed in the metadata section of the assembly.
[FileIOPermission(SecurityAction.Demand, Unrestricted=true)]
public calss MyClass
{
public MyClass() {...}
public void MyMethod_A() {...}
public void MyMethod_B() {...}
}
Imperative syntax
Imperative syntax uses runtime method calls to create new instances of security classes.
public calss MyClass
{
public MyClass() { }
public void Method_A()
{
FileIOPermission myPerm =
new FileIOPermission(PermissionState.Unrestricted);
myPerm.Demand();
}
public void Method_B()
{
}
}
The main difference between these two is, declarative calls are evaluated at compile time while imperative calls are evaluated at runtime. Please note that compile time means during JIT compilation (IL to native).
There are several actions that can be taken against permissions.
First, let's see how we can use the declarative syntax. Take the UIPermission class. Declarative syntax means using attributes. So we are actually using the UIPermissionAttribute class. When you refer to the MSDN documentation, you can see these public properties:
Action - one of the values in SecurityAction enum (common)
Unrestricted - unrestricted access to the resource (common)
Clipboard - type of access to the clipboard, one of the values in UIPermissionClipboard enum (UIPermission specific)
Window - type of access to the window, one of the values in UIPermissionWindow enum (UIPermission specific).
Action and Unrestricted properties are common to all permission classes. Clipboard and Window properties are specific to UIPermission class. You have to provide the action that you are taking and the other properties that are specific to the permission class you are using. So in this case, you can write like the following:
[UIPermission(SecurityAction.Demand,
Clipboard=UIPermissionClipboard.AllClipboard)]
or with both Clipboard and Window properties:
[UIPermission(SecurityAction.Demand,
Clipboard=UIPermissionClipboard.AllClipboard,
Window=UIPermissionWindow.AllWindows)]
If you want to declare a permission with unrestricted access, you can do it as the following:
[UIPermission(SecurityAction.Demand, Unrestricted=true)]
When using imperative syntax, you can use the constructor to pass the values and later call the appropriate action. We'll take the RegistryPermission class.
RegistryPermission myRegPerm =
new RegistryPermission(RegistryPermissionAccess.AllAccess,
"HKEY_LOCAL_MACHINE\\Software");
myRegPerm.Demand();
If you want unrestricted access to the resource, you can use PermissionState enum in the following way:
RegistryPermission myRegPerm = new
RegistryPermission(PermissionState.Unrestricted);
myRegPerm.Demand();
This is all you need to know to use any permission class in the .NET Framework. Now, we'll discuss about the actions in detail.
Demands are used to ensure that every caller who calls your code (directly or indirectly) has been granted the demanded permission. This is accomplished by performing a stack walk. What .. a cat walk? No, that's what your girl friend does. I mean a stack walk. When demanded for a permission, the runtime's security system walks the call stack, comparing the granted permissions of each caller to the permission being demanded. If any caller in the call stack is found without the demanded permission then a SecurityException is thrown. Please look at the following figure which is taken from the MSDN documentation.
Figure 10
Different assemblies as well as different methods in the same assembly are checked by the stack walk.
Now back to demands. These are the three types of demands.
- Demand
- Link Demand
- Inheritance Demand
Demand
Try this sample coding. We didn't use security namespaces before, but we are going to use them now.
using System.Security;
using System.Security.Permissions;
Add another button to the existing form.
private void btnFileRead_Click(object sender, System.EventArgs e)
{
try
{
InitUI(1);
}
catch (SecurityException err)
{
MessageBox.Show(err.Message,"Security Error");
}
catch (Exception err)
{
MessageBox.Show(err.Message,"Error");
}
}
InitUI just calls the ShowUI function. Note that it has been denied permission to read the C: drive.
[FileIOPermission(SecurityAction.Deny,Read="C:\\")]
private void InitUI(int uino)
{
// Do some initializations
ShowUI(uino); // call ShowUI
}
ShowUI function takes uino in and shows the appropriate UI.
private void ShowUI(int uino)
{
switch (uino)
{
case 1:
ShowFileReadUI();
break;
case 2:
break;
}
}
ShowFileReadUI shows the UI related to reading files.
private void ShowFileReadUI()
{
MessageBox.Show("Before calling demand");
FileIOPermission myPerm = new
FileIOPermission(FileIOPermissionAccess.Read, "C:\\");
myPerm.Demand();
// All callers must have read permission to C: drive
// Note: Using imperative syntax
// code to show UI
MessageBox.Show("Showing FileRead UI");
// This is excuted if only the Demand is successful.
}
I know that this is a silly example, but it's enough to do the job.
Now run the code. You should get the "Before calling demand" message, and right after that the custom error message - "Security Error". What went wrong? Look at the following figure:
Figure 11
We have denied read permission for the InitUI method. So when ShowFileReadUI demands read permission to C: drive, it causes a stack walk and finds out that not every caller is granted the demanded permission and throws an exception. Just comment out the Deny statement in InitUI method, then this should be working fine because all the callers have the demanded permission.
Note that according to the documentation, most classes in .NET Framework already have demands associated with them. For example, take the StreamReader class. StreamReader automatically demands FileIOPermission. So placing another demand just before it causes an unnecessary stack walk.
Link Demand
A link demand only checks the immediate caller (direct caller) of your code. That means it doesn't perform a stack walk. Linking occurs when your code is bound to a type reference, including function pointer references and method calls. A link demand can only be applied declaratively.
[FileIOPermission(SecurityAction.LinkDemand,Read="C:\\")]
private void MyMethod()
{
// Do Something
}
Inheritance Demand
Inheritance demands can be applied to classes or methods. If it is applied to a class, then all the classes that derive from this class must have the specified permission.
[SecurityPermission(SecurityAction.InheritanceDemand)]
private class MyClass()
{
}
If it is applied to a method, then all the classes that derive from this class must have the specified permission to override that method.
private class MyClass()
{
public class MyClass() {}
[SecurityPermission(SecurityAction.InheritanceDemand)]
public virtual void MyMethod()
{
}
}
Like link demands, inheritance demands are also applied using declarative syntax only.
Imagine a situation like this. You have given a nice form to the user with 20+ fields to enter and at the end, all the information would be saved to a text file. The user fills all the necessary fields and when he tries to save, he'll get this nice message saying it doesn't have the necessary permission to create a text file! Of course you can try to calm him down explaining all this happened because of a thing called stack walk .. caused by a demand .. and if you are really lucky you can even get away by blaming Microsoft (believe me ... sometimes it works!).
Wouldn't it be easier if you can request the permissions prior to loading the assembly? Yes you can. There are three ways to do that in Code Access Security.
- RequestMinimum
- RequestOptional
- RequestRefuse
Note that these can only be applied using declarative syntax in the assembly level, and not to methods or classes. The best thing in requesting permissions is that the administrator can view the requested permissions after the assembly has been deployed, using the permview.exe (Permission View Tool), so what ever the permissions needed can be granted.
RequestMinimum
You can use RequestMinimum to specify the permissions your code must have in order to run. The code will be only allowed to run if all the required permissions are granted by the security policy. In the following code fragment, a request has been made for permissions to write to a key in the registry. If this is not granted by the security policy, the assembly won't even get loaded. As mentioned above, this kind of request can only be made in the assembly level, declaratively.
using System;
using System.Windows.Forms;
using System.IO;
using System.Security;
using System.Security.Permissions;
[assembly:RegistryPermission(SecurityAction.RequestMinimum,
Write="HKEY_LOCAL_MACHINE\\Software")]
namespace SecurityApp
{
}
RequestOptional
Using RequestOptional, you can specify the permissions your code can use, but not required in order to run. If somehow your code has not been granted the optional permissions, then you must handle any exceptions that is thrown while code segments that need these optional permissions are being executed. There are certain things to keep in mind when working with RequestOptional.
If you use RequestOptional with RequestMinimum, no other permissions will be granted except these two, if allowed by the security policy. Even if the security policy allows additional permissions to your assembly, they won't be granted. Look at this code segment:
[assembly:FileIOPermission(SecurityAction.RequestMinimum, Read="C:\\")]
[assembly:FileIOPermission(SecurityAction.RequestOptional, Write="C:\\")]
The only permissions that this assembly will have are read and write permissions to the file system. What if it needs to show a UI? Then the assembly still gets loaded but an exception will be thrown when the line that shows the UI is executing, because even though the security policy allows UIPermission, it is not granted to this assembly.
Note that, like RequestMinimum, RequestOptional doesn't prevent the assembly from being loaded, but throws an exception at run time if the optional permission has not been granted.
RequestRefuse
You can use RequestRefuse to specify the permissions that you want to ensure will never be granted to your code, even if they are granted by the security policy. If your code only wants to read files, then refusing write permission would ensure that your code cannot be misused by a malicious attack or a bug to alter files.
[assembly:FileIOPermission(SecurityAction.RequestRefuse, Write="C:\\")]
Sometimes you need to override certain security checks. You can do this by altering the behavior of a permission stack walk using these three methods. They are referred to as stack walk modifiers.
Assert
You can call the Assert method to stop the stack walk from going beyond the current stack frame. So the callers above the method that has used Assert are not checked. If you can trust the upstream callers, then using Assert would do no harm. You can use the previous example to test this. Modify the code in ShowUI method, just add the two new lines shown below:
private void ShowUI(int uino)
{
FileIOPermission myPerm = new
FileIOPermission(FileIOPermissionAccess.Read, "C:\\");
myPerm.Assert(); // don't check above stack frames.
switch (uino)
{
case 1: // That's our FileRead UI
ShowFileReadUI();
break;
case 2:
// Show someother UI
break;
}
CodeAccessPermission.RevertAssert(); // cancel assert
}
Make sure that the Deny statement is still there in InitUI method. Now run the code. It should be working fine without giving any exceptions. Look at the following figure:
Figure 12
Even though InitUI doesn't have the demanded permission, it is never checked because the stack walk stops from ShowUI. Look at the last line. RevertAssert is a static method of CodeAccessPermission. It is used after an Assert to cancel the Assert statement. So if the code below RevertAssert is accessing some protected resources, then a normal stack walk would be performed and all callers would be checked. If there's no Assert for the current stack frame, then RevertAssert has no effect. It is a good practice to place the RevertAssert in a finally block, so it will always get called.
Note that to use Assert, the Assertion flag of the SecurityPermission should be set.
Warning from Microsoft!: If asserts are not handled carefully it may lead into luring attacks where malicious code can call our code through trusted code.
Deny
We have used this method already in the previous example. The following code sample shows how to deny permission to connect to a restricted website using imperative syntax:
WebPermission myWebPermission =
new WebPermission(NetworkAccess.Connect,
"http://www.somewebsite.com");
myWebPermission.Deny();
CodeAccessPermission.RevertDeny();
RevertDeny is used to remove a previous Deny statement from the current stack frame.
PermitOnly
You can use PermitOnly in some situations when needed to restrict permissions granted by security policy. The following code fragment shows how to use it imperatively. When PermitOnly is used, it means only the resources you specify can be accessed.
WebPermission myWebPermission =
new WebPermission(NetworkAccess.Connect,
"http://www.somewebsite.com");
myWebPermission.PermitOnly();
CodeAccessPermission.PermitOnly();
You can use PermitOnly instead of Deny when it is more convenient to describe resources that can be accessed instead of resources that cannot be accessed.
In the first example, we configured the machine policy level to set permissions for our code. Now we'll see how those permissions are calculated and granted by the runtime when your code belongs to more than one code group in the same policy level or in different policy levels.
The CLR computes the allowed permission set for an assembly in the following way:
- Starting from the All_Code code group, all the child groups are searched to determine which groups the code belongs to, using identity information provided by the evidence. (If the parent group doesn't match, then that group's child groups are not checked.)
- When all matches are identified for a particular policy level, the permissions associated with those groups are combined in an additive manner (union).
- This is repeated for each policy level and permissions associated with each policy level are intersected with each other.
So all the permissions associated with matching code groups in one policy level are added together (union) and the result for each policy level is intersected with one another. An intersection is used to ensure that policy lower down in the hierarchy cannot add permissions that were not granted by a higher level.
Look at the following figure taken from a MSDN article, to get a better understanding:
Figure 13
Have a quick look at the All_Code code group's associated permission set in Machine policy level. Hope it makes sense by now.
Figure 14
The runtime computes the allowed permission set differently if the Exclusive or LevelFinal attribute is applied to the code group. If you are not suffering from short term memory loss, you should remember that we set the Exclusive attribute for our code group - MyCodeGroup in the earlier example.
Here's what happens if these attributes are set.
Exclusive - The permissions with the code group marked as Exclusive are taken as the only permissions for that policy level. So permissions associated with other code groups are not considered when computing permissions.
LevelFinal - Policy levels (except the application domain level) below the one containing this code group are not considered when checking code group membership and granting permissions.
Now you should have a clear understanding why we set the Exclusive attribute earlier.
There are some nice features in .NET Configuration Tool. Just right click the Runtime Security Policy node and you'll see what I'm talking about.
Figure 15
Among other options there are two important ones.
- Evaluate Assembly - This can be used to find out which code group(s) a particular assembly belongs to, or which permissions it has.
- Create Deployment Package - This wizard will create a policy deployment package. Just choose the policy level and this wizard will wrap it into a Windows Installer Package (.msi file), so what ever the code groups and permissions in your development PC can be quickly transferred to any other machine without any headache.
Permissions View Tool - permview.exe
The Permissions View tool is used to view the minimal, optional, and refused permission sets requested by an assembly. Optionally, you can use permview.exe to view all declarative security used by an assembly. Please refer to the MSDN documentation for additional information.
Examples:
- permview SecurityApp.exe - Displays the permissions requested by the assembly SecurityApp.exe.
Code Access Security Policy Tool - caspol.exe
The Code Access Security Policy tool enables users and administrators to modify security policy for the machine policy level, the user policy level and the enterprise policy level. Please refer to the MSDN documentation for additional information.
Examples:
Here's the output when you run "caspol -listgroups", this will list the code groups that belong to the default policy level - Machine level.
Figure 16
Note that label "1." is for All_Code node because it is the parent node. It's child nodes are labeled as "1.x", and their child nodes are labeled as "1.x.x", get the picture?
- caspol -listgroups - Displays the code groups
- caspol -machine -addgroup 1. -zone Internet Execution - Adds a child code group to the root of the machine policy code group hierarchy. The new code group is a member of the Internet zone and is associated with the Execution permission set.
- caspol -user -chggroup 1.2. Execution - Changes the permission set in the user policy of the code group labeled 1.2. to the Execution permission set.
- caspol -security on - Turns code access security on.
- caspol -security off - Turns code access security off.
- Using .NET Code Access Security, you can restrict what your code can do, restrict which code can call your code and identify code.
- There are four policy levels -
Enterprise, Machine, User and Application Domain which contains code groups with associated permissions.
- Can use declarative syntax or imperative syntax.
- Demands can be used to ensure that every caller has the demanded permission.
- Requests can be used to request (or refuse) permissions in the grant time.
- Granted permissions can be overridden.
That's it. Take a look at the Functions of Code Access Security again. You should have a clear understanding by now than the first time you saw it. There are things like creating custom code access permissions, and best practices when using Code Access Security, which I haven't discussed in this article. If you want more information, you may refer to the following:
I suggest that you go through the whole article one more time, just to make sure you didn't miss anything. If it's still not clear, don't worry, it's not your fault, it's my fault. :)
Happy Coding !!!
- Dec 22, 2003 - Original Version
- Jan 12, 2004 - Corrected a bug in code. (Security Demands section - ShowUI1(1) to InitUI(1) in btnFileRead_Click event) - pointed out by Mark Focas, Thanks a lot Mark! Updated screen shots (reduced the file size by 4 times). Added section - "Nice Features in .NET Configuration Tool". Added Figure 16 (caspol screen shot).
