Updating Security Policy

Default security policy does not know about the existence of any custom permission. For example, the Everything named permission set contains all the built-in code access permissions that the runtime provides, but it does not include any custom permissions. To update security policy so that it knows about your custom permission, you must do three things:

• Make policy aware of your custom permission.

• Add the assembly to the list of trusted assemblies.

• Tell security policy what code should be granted to your custom permission.

Important

In the .NET Framework version 4, the common language runtime (CLR) is moving away from providing security policy for computers. Microsoft is recommending the use of Windows Software Restriction Policies as a replacement for CLR security policy. The information in this topic applies to the .NET Framework version 3.5 and earlier; it does not apply to the .NET Framework 4 and later. For more information about this and other changes, see Security Changes in the .NET Framework 4.

Making Policy Aware of Your Custom Permission

To make policy aware of your custom permission, you must:

• Create a new named-permission set that includes your custom permission. (You can modify an existing named-permission set instead of creating a new one.)

• Give the permission set a name.

• Tell security policy that the named-permission set exists.

For more information, see Code Access Security Policy Tool (Caspol.exe) or .NET Framework Configuration Tool (Mscorcfg.msc). You can add a new permission set in one of several ways. Using the Code Access Security Policy tool (Caspol.exe), you can create an .xml file that contains an XML representation of a custom permission set and then add this file to the security policy on the computer where the code is to run. Using the .NET Framework Configuration tool (Mscorcfg.msc), you can copy an existing permission set and add an XML representation of a permission to the new permission set.

To guarantee that your XML representation is valid and correctly represents your permission, you can generate it using code similar to the example that follows. Notice that this code creates a custom permission called MyCustomPermission, initialized to the unrestricted state. If your custom permission does not implement IUnrestrictedPermission, or if you do not want to set policy to grant your permission in an unrestricted state, use the constructor to initialize your permission to the state you want it to have.

Imports System
Imports System.IO
Imports System.Security
Imports System.Security.Permissions

Class PSetXML
   Public Shared Sub Main()
      Dim perm As New MyCustomPermission(PermissionState.Unrestricted)
      Dim pset As New NamedPermissionSet("MyPermissionSet", PermissionState.None)
      pset.Description = "Permission set containing my custom permission"
      pset.AddPermission(perm)
      Dim file As New StreamWriter("mypermissionset.xml")
      file.Write(pset.ToXml())
      file.Close()
   End Sub
End Class

using System;
using System.IO;
using System.Security;
using System.Security.Permissions;

class PSetXML {
   public static void Main() 
   {
   MyCustomPermission perm = 
    new MyCustomPermission(PermissionState.Unrestricted);
   NamedPermissionSet pset = 
    new NamedPermissionSet("MyPermissionSet", PermissionState.None);
   pset.Description = "Permission set containing my custom permission";
   pset.AddPermission(perm);
   StreamWriter file = new StreamWriter("mypermissionset.xml");
   file.Write(pset.ToXml());
   file.Close();
   }
}

After you have created the .xml file containing your permission set, you can add it to security policy. To use Caspol.exe, type the following on the command line:

caspol –machine –addpset mypermissionset.xml

When Caspol.exe asks whether you want to add the assembly containing your custom permission to the list of trusted assemblies, type yes.

To add the .xml file containing your permission set using the .NET Framework Configuration tool, select the Runtime Security Policy node and then select the policy level you want to modify. Right-click Permission Sets and select New. Use the wizard to add the permission set.

Adding the Assembly to the List of Trusted Assemblies

Because your custom permission will participate in the .NET Framework security system, it must be fully trusted (as any code that the security system relies on must be). You obtain full trust for your assembly by adding it to the list of trusted assemblies. After you have added your custom permission's assembly to the list using Caspol.exe (as described previously), you must also add any assemblies that your permission class references. To add additional assemblies to the list using Caspol.exe, type the following on the command line:

caspol -addfulltrust mypermissionset.dll

To view the list of fully trusted assemblies, use the following command:

caspol -listfulltrust

Because your custom permission's assembly (and any assemblies it references) will be fully trusted by the security system, it is important that those files be signed with a cryptographically strong name. Caspol.exe will not add an assembly to the full trust list if it does not have a strong name.

To add an assembly to the list of fully trusted assemblies using the .NET Framework Configuration tool, right-click the Runtime Security Policy node and select Trust Assembly. Use the wizard to trust the assembly.

Caution If the assembly implementing the custom security object references other assemblies, you must first add the referenced assemblies to the full trust assembly list. Custom security objects created using Visual Basic, Visual C++, or JScript, reference Microsoft.VisualBasic.dll, Microsoft.VisualC.dll, or Microsoft.JScript.dll, respectively. These assemblies are not in the full trust assembly list by default. You must add the appropriate assembly to the full trust list before you add a custom security object. Failure to do so will break the security system, causing all assemblies to fail to load. In this situation, the Caspol.exe -all -reset option will not repair security. To repair security, you must manually edit the security files to remove the custom security object.

Setting Policy to Grant Your Custom Permission

You must associate your new permission set with the appropriate code groups so that security policy will grant the custom permission to the code that should have it. You do this by modifying an existing code group or by adding a new code group that identifies the set of code that should be granted your custom permission. For more information about code groups, see Security Policy. Use the following Caspol.exe command to make mypermissionset the permission set granted to code that meets the membership condition of the LocalIntranet code group:

caspol -user -chggroup 1.2. mypermissionset

In this example, the label 1.2 represents the code group LocalIntranet. To display all the code groups and their associated labels, use the following command:

caspol -list

To view the list of permission sets, use the following command:

caspol -listpset

To make mypermissionset the permission set granted to members of the LocalIntranet code group using the .NET Framework Configuration tool, select the Runtime Security Policy node and then select the Machine policy. Right-click the LocalIntranet_Zone node and select Properties. Change the permission set using the Permission Set tab.

See Also

Reference

Caspol.exe (Code Access Security Policy Tool)

Mscorcfg.msc (.NET Framework Configuration Tool)

IUnrestrictedPermission

Concepts

Creating Your Own Code Access Permissions

.NET Framework Security Policy

Other Resources

Code Access Security