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!

Adding a code group to a code group hierarchy

Both the machine and user policy are expressed as a hierarchy of code groups. Every code group has a membership condition as well as a permission set associated with it. So when adding a code group to either the machine or user code group hierarchy both a membership condition as well as a named permission set must be defined. The label of the parent code group under which the new code group is to be added must also be defined. Optionally, it is also possible to set a couple of flags on the code group. Below is a summary of the syntax:

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

The parent label is the label of the parent code group to which the new code group should be attached. To find out what code group is identified by what label, simply do a –list or a –listgroups.

The pset_name simply refers to the named permission set that is to be associated with the new code group . Before a named permission set can be associated with a code group, it needs to be known at the policy level at which the code group should be inserted. For instance, if a MyPset permission set is to be associated with a new code group in the user policy, the MyPset permission set must have been added to the user policy previously. The only time when a permission set does not need to be added beforehand is if one of the standard (out-of-the-box) permission sets is used.

Mship stands for the membership condition for the new code group. A membership condition is basically what defines whether particular assemblies are or are not covered by a code group. For instance, a common code group is Zone, with value Internet. So code that has evidence certifying that the code has originated on the Internet will meet this membership condition. Below is the general syntax that mship can take in the –addgroup option:

Argument Description
-all All code group, all code applies to this code group
-pub { -cert file.crt |
-file file.exe | hex hexstring }
Software publisher denoted by certificate file, the signature on a file, or a hex string
-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: “Internet”, ”Intranet”, ”Trusted”, ”Untrusted”, “MyComputer”
-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.
-skipverification This membership condition tests whether code requests to skip verification.
-url urlname url of origin

Finally, it is also possible to set a couple of exclusive flags on the new code group. See explanation below:

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.

Common code group addition tasks

Below are examples and explanations for some of the most common code group addition tasks:

Adding a code group that targets code from the Internet

In order to make a code group applicable to code from the Internet, one simply uses the ‘–Zone’ option, with value ‘Internet’ as membership value. In the example below, the ‘Nothing’ permission set is associated with code from the Internet and inserted as a child code group to the root of the code group hierarchy.

Caspol –addgroup 1 –zone Internet Nothing

Adding a code group that targets code from the Intranet

The solution is similar to the one above. By using ‘-zone’ with value ‘Intranet’ one can generate a code group that targets code from the Intranet. In the example below a code from the Intranet is given the ‘Everything’ permission set.

Caspol –addgroup 1.1. –zone Intranet Everything

Adding a code group that only applies to a certain software publisher

Files from a software publisher need to be signed appropriately in order for this membership condition to work. The ‘–pub’ membership condition can be used to set a code group to apply only to a certain software publisher. The membership condition can either be constructed on the basis of an actual certificate file or a signed exe file. Suppose the certificate file for BuggySoft is handy (BuggySoft.cer) then the command below adds a code group in the machine policy with permission set ‘Nothing’ for code published by BuggySoft. The code group is added as a child code group of the root.

Caspol –machine –addgroup 1 –pub –cert buggysoft.cer Nothing

Adding a code group that applies to code from a particular web site

In order to add a code group that applies only to code from a particular web site one should use the ‘–site’ membership condition. It should be noted though that due to the possibility of DNS name spoofing this is not a safe way to ascertain the identity of a piece of code. Where possible one should use strong name or publisher membership conditions. Below is an example that gives code coming from the ‘www.Microsoft.com’ Intranet permissions.

Caspol –addgroup 1 –site www.microsoft.com Intranet

Adding a code group that overrides any other permissions granted at that policy level

For this purpose one simply sets the ‘–exclusive’ flag for the new code group. In the example below a code group is added that grants the ‘Everything’ permission set if the zone is Trusted, overriding any other permissions granted by any other code group.

Caspol –addgroup –zone Trusted Everything –exclusive On

Adding a specific code group both to the user and machine policy level

CASPol does not support a way in which an –addgroup commands adds a code group to the user and machine level at the same time. Each such addition has to be done separately, already since differing code group labels and conflict in the availability of certain permission sets may cause confusion.