13.4 Ensure the Runtime Grants Specific Permissions to Your Assembly

Problem

You need to ensure that the runtime grants your assembly those code access permissions that are critical to the successful operation of your application.

Solution

In your assembly, use permission requests to specify the code access permissions that your assembly must have. You declare permission requests using assembly-level code access permission attributes.

Discussion

The name permission request is a little misleading given that the runtime will never grant permissions to an assembly unless security policy dictates that the assembly should have those permissions. However, naming aside, permission requests serve an essential purpose, and although the way the runtime handles permission requests might initially seem strange , the nature of CAS doesn't allow for any obvious alternative.

Permission requests identify permissions that your code must have to function. For example, if you wrote a movie player that your customers could use to download and view movies from your Web server, it would be disastrous if the user 's security policy did not allow your player to open a network connection to your media server. Your player would load and run, but as soon as the user tried to connect to your server to play a movie, the application would crash with the exception System.Security.SecurityException . The solution to this problem is to include in your assembly a permission request for the code access permission required to open a network connection to your server ( System.Net.WebPermission or System.Net.SocketPermission , depending on the type of connection you need to open).

The runtime honors permission requests using the premise that it's better that your code never load, than load and fail sometime later when it tries to perform an action that it doesn't have permission to perform. Therefore, if after security policy resolution the runtime determines that the grant set of your assembly doesn't satisfy the assembly's permission requests, the runtime will fail to load the assembly and will instead throw the exception System.Security.Policy.PolicyException .

To declare a permission request, you must use the attribute counterpart of the code access permission that you need to request. All code access permissions have an attribute counterpart that you use to construct declarative security statementsincluding permission requests. For example, the attribute counterpart of SocketPermission is SocketPermissionAttribute , and the attribute counterpart of WebPermission is WebPermissionAttribute all permissions and their attribute counterparts follow the same naming convention and are members of the same namespace.

The following code shows a console application named PermissionRequestExample that includes two permission requests: one for SocketPermission and the other for SecurityPermission . It's important to remember the following:

You must declare the permission request after any top level using statements but before any namespace or type declarations.
The attribute must target the assembly and so you must prefix the attribute name with assembly: .
There is no need to include the Attribute portion of an attribute's namealthough you can if you want.
You must specify SecurityAction.RequestMinimum as the first positional argument of the attributethis value identifies the statement as a permission request.
You must configure the attribute to represent the code access permission you want to request using the attribute's properties. Refer to the .NET Framework SDK documentation for details of the properties implemented by each code access security attribute.
The permission request statements do not end with a semicolon (;).

To make more than one permission request, simply include multiple permission request statements as shown in the following example:

 using System.Net; using System.Security.Permissions; // Permission request for a SocketPermission that allows the code to open  // a TCP connection to the specified host and port.  [assembly:SocketPermission(SecurityAction.RequestMinimum,   Access = "Connect", Host = "www.fabrikam.com",   Port = "3538", Transport = "Tcp")]  // Permission request for the UnmanagedCode element of SecurityPermission,  // which controls the code's ability to execute unmanaged code.  [assembly:SecurityPermission(SecurityAction.RequestMinimum,   UnmanagedCode = true)]  public class PermissionRequestExample {     public static void Main() {            // Do something...     } }

If you try to execute the PermissionRequestExample application and your security policy doesn't grant the assembly the requested permissions, you will get the PolicyException shown here and the application won't execute. Using the default security policy, this will happen if you run the assembly from a network share because assemblies loaded from the Intranet zone are not granted SocketPermission .

 Unhandled Exception: System.Security.Policy.PolicyException: Required permission cannot be acquired.

When you try to load an assembly from within code (either automatically or manually), and the loaded assembly contains permission requests that security policy doesn't satisfy, the method you use to load the assembly will throw a PolicyException , which you must handle appropriately.