NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Code Access Security Policy Utility (caspol.exe)

Summary of the security model as exposed through caspol

Security policy is designed as a hierarchical structure of code groups. Each code group has a membership condition that determines membership of some code to that code group. Also, associated with each code group is a named permission set that specifies the permissions the runtime allows code satisfying the membership condition to have. A code group hierarchy, along with its associated named permission sets, is used to define and maintain each level of security policy.

There are three policy levels: machine policy, user policy, and application domain policy. The set of permissions that an assembly receives is determined by the intersection of the permission sets allowed by these three policy levels. Unlike machine policy and user policy, application domain policy is optional and it is dynamically created. Because application domain policy is not stored statically, it cannot be modified directly by caspol.

For more information about security policy and how the runtime determines which permissions to grant to code, see Security Policy Management.

Referencing security objects

To facilitate references to code groups in a hierarchy, the command line -list function will show indented objects with labels (1, 1.1, 1.1.1, etc.) for reference purposes. Subsequent command line operations targeting code groups use these labels to refer to specific code groups.

Named permission sets are referenced by their name. The –list option will show the list of code groups followed by a list of named permission sets available in that policy.

Caspol users can switch between the user and machine policies using the –machine and –user options.

Default Behavior

By default all options of caspol refer to the runtime version caspol has been installed with.

If a user without admin rights calls caspol, by default all caspol options refer to the user level policy, unless –machine is used.

If an admin calls caspol, by default all caspol options refer to the machine’s policy, unless the admin uses –user.

Syntax

caspol
   [-machine]
   [-user]
   [-all]
   [-list] 
   [-listgroups]
   [-listpset]
   [-addgroup parent_label mship pset_name ([-exclusive {on|off}][-
         levelfinal {on|off}])]
   [-chggroup label {mship | pset_name |[[ -exclusive{on|off}]| [-
   levelfinal {on|off}]]}] 
   [-remgroup label] 
   [-addpset { named_psfile | psfile pset_name} ]
   [-chgpset psfile pset_name]
   [-rempset pset_name] 
   [-resolvegroup [-all] assembly_file]
   [-resolvegroup [-user] assembly_file]
   [-resolvegroup [-machine] assembly_file]
   [-resolveperm [-all] assembly_file]
   [-resolveperm [-user] assembly_file]
   [-resolveperm [-machine] assembly_file]
   [-security { on | off }] 
   [-execution { on | off }] 
   [-polchgprompt { on | off }] 
   [-recover]
   [-reset]
   [-force]
   [-help]

Argument: -list

Description: Lists code groups and permission sets. The code group hierarchy and permission sets of machine policy, user policy, or all policy levels are shown. The general output format is:

Microsoft (R) COM+ CasPol [version]  - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is [ON|OFF]
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = [Machine|User]
Code Groups:
1.  [(PickFirst)] MemberShipConditionName [– Value] : PermSetName 
1.1  [(PickFirst)] MemberShipConditionName [– Value] : PermSetName 
1.2  ……
1.2.1  …..
Named Permission Sets:
1. Permission Set:Pset_name,(Description)
<Pset Xml>
2. Permission Set:Pset name,(Description)
<Pset Xml>
…

Example:

Caspol –list
Microsoft (R) COM+ CASPol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is ON
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = Machine
Code Groups:
1  All Code : Nothing
   1.1  Zone Internet: Internet
   1.2  Zone Intranet: Intranet_permission_set
        1.2.1  Site “www.microsoft.com” : Internet
Named Permission Sets:
1. Permission Set:Nothing,(grants no permissions)
<PermissionSet ….>
…
</PermissionSet>
2. Permission Set:Internet, (Permissions suitable for apps from the internet)
<PermissionSet….>
…
</PermissionSet>

Argument:-listgroups

Description: This option lists the code groups of one policy level or all policy levels.

Example:

Caspol –listgroups
Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is ON
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = Machine
Code Groups:
1  All Code : Nothing
   1.1  Zone Internet: Internet
   1.2  Zone Intranet: Intranet_permission_set
        1.2.1  Site “www.microsoft.com” : Internet

Argument: -listpset

Description: This option lists the permission set of one policy level or all policy levels.

Example:

Caspol –listpset
Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is ON
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = Machine
Named Permission Sets:
1. Permission Set:Nothing,(grants no permissions)
<PermissionSet ….>
…
</PermissionSet>
2. Permission Set:Internet, (Permissions suitable for apps from the internet)
<PermissionSet….>
…
</PermissionSet>

Argument: -machine

Description: This option forces all options following it to apply to the machine policy. Note: Users that are not administrators do not have sufficient rights to modify the machine policy, although they may view it. -machine is the default for administrators.

Example:

Caspol –machine –list
Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Security is ON
Execution Checking is [ON|OFF]
Policy Change Prompt is [ON|OFF]
Level = Machine
Code Groups
1. All Code : Execution
Permission Set:Execution,(grants execution permission to code)
<PermissionSet ….>
…
</PermissionSet>

Argument: -user

Description: This option forces all options that follow it to apply to the user policy of the user on whose behalf caspol is running. -user is the default for non-admin users of caspol.

Example:

Caspol –user –list

Argument: -all

Description: This option forces all options that follow it to apply to the machine and user policies. This option can be applied to only the -list, -listpset, -listgroups, -resolvegroups, and -resolveperm options.

Example:

Caspol -all -list

Argument: -addgroup parent_label mship pset_name [-exclusive {on|off}][-levelfinal {on|off}]

Description: This option is used to add a new code group to the code group hierarchy. Parent_label designates the label (viz. 1. or 1.1.) of the code group from which the new code group should hang as child code group. Mship defines the membership condition for the new code group (see table below). pset_name is the name of the permission set that is to be associated with the new code group. It is also possible to set a couple of exclusive flags (see below).

mship is defined in terms of one of the following options:

Argument Description
-all All Code group; all code is a member of this code group.
-pub { -cert cert_file_name |
-file signed_file_name | -hex hex_string }
Software publisher denoted by certificate file, the signature on a file.
-strong {-file file_name} {name | -noname}

{version | -noversion}

Strong name as designated by a file, name and version.
-zone zonename Zone of origin of code. Zonename can be one of the following values: "MyComputer", "Intranet", "Trusted", "Internet", or "Untrusted".
-site website Site of origin.
-hash hashAlg {-hex hashValue | -file assembly_file } An assembly’s hash can be used as a code group membership condition. Either the hash value or the assembly file needs to be specified.
-appdir If –appdir is specified as membership condition the URL evidence of code is compared with the AppDir evidence of that code. If both evidence values are the same, this membership condition succeeds.
-skipverif This membership condition tests whether code requests to skip verification.
-urlURL url of origin

When adding a new code group, it is also possible to set a couple of exclusive flags:

Argument Description
-exclusive {on|off} When this flag is set only the permission set of the added code group applies when some code fits the membership condition of the added code group.
-levelfinal {on|off} When this flag is set (typically at the machine policy level) then no policy level below the level in which the added code group occurs is considered. For instance if this flag is set for some code group at the machine level and some code matches this code group’s membership condition, then the user level policy for this code is not calculated and applied.

Example:

Caspol  -machine –addgroup 1.  –zone Internet Execution

This command adds a child code group to the root of the machine policy code group hierarchy. The new code group has a zone membership with value Internet, and has the Execution Permission set associated with it.

Argument: -chggroup parent_label {mship |pset_name | [-exclusive {on|off}][-levelfinal {on|off}] }

Description: This option is used to change a code group’s membership condition, permission set or exclusive flags. Mship, pset_name, -exclusive and –levelfinal have the same purpose and syntax as defined for –addgroup.

Example:

Caspol –user –chggroup 1.2. Execution

The above command changes the permission set of the user policy code group with label 1.2. to the “Execution” permission set.

Caspol –chggroup 1.2.1. –zone Internet –exclusive on

This command changes the zone and group exclusive flag of the code group with label 1.2.1. at the default policy level (see Default Behavior). Zone is set to Internet and the –exclusive flag is switched on.

Argument: -remgroup label

Description: This option is used to remove code groups and their child code groups. If a code group at label has child code groups, all these child code groups will be removed as well.

Example:

Caspol –remgroup 1.1.

This removes the code group at 1.1. If this code group had any child code groups then those are deleted as well.

Argument: -addpset {named_psfile | psfile pset_name}

Description: This option is used to add a new named permission set The permission set needs to be pre-authored in XML and stored in an xml file. If the permission set name is not specified in the specified xml file, the permission set name needs to be explicitly specified in pset_name. If the name of the permission set is already contained in the xml file, pset_name does not need to be specified, but only named_psfile, which contains the permission set along with the permission set name.

Example:

Caspol  -user –addpset Mypset.xml Mypset

Adds the Mypset permission set to the user policy.

Argument:-chgpset psfile pset_name

Description: Changes a named permission set, the permission set will henceforth be defined in terms of the content of psfile. The psfile is a serialized permission set file in XML format.

Example:

Caspol –chgpset Mypset newpset.xml

Changes the permission set with name Mypset to the permission set contained in newpset.xml. Note that the current release does not support changing permission sets that are in use by the code group hierarchy.

Argument:-rempset pset_name

Description: The permission set with name pset_name is removed from a policy. As defined in the Default Behavior section, if no –user or –machine option is used then this option refers to the default policy level (user policy for non-admin users and machine policy for administrators).

Note: the permission set is only removed if it is not associated with any code group. Default permission sets cannot be removed.

Example:

Caspol –user –rempset Execution

Removes the permission set with name Execution from the user policy.

Caspol –rempset MyPset

Removes Mypset from the default policy level.

Argument: [-all | -machine | -user] -resolvegroup assembly_file

Description: With this option it is possible to discover which code groups a specific assembly (assembly_file) belongs to. By default this option applies only to one policy level. If all code groups of both the machine and user policy that the assembly belongs to should be shown, the –all option is used.

Example:

Caspol –machine –resolvegroup myassembly

This command shows all code groups of the machine policy that myassembly belongs to.

In general the output format for this option is:

Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Level = Machine
Code Groups:
1. MemberShipConditionName [– Value] : PermSetName [Intersection Merge]
1.1 MemberShipCondName [– Value] : PermSetName [Intersection Merge]
……

Argument: [-all | machine | user] -resolveperm assembly_file

Description: With this option it is possible to discover all the effective permissions that an assembly would be granted were it to run. By default this option only applies to one (the default) policy level. The –all option is used to indicate that the permissions applying to assembly_file should be calculated based both on the user and machine policy.

Example:

Caspol –all resolveperm testassembly 

The effective permissions for testassembly are calculated based on the machine and user policy.

The general output format for this option is:

Microsoft (R) COM+ Caspol [version] - the policy manipulation tool
Copyright (c) Microsoft Corp 1999-1999. All rights reserved.
Resolving Permissions for Level = Machine
Grant=
<PermissionSet>
XML for individual permissions
</PermissionSet>

Argument: -security { on | off }

Description: This option turns code access security on or off.

Note:This option should be used with extreme caution.

Argument:-execution { on | off }

Description: This option turns on/off checking for "right to run" on code execution start-up.

Argument:-polchgprompt { on | off }

Description: This option enables or disables the prompt that is displayed whenever caspol is called using an option that would cause policy changes.

Argument:-recover

Description: Whenever a policy change is made, caspol stores the old policy in a backup file. If the policy from the backup file should be recovered, use –recover

Example:

Caspol –machine –recover

Recovers the most recently saved machine policy.

Argument:-reset

Description: This option turns a policy back to its default state. This is useful whenever a changed policy seems beyond repair and it is easier to start with the installation defaults. This option will also automatically persist the default policy to disk. (see Manually Editing the Security Configuration below.)

Example:

Caspol –user –reset

Resets the user policy to the installation default.

Argument:-force

Description: Caspol checks whether any policy changes would result in granting caspol itself insufficient permissions to run properly. If that is the case, the policy change is not saved and an error message is printed. If the caspol user wants to force caspol to admit policy changes even if that means that caspol may not run anymore, the –force option can be used. This option surpresses the “self-destruct” test and commits the policy change as dictated by the caspol user.

Example:

Caspol –force –user –chggroup 1 Nothing

Argument:-help

Description: Displays the help screen

Abbreviations

Most options have one to three character abbreviations that can be used in place of the full-length option name. Below is a table of valid abbreviations:

Option Valid abbreviation
-all -a
-machine -m
-user -u
-list -l
-listgroups -lg
-listpset -lp
-addpset -ap
-chgpset -cp
-rempset -rp
-remgroup -rg
-chggroup -cg
-addgroup -ag
-resolvegroup -rsg
-resolveperm -rsp
-security -s
-execution -e
-help -h (or -? or /?)
-polchgprompt -pp
-recover -r
-reset -rs
-force -f

Caspol’s self protection

The caspol utility needs policy to grant itself the equivalent of the Everything permission set in order to function. There is built-in protection to prevent the creation of policy that fails to give it the necessary permissions – if this happens caspol will notify the user that the requested policy change will break caspol. Such policy changes will be rejected unless –force is used.

Manually editing the security configuration files

We do not recommend editing the security configuration files manually. However, there may be scenarios in which this might become necessary (such as when an administrator wants to edit the security configuration for a particular user – this capability will become part of a not yet implemented security administrative tool).

Corresponding to the two policy levels supported by caspol, there are two security configuration files - one for the machine policy and one for a particular user’s policy.

The machine policy resides at :

Machine policy configuration
Windows 2000 %WINDIR%\complus\vxx.xx\security.cfg
Windows NT %WINDIR%\complus\vxx.xx\security.cfg
Windows 9x %WINDIR%\complus\vxx.xx\security.cfg
User policy configuration
Windows 2000 %USERPROFILE%\complus\vxx.xx\security.cfg
Windows NT %USERPROFILE%\complus\vxx.xx\security.cfg
Windows 9x %WINDIR%\username\complus\vxx.xx\security.cfg

These files are only created on disk when the caspol user changes the machine or user policy using caspol (otherwise the hardwired defaults are used). If the default security policy should be written to disk nevertheless then simply call –reset, which automatically persists the default policy to disk. This might be convenient when the default policy is used as a starting point for further hand–edits to the security policy.

See Also

Security Policy Management