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.
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.
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.
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]
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>
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
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>
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>
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
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
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.
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.
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.
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.
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.
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.
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] ……
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>
Description: This option turns code access security on or off.
Note:This option should be used with extreme caution.
Description: This option turns on/off checking for "right to run" on code execution start-up.
Description: This option enables or disables the prompt that is displayed whenever caspol is called using an option that would cause policy changes.
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.
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.
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
Description: Displays the help screen
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 |
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.
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.