Programming .NET Security : Using the Code-Access Security Policy Tool (part 1) - Administering Policy Levels

The Code Access Security Policy tool (Caspol.exe) is a utility provided with the .NET Framework that allows you to administer .NET's code-access security system from the command line and from batch files. You can run Caspol.exe from the following location, where version is the version of the .NET framework, such as "v1.0.3705" for Version 1.0:

%Systemroot%\Microsoft.NET\Framework\version\Caspol.exe

When performing some administrative tasks Caspol.exe commands can become long and confusing, but for many tasks, Caspol.exe provides a much quicker way of configuring and inspecting security policy, as long as you are happy to work from the command line. Before we look at how to configure security policy using Caspol.exe, there is one Caspol.exe configuration setting that you will want to change if you use Caspol.exe frequently.

Whenever you run a Caspol.exe command that changes the security policy configuration, before Capsol.exe commits the change to disk, it will prompt you to confirm the change with the following message:

The operation you are performing will alter security policy.
Are you sure you want to perform this operation? (yes/no)

You must enter "y" or "yes" for the change to proceed. Although it serves a valuable purpose, you will find this level of protection frustrating if you use Caspol.exe frequently. To turn this prompt on and off use the following statements, but remember that if you turn it off, any changes you make will be committed automatically:

caspol -polchgprompt on
caspol -polchgprompt off

Each Caspol.exe command has a short version as well as the full version we use throughout this section. For example, the short version of the -polchgprompt flag we just used is -pp. Consult the .NET SDK Documentation for the short versions of each command.

1. Controlling the Security System

Not only does Caspol.exe allow you to manage security policy, but it also allows you to manage some higher-level configuration settings of the security system. These features map directly to methods of the System.Security.SecurityManager class.

1.1. Switching code-access security on and off

To switch code-access security on and off, use the -security flag, as shown here:

caspol -security on
caspol -security off

Turning off code-access security bypasses the security system, meaning that all code has full permission to perform any action. You should consider this only after ensuring that other security mechanisms, such as operating system security, are in place and properly configured to protect your system and resources.

1.2. Switching execution permission checks on and off

Normally, the .NET Framework runtime checks to see if an assembly has the SecurityPermission.Execution permission before it will load and run the assembly. You can switch execution permission checking on and off using the -execution flag shown here:

caspol -execution on
caspol -execution off

There are performance benefits from turning off execution checking; your assembly will load and start more quickly, but you must weigh those savings against the decreased security. Once an assembly is running, there are many undesirable things that malicious code can do that do not require permissions, such as making heavy use of your CPU. Also' once loaded, malicious code is free to probe the security you have in place to try to identify any weaknesses that exist.

2. Administering Policy Levels

With respect to the administration of security policy, the functionality of Caspol.exe is much the same . In the following sections, we describe how to manage each of the key elements of security policy, but first we must describe how to target your Caspol.exe commands to affect the appropriate policy level and code group.

2.1. Specifying the target policy level

You must target each policy-administration command at the policy levels you want it to affect using one of the following flags:

-all

Affects the enterprise and machine policies as well as the user policy for the currently logged-on user

-enterprise

Affects only the enterprise policy

-machine

Affects only the machine policy

-user

Affects only the user policy for the currently logged on user

-customuser path

Affects only the user policy contained in the security policy file located at the specified path

-customall path

Affects the enterprise and machine policies as well as the user policy contained in the security policy file located at the specified path

Not every target value is valid for every Caspol.exe command. In addition, if you do not specify a target policy level, the result will depend on the command you execute; some commands assume a default -machine setting, others use -all. We describe the default behavior when we discuss the individual commands.

2.2. Specifying the target code group

Some Caspol.exe commands require you to specify an existing code group as the target of the command. For example, you must identify the code group you want to delete, or the code group under which you want to add a new child code group. Caspol.exe provides two ways in which you can uniquely reference a code group.

First, because code group names must be unique within their policy levels, you can use the name of the code group. 

Second, you can use a numeric label that uniquely represents the position of the target code group within the code group hierarchy of a policy group. The root code group has a label of "1.", and every code group below it has a label that identifies its position among its peers—for example, "1.1.", "1.2.", "1.3.", and so on. The labels extend to accommodate all the levels in the code group hierarchy—for example, "1.1.", "1.1.1.", "1.1.1.1.", and so on. You must always include the final decimal point when specifying the label of a code group.

2.3. Managing fully trusted assemblies

To list the fully trusted assemblies in a policy level use the -listfulltrust flag. The default target for -listfulltrust is -machine, but you can specify any of the target values; we show some examples here:

caspol -listfulltrust
caspol -all -listfulltrust
caspol -customuser "c:\someuser\security.config" -listfulltrust

The start of the output from these commands will look similar to the following. The output shows some general Caspol.exe settings, identifies the target policy level, and then lists the fully trusted assemblies, along with strong-name information.

Microsoft (R) .NET Framework CasPol 1.0.3705.288
Copyright (C) Microsoft Corporation 1998-2001. All rights reserved.

Security is ON
Execution checking is ON
Policy change prompt is ON

Level = Machine

Full Trust Assemblies:

1.  mscorlib.resources 1.0.3300.0 =
StrongName - 00000000000000000400000000000000 name = mscorlib.resources version
= 1.0.3300.0
2.  System 1.0.3300.0 =
StrongName - 00000000000000000400000000000000 name = System version = 1.0.3300.0

					  

To add an assembly to the fully trusted list of a policy level, use the -addfulltrust flag. You cannot specify -all or -customall as the target, and if you do not specify any target, -machine is used. You must specify the name and path of the assembly that you want to add to the fully trusted list, as shown in the following examples:

caspol -addfulltrust SomeAssembly.dll
caspol -user -addfulltrust C:\Development\SomeOtherAssembly.dll

						

To remove an assembly from the fully trusted assembly list, use the -remfulltrust flag and specify the name of the assembly to remove, as shown here; note that you do not need to include any path information. Again, the default target is -machine, and you cannot specify -all or -customall as the target of the command:

caspol -remfulltrust SomeAssembly.dll
caspol -user -remfulltrust SomeOtherAssembly.dll

2.4. Managing named permission sets

To list the named permission sets currently defined in a policy level, use the -listpset flag. The default target for -listpset is -machine, but you can specify any target, as shown in these examples:

caspol -listpset
caspol -user -listpset
caspol -customall "c:\someuser\security.config" -listpset

The start of the output from these commands will look something like this, showing the XML representation of every code group defined in the policy level. This information is long and difficult to read in this format, but you cannot get Caspol.exe to list the definition of a specific permission set:

Microsoft (R) .NET Framework CasPol 1.0.3705.288
Copyright (C) Microsoft Corporation 1998-2001. All rights reserved.

Security is ON
Execution checking is ON
Policy change prompt is ON

Level = Machine

Named Permission Sets:

1. FullTrust (Allows full access to all resources) =
<PermissionSet class="System.Security.NamedPermissionSet"
               version="1"
               Unrestricted="true"
               Name="FullTrust"
               Description="Allows full access to all resources"/>

2. SkipVerification (Grants right to bypass the verification) =
<PermissionSet class="System.Security.NamedPermissionSet"
               version="1"
               Name="SkipVerification"
               Description="Grants right to bypass the verification">
   <IPermission class="System.Security.Permissions.SecurityPermission, mscorlib,
 Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"
                version="1"
                Flags="SkipVerification"/>
</PermissionSet>

					  

To add a new named permission set to a policy level, use the -addpset flag. You must specify the name of the file that contains the XML description of the permission set to add. This is equivalent to importing the permission set using Mscorcfg.msc, and the XML format is the same. The following statements demonstrate how to create permission sets from an XML description contained in the file pset.xml. You cannot use -all or -customall as the target of the command, and the default is -machine:

caspol -addpset pset.xml
caspol -enterprise -addpset pset.xml

If the XML description of the permission set does not include a Name attribute, Capsol.exe will throw an error and refuse to create the permission set. In this case, you must specify the name of the permission set as an argument to the -addpset command, as shown here where we name the permission set "TestSet":

caspol -addpset pset.xml TestSet
caspol -enterprise -addpset pset.xml TestSet

You can change an existing permission set using the -chgpset flag and specifying the name of the existing permission set to change and the name of the file containing the new XML description for the permission set. The -chgpset command simply overwrites the existing permission set definition with the new one. For example, to change the TestSet permission set that we just created using the contents of a file named newpset.xml, we use these commands:

caspol -chgpset newpset.xml TestSet
caspol -enterprise -chgpset newpset.xml TestSet

To remove a named permission set, use the -rempset flag and specify the name of the permission set to remove. Here we show how to remove the TestSet permission set that we just created. Again, the default target is -machine, and you cannot specify -all or -customall as the target of the command:

caspol -rempset TestSet
caspol -enterprise TestSet

Caspol.exe will not remove permission sets that are in use by code groups.

2.5. Managing code groups

To list the code groups in a policy level, use the -listgroups flag. The default target for -listgroups is -machine, but you can specify any of the target settings, as demonstrated in the following examples:

caspol -listgroups
caspol -user -listgroups
caspol -customuser "c:\someuser\security.config" -listgroups

When executed against the default machine policy, the output of the -listgroups command looks like this; the numeric label we discussed in Section 9.4.2.2 precedes the membership condition, and the name of the permission set each code group grants:

Microsoft (R) .NET Framework CasPol 1.0.3705.288
Copyright (C) Microsoft Corporation 1998-2001. All rights reserved.

Security is ON
Execution checking is ON
Policy change prompt is ON

Level = Machine

Code Groups:

1.  All code: Nothing
   1.1.  Zone - MyComputer: FullTrust
      1.1.1.  StrongName - 00240000048000009400000006020000002400005253413100040
0000100010007D1FA57C4AED9F0A32E84AA0FAEFD0DE9E8FD6AEC8F87FB03766C834C99921EB23BE
79AD9D5DCC1DD9AD236132102900B723CF980957FC4E177108FC607774F29E8320E92EA05ECE4E82
1C0A5EFE8F1645C4C0C93C1AB99285D622CAA652C1DFAD63D745D6F2DE5F17E5EAF0FC4963D261C8
A12436518206DC093344D5AD293: FullTrust
      1.1.2.  StrongName - 00000000000000000400000000000000: FullTrust
   1.2.  Zone - Intranet: LocalIntranet
      1.2.1.  All code: Same site Web.
      1.2.2.  All code: Same directory FileIO - Read, PathDiscovery
   1.3.  Zone - Internet: Nothing
   1.4.  Zone - Untrusted: Nothing
   1.5.  Zone - Trusted: Internet
      1.5.1.  All code: Same site Web.
Success

					  

To add a new code group to a policy level, use the -addgroup flag. Because of the complexity of code group configuration, the -addgroup command is the most complex Caspol.exe statement, and takes multiple arguments with many optional values. The general form of the -addgroup command is shown here:

caspol -target -addgroup {label|name} membership pset [flags]

The target argument specified the target policy level, which defaults to -machine, and cannot be -all or -customall. The label and name arguments allow you to specify the parent of the new code group using either its numeric label or name. The membership, pset, and flags arguments specify the membership condition, permission set, and properties of the code group respectively. We summarize the possible values of the membership argument in Table 1, and those of the flags argument in Table 2.

Table 1. Possible values of the membership argument

Value	Description
-all	Specifies that all code is a member of the code group.
-appdir	Looks for both ApplicationDirectory and Url evidence and tests to see of if the location specified in the Url evidence represents a location that is a child of the location specified in the ApplicationDirectory evidence.
-custom xmlfile	Specifies the use of a custom membership condition to determine membership of the code group. The xmlfile argument specifies the name of the file containing the XML description of the custom membership condition.
-hash hashAlg {-hex value|-file assembly}	Specifies that all code with Hash evidence of a specified value is a member of the code group. The hashAlg specifies the hashing algorithm to use, and the hex and file arguments provide different ways of providing the hash value; see the .NET Framework SDK documentation for details.
-pub {-cert file|-file file|-hex string}	Specifies that all code with the specified Publisher evidence is a member of the code group. The cert, file, and hex arguments provide different ways of specifying the publisher certificate to test for; see the .NET Framework SDK documentation for details.
-site sitename	Specifies that all code with the Site evidence specified by the sitename argument is a member of the code group.
-strong -file file_name name version	Specifies that all code with the specified StrongName evidence is a member of the code group. The file_name, name, and version arguments specify the component parts of the strong name; see the .NET Framework SDK documentation for details.
-url URL	Specifies that all code with the Url evidence specified by the URL argument is a member of the code group.
-zone zonename	Specifies that all code with the Zone evidence specified by the zonename argument is a member of the code group.

Table 2. Possible values of the flags argument

Value	Description
-description "description"	Allows you to specify the description for the code group, which you must enclose in double quotes.
-exclusive {on|off}	Allows you to set the code group's Exclusive attribute on or off.
-levelfinal {on|off}	Allows you to set the code group's LevelFinal attribute on or off.
-name "name"	Allows you to specify the name of the code group, which you must enclose in double quotes, and which must be unique within the target policy level.

To create a code group using the custom AuthorMembershipCondition class:

caspol -user -addgroup All_Code -custom Peter.xml FullTrust 
-name "Peter's code" -description "Code group grants all 
code written by Peter full trust"

The command to change an existing code group is also complex but uses the same arguments as the -addgroup command, with which you are now familiar. The general structure of a -chggroup command is as follows:

caspol -target -chggroup {label|name} {membership|pset|flags}

In the following example, we change the name of the machine-level code group with label "1.5." to "SomeTestGroup":

caspol -enterprise -chggroup 1.5. -name SomeTestGroup

Here, we target a machine-level code group named "MyCode" to change its membership condition and its permission set, and make the code group Exclusive; notice that we do not specify the target level because -machine is the default:

caspol -chggroup MyCode -url "file://c:\dev\*" FullTrust -exclusive on

To remove a code group, use the -remgroup flag and specify the code group to remove. The examples here show how to remove a code group in the enterprise level using both its name and numeric label. Again, the default target is -machine, and you cannot specify -all or -customall as the target of the command:

caspol -enterprise -remgroup 1.5. 
caspol -enterprise -remgroup SomeTestGroup