Using Batch Scripts for Security Policy Administration

for RuBoard

The .NET Framework ships with a command-line administration tool called Caspol (Code Access Security Policy tool). With it, you can undertake administrative changes of security policy via the command line. For example, the following is a Caspol command to reset the machine policy level:

 Caspol machine -reset 

By adding Caspol calls into a batch file ( .bat ), you can effectively create indefinitely complex scripts to change security policy. The following set of Caspol commands represents a script that first turns off Caspol's prompt to the user to ascertain a policy change, resets all of security policy, and adds a new code group under the Internet code group of the machine policy. The newly created code group has a site membership condition set to www.micrsosoft.com and hands out the intranet permission set:

 Caspol polchgprompt off Caspol all reset Caspol -machine addgroup Internet_Zone site www.micrsosoft.com LocalIntranet 

Executing a batch file with these three commands will programmatically change security policy without requiring any user input. You can run such policy change batch scripts either as part of an installation process for an application or even add a scheduled task on a machine to periodically switch security settings if necessary.

TIP

To create a scheduled task, open the control panel, open the Scheduled Task folder, and double-click the Add Scheduled Task Wizard. Browse to the batch script containing the Caspol commands you want to run periodically and choose the times at which to run it.

The various options that you can use to string together Caspol scripts are explained in some more detail in this section.

Also refer to the SDK documentation of the .NET Framework for help and more details.

Finding and Starting the Caspol Tool

Every installation of the .NET Framework comes with a copy of Caspol. You can find it in the %Windows%\Microsoft.NET\Framework\v [version number] \Caspol.exe directory.

%Windows% here refers to either the Winnt or Windows directory, depending on the operating system you are running. Because the .NET Framework allows different versions of itself to coexist, most .NET Framework libraries and tools are contained in version-specific directories. By browsing to the Framework subfolder, you can see which version or versions of the .NET Framework have been installed and pick the version that you want to administer by browsing to the respective version subdirectory and calling Caspol. If you have the SDK installed, the PATH environment variable will contain the path to the latest version of the SDK on the machine. In such cases, you can type Caspol from anywhere in the file system. The regular redistributable installations of the .NET Framework will not modify the PATH environment variable to contain the preceding path. In that, case you will need to browse to Caspol as indicated at the beginning of this section.

TIP

You can change the environment variable of your system by opening the Control Panel, choosing the System icon, clicking Advanced, selecting Environment Variables and, under System Variables, select the Path variable and edit it to contain the path of the location of the Caspol tool.

Caspol will always only modify the version of the .NET Framework with which it has been installed. If you happen to have multiple versions of the .NET Framework installed on your system, you will need to run your policy change scripts for each version for which you want to change policy.

Basic Caspol Techniques

This section contains a detailed list of most of the options Caspol has to offer. They are similar in type and use to what you can do in the .NET Framework Configuration tool using the graphical security model representation it offers.

For each option, its syntax, at least one example, and the option abbreviation is given.

Format and Scope of Caspol Commands

The basic format of Caspol commands is as follows :

 Caspol [Policy Level Directive]  Option   Arguments   [ [Policy Level Directive] Option Arguments]*  

Every line in your Caspol script will start with Caspol, invoking the Caspol tool.

The Caspol tool will execute one option and its given arguments at a time and return to the command line when finished. As the previous syntax indicates, it is possible to concatenate multiple option-arguments pairs in one Caspol call, although the suggested way of using Caspol is to call it one option-arguments pair at a time.

Because security policy consists of three administrable policy levels, most Caspol options need to be scoped to one of the three policy levels. This is done using the following option prefixes:

 -enterprise -machine -user 

For example, the first Caspol command in the following example resets the user policy level to its default policy state, while the second command resets the enterprise policy level:

 Caspol user reset Caspol enterprise reset 

While the use of friendly option names makes it clearer what you are trying to do with security policy, they also can make for a lot of typing. For that reason, Caspol also understands abbreviated forms for every option it offers. For example, the policy level directives just introduced are abbreviated to “en , “m , and “u , while the reset option is abbreviated to “rs . As a result, the previous two sample commands could have just as easily been written as follows:

 Caspol u rs Caspol en rs 

For every Caspol option introduced in this chapter, the abbreviations will be given, along with the full syntax of the option in question.

A few Caspol commands can also be preceded by the “all directive, meaning that the option following this directive applies to all policy levels. For example, you can reset all security policy levels, with the following command:

 Caspol all reset 

Finally, you may wonder what happens if you leave off the policy level directive before an option, such as a reset. Caspol actually always determines whether you have write access to the machine policy file. If so, it defaults all options not explicitly preceded by a policy level directive to the machine policy level. For example, if you have write access to the machine policy file (typically by having machine administrator rights), the following command will reset the machine policy level:

 Caspol reset 

If the user on whose behalf Caspol is running does not have write access to the machine and enterprise policy settings, all Caspol options not preceded by an explicit policy level directive are defaulted to the user level policy. In this case, the previous command would have reset the user policy level.

TIP

When writing Caspol scripts, you should always precede policy change options with the policy level directive, because the script may be run in user contexts with different write access to the machine policy.

Not all Caspol options need to be preceded by a policy level directive. Mostly, these are options that refer to the security system as a whole (such as the option to turn security off) or to the functioning of the Caspol tool itself. This fact will be made explicit by the syntax notation for the respective options introduced shortly.

All policy changes made using Caspol are immediate. There is no sense of a multistep policy change transaction. So if your script fails prior to the execution of all commands in it, the changes made by the Caspol commands that have succeeded will be present in security policy. For that reason, design scripts carefully and cautiously.

Turning the Policy Change Prompt Off

By default, Caspol requires an explicit user acknowledgment to persist policy changes into security policy. For example, after typing in the Caspol command to reset the machine policy, the user will be queried to affirm that this should really be done. This is a helpful aid in preventing usage error in case an option or an argument has been mistyped , but this would also make running an automated policy change batch script impossible . For that reason, Caspol offers the option to turn these warnings off.

Syntax:

 -polchgprompt {off  on } 

Abbreviation:

 -pp {off  on } 

Example:

 Caspol pp off 

TIP

Unless you are absolutely certain that you have previously run a command, you should include the policy change prompt command as the first line in all of your scripts to make sure that it will run without requiring any user interaction. The policy change prompt setting is stored in a machine “wide registry key that sets the policy change warning for the specific version of Caspol that is run to make that change.

Showing Current Security Policy Settings

Security policy contains three administrable policy levels, each of which consists of a tree of code groups, a list of known permissions, and a list of policy assemblies.

NOTE

Please refer to Part II, "Code Access Security Fundamentals," for a detailed discussion of the security model.

To display the state of policy, Caspol ships with a variety of options that help you view parts or all of security policy.

If you want to see the tree of code groups of a policy level, or of all policy levels, use the following option:

Syntax:

 [{-u[ser],-m[achine],-en[terprise],-a[ll]}] listgroups 

Abbreviation:

 -lg 

Example:

 Caspol a lg 

This example will show you the code group hierarchy of all administrable policy levels (user, machine, and enterprise policy level).

If you have write access rights to the machine and enterprise policy, the following command will show you the machine policy level's code groups:

 Caspol listgroups 

The output of this command for the machine policy looks much like the following:

 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 - 0024000004800000940000000602000000240000525341310004000001 00010007D1FA57C4AED9F0A32E84AA0FAEFD0DE9E8FD6AEC8F87FB03766C834C99921EB23BE79AD9 D5DCC1DD9AD236132102900B723CF980957FC4E177108FC607774F29E8320E92EA05ECE4E821C0A5 EFE8F1645C4C0C93C1AB99285D622CAA652C1DFAD63D745D6F2DE5F17E5EAF0FC4963D261C8A1243 6518206DC093344D5AD293: 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.3.1.  All code: Same site Web.    1.4.  Zone - Untrusted: Nothing    1.5.  Zone - Trusted: Internet       1.5.1.  All code: Same site Web. 

To represent a tree structure of code groups, Caspol uses both indentation as well as a sub-sectional numeric labeling system. For example, lines starting with a 1 . number label are child code groups of the code group with label 1 . Following the numeric label is the name of the membership condition, its value set for that code group, and lastly, the name of the permission set the code group hands out if the membership condition is met.

Each code group can have a description and a code group name. To display that additional information about each code group, use the following Caspol option:

Syntax:

 [{-u[ser],-m[achine],-en[terprise],-a[ll]}] listdescription 

Abbreviation:

 -ld 

Example:

 Caspol m ld 

This example will show you the code group names and descriptions of the machine policy level.

TIP

It is strongly recommended that you use a code group's name and not the numeric label in modifying security policy. The Caspol tool will reorder the numeric label depending on what code groups have been added or deleted from the initial default policy state, while code group names remain the same unless explicitly changed by an administrative action.

The named permission set a code group references is part of a list of known named permission sets at the respective policy level. To see this list for a policy level (or for all policy levels using the “all directive), use the following command:

Syntax:

 [{-u[ser],-m[achine],-en[terprise],-a[ll]}] listpset 

Abbreviation:

 -lp 

Example:

 Caspol all listpset 

This example will show the known permission sets at each policy level. Note that you will see the XML serialization of each permission set object known at the respective policy level. Each of the permission sets typically consists of a number of permissions configured to a specific permission state.

NOTE

Please see Chapter 6 for more details on permissions.

Finally, each policy level also contains a policy assemblies list. This list contains the transitive closure of all assemblies used to implement the code group hierarchy at a policy level.

NOTE

Please see the sections on policy assemblies in Chapters 8 and 18 for more detail.

To view this list, simply use the following Caspol option:

Syntax:

 [{-u[ser],-m[achine],-en[terprise],-a[ll]}] listfulltrust 

Abbreviation:

 -lf 

Example:

 Caspol en lf 

This example will show you the list of policy assemblies at the enterprise policy level. Note that this list will include the assembly names as well as the assemblies' strong names.

Caspol also offers an option that combines the “listgroup and “listpset options. If you want to view both, you can just use the following option:

Syntax:

 [{-u[ser],-m[achine],-en[terprise],-a[ll]}] list 

Abbreviation:

 -l 

Example:

 Caspol u list 

Adding a Code Group

To add a code group to the code group hierarchy of a policy level, use the following Caspol command:

Syntax:

 [{-u[ser],-m[achine],-en[terprise]}] -addgroup        {label_of_parent  name_of_parent}  mshipcondition  pset [  flags  ] 

Abbreviation:

 -ag 

Example:

 Caspol m ag Internet_Zone site www.microsoft.com LocalIntranet n MyIntranet-Group 

This example adds a code group to the machine code group hierarchy under the Internet_Zone code group. The new code group has a site membership condition with membership condition value of www.microsoft.com and hands out the LocalIntranet permission set if an assembly matches that membership condition. Last, the code group has been named MyIntranetGroup. Essentially, if you were to run this Caspol line over default machine policy, it would extend policy such that all assemblies from the microsoft.com site will receive not just the Internet permission set but LocalIntranet permissions.

All items in italics in the previous syntax description need further definition. As you will remember from Chapter 8, the .NET Framework security system offers a number of membership condition types for building up your security policy. If the built-in membership condition types do not suffice for your needs, you could even custom author your own membership conditions. Caspol allows you to add code groups using either the membership condition types shipping in the .NET Framework or using custom membership conditions. mshipcondition in the previous syntax description can be replaced by any of the following switches:

Syntax for mshipcondition :

• -allcode ” This membership condition will always be true ; it is typically used for root nodes in code group hierarchies.

• -appdir ” This membership condition tests whether an assembly's URL evidence matches the assembly's application directory.

• -custom MshipXMLFile ” This membership condition switch is used to import a custom membership condition into a code group hierarchy. MshipXMLFile is used to point at an XML file representing the XML serialization of the custom membership condition in a specific membership condition state.

• -hash HashAlg { -hex hashvalue -file assembly} ” This membership condition is used to check whether an assembly has a specified hash value. HashAlg should be set to a proper hash algorithm name, such as SHA1 or MD5 . You can then either type in the hexadecimal encoded hash value directly or (far more convenient ) point Caspol at the file whose hash value you want to add to policy.

NOTE

You should not use MD5 for HashAlg unless you have specific requirements to use MD5 . MD5 is cryptographically weaker than the various SHA hash algorithms.

When creating the hash of assembly Caspol, simply use the hash algorithm name you supplied to look up the corresponding algorithm implementation in the cryptography configuration system. This system, by default, maps standard hash algorithm names, such as MD5 , SHA1 , and SHA256 , to their managed implementation.

• -pub { -cert cert_file -file signed_file -hex certstring } ” This membership condition is used to check an assembly for a specific x.509 certificate. You can either point Caspol to a .cer file containing the cert you want to test for, point it at a signed assembly (probably the most common use form to supply this membership condition value), or type in the cert in hexadecimal encoding directly.

• -site sitename ” This membership condition tests whether an assembly came from a specific site.

• -strong “file signed_file { name -noname} { version -noversion} ” The “strong membership condition tests assemblies for a specific strong name signature. To set this membership condition's value, you need to point Caspol at a specific strong name signed file (such as Caspol.exe ). Additionally, you need to specify whether the membership condition should check for a specific assembly name (such as Caspol) and version (such as 1.0).

• -url URL ” The “url membership condition checks whether an assembly came from a specific URL address.

NOTE

To have an URL memebership condition match all files (and subdirectories) at a specific drive, folder, or site, you must append an \* at the end of the drive, folder, or site value. For example, “url file://\\\h:\* should be used to match all files and folders on drive h.

• -zone zone ” The -zone membership condition tests whether an assembly comes from the specified zone. The legal values you can use for the zone membership condition are Mycomputer, intranet, Trusted, Internet, and Untrusted.

In addition to the code group membership condition, you can optionally also specify a number of flags for the new code group. The following is a list of the available options:

• -exclusive {onoff} ” This flag makes a code group level exclusive. This means that if an assembly ever matches this code group, only the permission set granted by this code group determines the respective policy level's permission grant to the evaluated assembly.

• -levelfinal {onoff} ” If this flag is set and the code group carrying this flag is matched, policy resolution will stop at the present policy level. No policy levels below the one in which this flag occurred are evaluated.

• -n[ame] codegroupname ” This flag allows you to specify a name for the newly created code group.

TIP

It is highly suggested that you give all code groups you later may want to script to a unique name. Scripting policy changes against the numeric labels is very brittle because a simple code group addition or deletion can lead to a reordering of numeric labels.

• -d[escription] codegroupdescription ” This flag allows you to add a description to a code group.

Now, let's put all this together and look at a few more examples. Note that the Flags and mshipcondition switches will also be used to change properties on a code group, so understanding how to use them will pay off when writing your scripts.

 Caspol m ag Internet_Zone strong file Caspol.exe noname noversion FullTrust n  CaspolSNgroup 

The previous command will add a code group under the Internet_Zone group with a strong name membership condition. The strong name that this code group will check for is the strong name Caspol has been signed with; the code group will not check for a specific assembly name or version and grant the FullTrust permission set. The new code group has been named CaspolSNgroup.

 Caspol en ag All_Code hash SHA1 file myassembly.exe FullTrust exclusive on  levelfinal on n MyAssembly 

The previous Caspol line will add a code group under the root code group of the enterprise policy code group hierarchy. The code group will check whether an assembly matches the SHA1 hash value for myassembly.exe and, if so, the code group will grant the FullTrust permission set. The code group is also marked exclusive, excluding any other code group at the enterprise policy level from contributing to the permission set granted at that policy level. Furthermore, the code group is marked level final, which means that no further policy levels will be evaluated. This is an effective technique for making sure that a specific assembly or set of assemblies gets exactly the level of permissions you want, without having user or machine policy interfere. Finally, the code group name is set to MyAssembly.

Deleting a Code Group

The following is the syntax to delete a code group:

Syntax:

 [{-u[ser],-m[achine],-en[terprise]}] -remgroup { codegroup_labelcodegroup_name} 

Abbreviation:

 -rg 

Example:

 Caspol en rg MyAssembly 

This Caspol command deletes a code group with name MyAssembly from the enterprise policy code group hierarchy.

NOTE

If the code group being deleted has any child code groups, they will also be removed.

Changing the Properties of a Code Group

All properties of a code group can be altered by using the following Caspol option:

Syntax:

 [{-u[ser],-m[achine],-en[terprise]}] chggroup {codegroup_label  codegroupname} {  mshipcondition  pset  flags  } 

Abbreviation:

 -cg 

Example:

 Caspol en Myassembly pub file myassembly.exe levelfinal off 

When changing a code group using this option, you do not need to redefine all properties of a code group. As you can see in the previous example, the name, description, and permission set of the MyAssembly code group are left untouched. This code group is changed to check for a publisher certificate, and the level final flag is turned off.

NOTE

For a detailed description of the mshipcondition and Flags options, please see the "Adding a Code Group" section earlier in this chapter.

Adding a New Permission Set

Caspol allows you to add new named permission sets to the list of permission sets known at a policy level. Unlike the .NET Framework Configuration tool, Caspol does not have any support to help you build a new permission set. Caspol only allows you to import the XML serialization of a permission set you have already defined.

TIP

For more help on permission set XML syntax, please see the "Dealing with Custom Permissions and Permission Sets" section in Chapter 18.

Building your permission set XML is risky and very error prone. Instead, you should use the .NET Framework Configuration tool's New Permission Set Wizard to add a new permission set to a policy level. If that permission set needs to be exported across your enterprise's machines, simply open the respective policy file and copy the permission set XML the tool produced for you into a new .xml file. You can use that file with the following Caspol option.

Syntax:

 [{-u[ser],-m[achine],-en[terprise]}] -addpset { xml_file  xml_file name} 

Abbreviation:

 -ap 

Example:

 Caspol en mypset.xml MyPset 

This example adds the permission set defined in mypset.xml to the enterprise policy level under the name MyPset. If the name is already defined in the XML representation of the permission set, you do not need to explicitly state a permission set name in the Caspol command.

NOTE

If the added permission set contains any custom permission objects that are not part of the .NET Framework class library, you need to add the assembly that implements the custom permission to the Policy Assemblies list (see "Adding an Assembly to the Policy Assemblies List" later in this chapter). You will also need to add all assemblies on which that implementing assembly depends.

To see examples of the XML representations of a permission set, simply list the permission sets of a policy level:

 Caspol m lp 

This will show you the XML representation of all permission sets known at the machine level.

Changing a Permission Set

To change a permission set at a policy level, you need to supply the XML representation of the permission set that should replace the permission set to be altered. Use the following command to do just that:

Syntax:

 [{-u[ser],-m[achine],-en[terprise]}] -chgpset 

Abbreviation:

 -cp 

Example:

 Caspol u cp mynewpset.xml MyPset 

This Caspol command changes the MyPset to the permission set state represented by the mynewpset.xml file.

NOTE

Please see the "Adding a New Permission Set" section earlier in this chapter for some helpful tips and notes.

Removing a Permission Set

Removing a permission set from a policy level will require you to re-import it if you need to use it later to build a new code group. Consequently, you should only remove those permission sets that you are reasonably sure you won't need at a future point. Caspol will not allow you to remove any permission set that is still referenced by a code group at that policy level. You will first either need to delete the code group or code groups referencing the permission set or change the code group(s) to reference a different permission set. When removing a permission set, you may also be able to remove assemblies from the policy assemblies list that were only added to support the implementation of a custom permission type in the deleted permission set.

NOTE

See the "Removing an Assembly from the Policy Assemblies List" section later in this chapter for more information about removing entries from the Policy Assemblies list.

The following is the syntax to remove a permission set.

Syntax:

 [{-u[ser],-m[achine],-en[terprise]}] rempset  pset_name  

Abbreviation:

 -rp 

Example:

 Caspol user rempset Everything 

This command will remove the Everything permission set from the user policy list of known permission sets.

Adding an Assembly to the Policy Assembly List

The Policy Assembly list contains all the assemblies required to implement custom security objects of a policy level. For example, if a custom membership condition was used in the code group hierarchy of the user level policy, the user level Policy Assembly list must hold the assembly (and all assemblies it depends on) that implements the new membership condition. You do not need to add anything here if you are strictly using security policy types that ship with the .NET Framework.

Syntax:

 [{-u[ser],-m[achine],-en[terprise]}] addfulltrust  file  

Abbreviation:

 -af 

Example:

 Caspol machine af customperm.dll 

This Caspol line adds the customperm.dll assembly to the Policy Assembly list.

NOTE

The name of this Caspol switch contains fulltrust because all assemblies added to this list are fully trusted at that policy level. This is necessary for policy resolution not to result in circularity problems. Consequently, it is important that you always add all the assemblies required to implement a custom security object used at a policy level to that policy level's list of Policy Assemblies.

Removing an Assembly from the Policy Assemblies List

After a custom security object is no longer used at a policy level, you can remove all the assemblies required to implement this custom security object from the Policy Assembly list.

CAUTION

Be careful which assemblies you remove from this list. If you remove any assembly that another type currently used in the security policy depends on, you may bring the security system to a halt. This is a place were you should err on the side of caution. If in doubt, leave the assembly in the list.

Syntax:

 [{-u[ser],-m[achine],-en[terprise]}] remfulltrust  file  

Abbreviation:

 -rf 

Example:

 Caspol u rf MyCustomCodeGroup.dll 

NOTE

This example presumes that MyCustomCodeGroup.dll is in the path from which Capsol is running.

Showing the Permissions or Code Groups Applicable to an Assembly

Caspol has a couple options designed to help you analyze problems with policy settings or quickly find out whether a specific policy change works as intended. You can determine the permissions applicable to an assembly or the code groups applying to it.

Use the following command to determine the permissions an assembly would be granted from one or all policy levels:

Syntax:

 [{-u[ser],-m[achine],-en[terprise],-a[ll]}] resolveperm  file  

Abbreviation:

 -rsp 

Example:

 Caspol m resolveperm myassembly.exe 

Likewise, you can determine the code groups that an assembly receives from a specific or all policy levels:

Syntax:

 [{-u[ser],-m[achine],-en[terprise],-a[ll]}] resolvegroup  file  

Abbreviation:

 -rsg 

Example:

 Caspol en rsg MyAssembly.exe 

You should use both of these options (or the equivalent options in the .NET Framework Configuration tool) if the security policy does not seem to grant an assembly the level of trust you expected.

NOTE

Sometimes, an assembly may receive a sufficient level of trust to run as expected by policy as indicated by the “rsp and “rsg resolves, but still generate a security exception. This may be the case either because the assembly itself may be annotated to require a specific level of permissions that policy is not giving it. Alternatively, it may be annotated to refuse permissions to access a resource that it later indeed tries to access. The former can be helped administratively by increasing the permissions given to the assembly in question. The latter is a programming error administrators will not be able to do anything about. Use the permview tool to see what permissions an assembly requires or refuses (see the SDK for more detail). Alternatively, if problems persist, it could also be that the assembly in question depends on other assemblies to whom you haven't given the required level of trust.

Turning Off Security

It is possible to switch security completely off using the Caspol tool. This switch is only available if you have write access to the local machine's registry system (usually reserved for power users and machine administrators). You should never really need to use this switch, unless you must squeeze a few more milliseconds of performance out of the .NET Framework Common Language Runtime and run on an isolated, secure machine.

CAUTION

Again, this is probably the singlemost dangerous option of Caspol. All bets are off when you have turned security to off!

Syntax:

 security {on  off} 

Abbreviation:

 -s 

Example:

 Caspol s off 

Resetting Security Policy

The default security policy has been designed to represent a known safe state that is as permissive as possible without opening undue security holes. It has been designed to protect against mobile code abusing resources on your machine, so it consigns assemblies from the local intranet to execute within a tightly protected security context, while requiring you to explicitly add permissions for any assembly you wish to run off the Internet. In case you have made administrative changes to security policy that you have become unsure of, it may often be advisable to start over with the known safe default policy settings as opposed to trying to fix policy. To return to the default policy state, simply use the following Caspol option:

Syntax:

 [{-u[ser],-m[achine],-en[terprise],-a[ll]}] reset 

Abbreviation:

 -rs 

Example:

 Caspol all reset 

This example will return the security policy to its default policy state by resetting all policy levels.

Undoing the Latest Policy Change

Caspol creates a backup copy of the latest policy change you have made. In the case that you have mistyped some information or decided that the latest change was a mistake, you can easily revert to the policy state prior to the last Caspol command that changed security policy.

Syntax:

 -recover 

Abbreviation:

 -r 

Example:

 Caspol r 

Caspol's Self-Protection Mechanism and How to Override It

Because Caspol is itself a managed application, it is subject to the .NET Framework security policy system, just like any other assembly. It is possible to change the security policy to a state in which Caspol would not run anymore. Consequently, Caspol has a self-protection mechanism built in that will check whether a specific command would prevent the Caspol tool from running again. Prefacing your policy change with the following switch will force Caspol to accept the policy change despite the fact that it may not be able to run afterwards.

Syntax:

 -force 

Abbreviation:

 -f 

Example:

 Caspol f u cg All_Code Nothing 

This command will set the root code group of the user policy level to grant no permissions. Assuming user policy is in the default state, no assemblies ”including the Caspol tool ”will receive any permissions, because all policy levels are intersected. Without using the “force option, the previous command will not succeed on the default policy because the .NET Framework Configuration tool will recognize it could not run anymore. If you want the command to succeed anyway, you need to use “f[orce] .

NOTE

There are a few more Caspol options that have not been explained so far. All of these are of little interest for policy scripting. The “execution directive can be used to turn off the security system's assembly load time check whether an assembly is allowed to execute; if turned off, the check will take place the first time an assembly tries to access a protected resource. The “buildcache option will cause the security system to update its policy cache for potentially better performance, while the “customuser and “customall directives can be used to model policy changes. Use the /? option to get more help, or refer to the SDK documentation of this tool.

Caspol in Action ”Scripts, Hints, and Tricks

Caspol has most administrative features that the .NET Framework Configuration tool offers. By putting together the previously discussed individual Caspol commands, you can write an indefinite number of powerful scripts to change security to a new state, automating complex policy changes. The following are a few helpful hints you should consider:

• Use the policy level directives to explicitly state whether you want to make a change to the machine or user policy level. Relying on Caspol to default commands to the machine level when the user has sufficient access rights to policy is risky, because this may lead to accidental changes of user policy levels for users who do not have write access to the machine and enterprise policy levels.

• If you want the state of policy after your script to be in a fully known, predicted state, don't be afraid to do a policy reset first, giving you a known safe starting point for your script.

• Any code group changes or additions should be made using code group names and not their numeric labels. Numeric labels will get reordered as soon as a new code group is introduced or a code group gets deleted.

• Turn the policy change prompt off on your first script line unless you are absolutely certain that the machine running the script already had Caspol “pp off run on it.

• Don't remove any assemblies from the Policy Assemblies list unless you are absolutely certain they are not needed by any type used to implement the code group hierarchy or a permission set.

• Always give your newly introduced code groups a name if you expect to be scripting against them at a later point.

• Remember that removing a code group from the code group hierarchy will destroy the code group and all code groups beneath it.

• You should get in the habit of annotating your newly introduced code groups or permission sets with a description. This will make it easier to remember what you intended them to accomplish when you have to debug policy issues later.

• For importing a new permission set via Caspol, use the .NET Framework Configuration tool to build the new permission set and simply cut and paste the requisite XML from the policy file into a separate XML file.

• If you changed security policy so that neither Caspol or the GUI tool still run, just delete the policy configuration files to get back to a default policy state. See Chapter 18 for file location information.

• Don't turn off security if you have issues getting an assembly to run; do a more targeted policy update.

• Remember that a batch script is not transacted, so if any failures occur during script execution, you may end up with policy changed, but only partially to the state you intended.

• Use the GUI tool whenever you can because its graphical representation of the security system is more intuitive than dealing with a command-line representation of hierarchical code group arrangements.

• Be careful in the introduction of exclusive code groups. If more than one exclusive code group applies to an assembly, the policy system will throw an exception and the assembly will not be able to run.

• Test your scripts thoroughly before large scale deployment.

It's now time to pull together the various Caspol options previously introduced and present a few sample scripts.

The following script first turns off the policy change warning, and then resets all policy levels to their default state. After that, it restricts the permissions of all assemblies coming from the intranet:

 Caspol pp off Caspol all reset Caspol m ag LocalIntranet_Zone strong file myassembly.exe         noname -noversion FullTrust n MySNgroup Caspol m cg LocalIntranet_Zone Execution 

First, resetting policy is of interest if you need to fully guarantee the shape of policy after your script executed, excluding any previous customizations. A code group is added under the LocalIntranet_Zone code group giving all assemblies signed with the strong name on myassembly.exe full trust to access all protected resources. Finally, the permission set handed out by the LocalInteraet_Zone code group is reduced to the Execution permission set, just allowing assemblies to compute without any further access to resources. In essence, the previous script cranks down the permissions for all assemblies from the intranet with the exception of the assemblies signed by the myassembly.exe strong name. Those assemblies would be fully trusted.

The following is another example:

 Caspol pp off Caspol m ag LocalIntranet_Zone        url file:///\mymachine\* FullTrust n MyFullTrustShare Caspol m ag Internet_Zone site www.aw.com Nothing exclusive on n NoTrustToEvil 

This example gives a share on the intranet full trust to access protected resources, while enforcing that no assemblies coming from the www.aw.com should run.

 Caspol pp off Caspol en reset Caspol en ag All_Code pub        file mysignedfile.exe Internet levelfinal on n Trustcert Caspol en ag Trustcert strong file myfile.exe FullTrust n TrustCertandSN Caspol en ag Trustcert strong file my2ndfile.exe intranet n TrustCertandSN2 Caspol en ag All_Code zone intranet Nothing n IntranetZone Caspol en ag All_Code strong file Caspol.exe noname noversion FullTrustn Caspol Caspol en cg All_Code Nothing 

This sample deletes all changes that may have been made on the enterprise policy on the client machine. Policy is then set up to give FullTrust to all assemblies signed both with the authenticode signature found on mysignedfile.exe and the strong name found on myfile , while assemblies signed with the same authenticode signature but with the strong name on my2ndfile.exe receive only intranet permissions. Because the Trustcert code group is level final, no policy levels below the enterprise level will interfere with the permission grant from policy for all assemblies signed with that authenticode signature. Enterprise policy is further changed to not allow any assemblies from the intranet to run (except for the assemblies signed with the previously added signatures). To continue to make the Caspol tool function when called from the intranet, a code group based on Caspol's strong name is added, while the All_Code group is changed to give the Nothing permission set instead of the FullTrust permission set. It is important that this be the last step ”if you had begun your script with reducing the permissions granted by the All_Code group, further lines in the script may not have run, because at each invocation of Caspol on each separate script line, the security system checks anew whether Caspol has sufficient rights granted to it to run and access resources, such as the file system, when saving out policy changes.

for RuBoard