Microsoft Windows SharePoint Services and Code Access Security

發行項
03/25/2009

Maurice J. Prather
Suraj Poozhiyil
Andrew M. Miller
Microsoft Corporation

July 2003

Applies to:
    Microsoft® Windows® SharePoint™ Services
    Microsoft Office SharePoint Portal Server 2003
    Common Language Runtime

Summary: Learn how to implement policies for code access security for Microsoft SharePoint Products and Technologies and how to customize default security settings for Microsoft Windows SharePoint Services. This document also answers some of the most commonly asked questions about code access security and its applicability to Windows SharePoint Services. (11 printed pages)

Introduction
Default Security Permissions in Windows SharePoint Services
ASP.NET and SharePoint Security Policies
Setting the Trust Level for a Virtual Server
Frequently Asked Questions
Conclusion

Introduction

One of the key security enhancements of Microsoft® ASP.NET v1.1 is the ability for Web applications to operate in a partially trusted environment. For more information, see What's New in the .NET Framework v1.1. This is a change in behavior from ASP.NET v1.0 in which all Web applications were required to be fully trusted. With code access security enabled by ASP.NET v1.1, Windows SharePoint Services uses this feature to provide server administrators the flexibility to set execution permissions on assemblies tailored to their needs.

Developers creating Web Parts or custom solutions on the Windows SharePoint Services platform should familiarize themselves with its implementation of custom security permissions and policy files. The Windows SharePoint Services implementation allows developers the opportunity to customize their applications for partially trusted environments.

Default Security Permissions in Windows SharePoint Services

Windows SharePoint Services defines two security permissions by default as part of the Microsoft.SharePoint.Security namespace located in the Microsoft.SharePoint.Security.dll. Each permission contains one or more attributes as follows:

SharePointPermission. Controls rights to access resources used by Windows SharePoint Services.

Attribute	Description
ObjectModel	Set to TRUE to use the Microsoft.SharePoint object model
UnsafeSaveOnGet	Set to TRUE to save data on HTTP-GET requests
Unrestricted	Set to TRUE to enable all rights associated with this permission.

WebPartPermission. Controls rights to access Web Part resources

Attribute	Description
Connections	Set to TRUE to participate in Web Part to Web Part communications
Unrestricted	Set to TRUE to enable all rights associated with this permission.

ASP.NET and SharePoint Security Policies

You can specify a level of trust that corresponds to a predefined set of permissions for ASP.NET applications. By default, ASP.NET defines the following trust levels:

Full
High
Medium
Low
Minimal

With the exception of the Full trust level, all trust levels grant only partial trust to the application folder of a virtual server instance. For more information on the ASP.NET trust levels, see Code Access Security for ASP.NET.

Additionally, Windows SharePoint Services defines two trust levels of its own:

WSS_Minimal
WSS_Medium

The trust levels extend the Minimal and Medium trust levels of ASP.NET for Windows SharePoint Services. The trust levels are defined in security policy files, wss_minimaltrust.config and wss_mediumtrust.config. By default, Windows SharePoint Services stores these files in the following location:

local_drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\config

By default, when you extend a virtual server with Windows SharePoint Services, Windows SharePoint Services sets the trust level to WSS_Minimal. This helps provide a secure trust level in which assemblies operate with the smallest set of permissions required for code to execute.

The following table outlines the specific permissions granted with the custom security policy files included with Windows SharePoint Services.

Permission	WSS_Medium trust level	WSS_Minimal trust level
AspNetHostingPermission	Medium	Minimal
Environment	Read: TEMP, TMP, OS, USERNAME, COMPUTERNAME
FileIO	Read, Write, Append, PathDiscovery:Application Directory
IsolatedStorage	AssemblyIsolationByUser, Unrestricted UserQuota
Reflection
Registry
Security	Execution, Assertion, ControlPrincipal, ControlThread, RemotingConfiguration	Execution
Socket
WebPermission	Connect to origin host (if configured)
DNS	Unrestricted
Printing	Default printing
OleDBPermission
SqlClientPermission	AllowBlankPassword=false
EventLog
Message Queue
Service Controller
Performance Counters
Directory Service
SharePointPermission	ObjectModel = true
WebPartPermission	Connections = true	Connections = true

Note By default, Windows SharePoint Services does not grant access to the Microsoft SharePoint object model. To grant access, you must raise the associated trust level by one of several methods. The next section discusses these methods.

Setting the Trust Level for a Virtual Server

You can determine the trust level for a virtual server by the value of the level attribute of the <trust> tag in the web.config file. By default, Windows SharePoint Services sets the trust level to WSS_Minimal. In the web.config file of a virtual server extended with Windows SharePoint Services, you can find the following <trust>:

<trust level="WSS_Minimal" originUrl="" />

By default, you can use any one of the seven predefined trust levels outlined in the preceding section.

**Note **After changing the trust level of a virtual server, you must reset the Web service such as by using iisreset.

Specifying a trust level in the web.config file results in the following:

The trust level specified in the web.config file applies to all assemblies used by the specified virtual server.
All SharePoint sites associated with the specified virtual server apply the same trust level.

Frequently Asked Questions

The following is a list of questions that apply to code access security and Windows SharePoint Services.

What does partial trust mean the Web Part developer?

If you install assemblies into the BIN directory, you must ensure your code provides error handling in the event that required permissions are not available. Otherwise, unhandled security exceptions may cause your Web Part to fail and may affect page rendering on the page where the Web Part appears.

The following is a typical example of a security exception:

Request for the permission of type 
  Microsoft.SharePoint.Security.SharePointPermission, 
  Microsoft.SharePoint.Security, Version=11.0.0.0, Culture=neutral, 
  PublicKeyToken=71e9bce111e9429c failed

As stated previously, the WSS_Minimal trust level does not grant permission to the SharePointPermission.ObjectModel to assemblies in the BIN directory for an application. Therefore, if your code attempts to use the Microsoft SharePoint object model, the common language runtime (CLR) throws an exception.

Since the minimal permission set provides the smallest set of permissions required for code to execute, the likelihood of additional security exceptions is increased.

Recommendation Try-catch critical areas to address situations where you may not have the necessary permissions to accomplish a specified objective.

What if my assemblies are installed in the GAC?

By default, assemblies installed in the global assembly cache (GAC) run with Full trust. Although, installing your Web Part assembly in the GAC is a viable option, it is recommended that you install Web Part assemblies in the BIN directory for a more secure deployment.

How can I raise the trust level for assemblies installed in the BIN directory?

Windows SharePoint Services can use any of the following three options from ASP.NET and the CLR to provide assemblies installed in the BIN directory with sufficient permissions. The following table outlines the implications and requirements for each option.

Option	Pros	Cons
Increase the trust level for the entire virtual server. For more information, see "Setting the trust level for a virtual server"	Easy to implement. In a development environment, increasing the trust level allows you to test an assembly with increased permissions while allowing you to recompile assemblies directly into the BIN directory without resetting IIS.	This option is least secure. This option affects all assemblies used by the virtual server. There is no guarantee the destination server has the required trust level. Therefore, Web Parts may not work once installed on the destination server.
Create a custom policy file for your assemblies. For more information, see "How do I create a custom policy file?"	Recommended approach. This option is most secure. An assembly can operate with a unique policy that meets the minimum permission requirements for the assembly. By creating a custom security policy, you can ensure the destination server can run your Web Parts.	Requires the most configuration of all three options.
Install your assemblies in the GAC	Easy to implement. This grants Full trust to your assembly without affecting the trust level of assemblies installed in the BIN directory.	This option is less secure. Assemblies installed in the GAC are available to all virtual servers and applications on a server running Windows SharePoint Services. This could represent a potential security risk as it potentially grants a higher level of permission to your assembly across a larger scope than necessary In a development environment, you must reset IIS every time you recompile assemblies. Licensing issues may arise due to the global availability of your assembly.

Increase the trust level for the entire virtual server. For more information, see "Setting the trust level for a virtual server"

Easy to implement.

In a development environment, increasing the trust level allows you to test an assembly with increased permissions while allowing you to recompile assemblies directly into the BIN directory without resetting IIS.

This option is least secure.

This option affects all assemblies used by the virtual server.

There is no guarantee the destination server has the required trust level. Therefore, Web Parts may not work once installed on the destination server.

Create a custom policy file for your assemblies. For more information, see "How do I create a custom policy file?"

Recommended approach.

This option is most secure.

An assembly can operate with a unique policy that meets the minimum permission requirements for the assembly.

By creating a custom security policy, you can ensure the destination server can run your Web Parts.

Requires the most configuration of all three options.

Install your assemblies in the GAC

Easy to implement.

This grants Full trust to your assembly without affecting the trust level of assemblies installed in the BIN directory.

This option is less secure.

Assemblies installed in the GAC are available to all virtual servers and applications on a server running Windows SharePoint Services. This could represent a potential security risk as it potentially grants a higher level of permission to your assembly across a larger scope than necessary

In a development environment, you must reset IIS every time you recompile assemblies.

Licensing issues may arise due to the global availability of your assembly.

I changed the trust level in the web.config file—now my entire site fails to render. What should I do?

If you change the trust level in the web.config file, Windows SharePoint Services may fail to render on subsequent requests. The following is an example of a typical error:

Assembly <assemblyName> security permission grant set is incompatible 
  between appdomains.

To resolve the conflicting trust setting, reset Internet Information Services (IIS) such as by using iisreset.

**Note **This is a known issue related to the architecture of ASP.NET and the .NET Framework.

How do I create a custom policy file?

To customize one of the built-in policy files, it is recommended that you make a copy of it and make changes to the copy to ensure that you can reuse the original file if necessary.

The following procedure describes how to give access to the Microsoft SharePoint object model to a specific assembly.

To give access to an assembly

Copy the wss_minimaltrust.config file.
Rename the file new_file_name**.config**.
Using a text editor such as NotePad, open new_file_name**.config**

Under the <SecurityClasses> element, add a reference to the SharePointPermission class as follows:

<SecurityClasses>
  <!-- other security classes omitted for clarity -->
  <SecurityClass Name="SharePointPermission"
  Description="Microsoft.SharePoint.Security.SharePointPermission, 
  Microsoft.SharePoint.Security, Version=11.0.0.0, Culture=neutral, 
  PublicKeyToken=71e9bce111e9429c" /> 
</SecurityClasses>

Search for the <PermissionSet> tag where the name attribute equals ASP.Net.
Copy this entire tag and all of its children, and paste a copy of it immediately below the one you copied.

Change the name of the new PermissionSet element from ASP.Net to New_File_Name:

Example (Before)

<PermissionSet class="NamedPermissionSet" version="1" Name="ASP.Net">
<!-- <IPermission> nodes omitted for clarity -->
  </PermissionSet>

Example (After)

<PermissionSet class="NamedPermissionSet" version="1" 
  Name="New_File_Name">
<!-- <IPermission> nodes omitted for clarity -->
  </PermissionSet>

Add the following <IPermission> node to the<PermissionSet> element where the name attribute equals New_File_Name:

<IPermission class="SharePointPermission" 
             version="1" 
             ObjectModel="True" />

Therefore, the resulting customized <PermissionSet> will look as follows:

<PermissionSet class="NamedPermissionSet" version="1" Name=" 
  New_File_Name">
  <IPermission class="AspNetHostingPermission" version="1" 
    Level="Minimal" /> 
  <IPermission class="SecurityPermission" version="1" Flags="Execution" 
    /> 
  <IPermission class="WebPartPermission" version="1" Connections="True" 
    /> 
  <IPermission class="SharePointPermission" version="1" 
    ObjectModel="True" /> 
</PermissionSet>

Once you define the customized element, you must create a code group to specify when the CLR should apply the permission set.

**Important **By default, the AllCode code group is a FirstMatchCodeGroup in ASP.NET policy files. Therefore, the CLR stops assigning permissions to an assembly after the first match to a specific code group. To apply the custom permissions, you must declare the specific code group assigning the custom permissions to your assembly as the first code group within the AllCode group. This ensures that the CLR assigns the MyCustomPermissions permission set and stops without proceeding to the default $AppDirUrl$/* code group that is used to assign permissions based on whether the assembly is located in BIN directory.

In the following example, the membership condition for the new code group is based on strong name membership:
```

<CodeGroup class="UnionCodeGroup" 
           version="1" 
           PermissionSetName="MyCustomPermissions">
  <IMembershipCondition class="StrongNameMembershipCondition" 
                        version="1" 
                        PublicKeyBlob="... see note below ..." 
                        Name="MyAssemblyName" /> 
</CodeGroup>
```
**Note **To retrieve the public key blob for an assembly, use the secutil.exe tool as follows:
```
secutil.exe -hex -s MyAssemblyName.dll
```
For more information about secutil.exe, see Secutil Tool.
Save and close the file. The policy file is ready to use.
Open the web.config file for the virtual server extended with Windows SharePoint Services and add the following <trustLevel> tag to the SecurityPolicy element:
```
  <trustLevel name="MyCustomTrustLevel" 
              policyFile="new_file_name.config" /> 
```
In the web.config file, change the <trust> tag so that it refers to the newly defined trust level.
```
<trust level="MyCustomTrustLevel " originUrl="" />
```
Save and close the web.config file.
Reset IIS, such as by using iisreset, to apply the custom policy to the specified virtual server.

What if my assembly is not strongly named? How does my code group change?

You can specify membership conditions for a code group in several ways. You can use the UrlMembershipCondition to specify conditions as follows:

<CodeGroup class="UnionCodeGroup" 
           version="1" 
           PermissionSetName="MyCustomPermissions">
  <IMembershipCondition class="UrlMembershipCondition" 
                        version="1" 
                        Url="$AppDirUrl$/bin/MyAssemblyName.dll" />
</CodeGroup>

My assembly refers to a library assembly. Everything works when the assembly is installed in the GAC, but fails once the assembly is placed in the BIN directory. What is going on?

Assuming you granted the required permissions to an assembly, the reason your assembly cannot run may be related to how the library assembly was built. By default, strongly named assemblies allow only callers who are granted Full Trust. Therefore, the CLR blocks a partially trusted assembly from calling into a Full Trust-only assembly.

You have several possible solutions, both of which have security implications that you must consider:

When compiling the assembly, you can add the AllowPartiallyTrustedCallersAttribute attribute to the specified library assembly.

Important You can only add this attribute to the source code. If you are using a third-party assembly and do not have access to the source, you cannot choose this option. If you choose this option, you are allowing partially trusted callers to execute code from within the library. This could represent a potential security risk as it opens the specified library assembly for use by other callers with partial trust.
You can give your assembly Full trust by installing it to the GAC.

Important Assemblies installed in the GAC are available to all virtual servers and applications on the server running Windows SharePoint Services. This could represent a potential security risk as it potentially grants a higher level of permission to your assembly across a larger scope than necessary.
You can give your assembly Full trust by creating a custom policy file as outlined in the previous section.

Important It is recommended that you choose this option as it allows you to explicitly grant the required minimum level of permission to your assembly without increasing the scope of access to a larger number of callers.

I am trying to access a Web service by using a Web Part. When I do so, I get a Security Exception as follows:

Request for the permission of type System.Net.WebPermission, System, 
  Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 
  failed.

By default, assemblies in the BIN directory do not have the required permission, System.Net.WebPermission, to access Web services. To grant this permission, add the following to the corresponding IPermission element in the appropriate policy file:

<IPermission class="WebPermission" version="1">
  <ConnectAccess>
    <URI uri="...uri in the form of a regular expression..." />
  </ConnectAccess>
</IPermission>

I want to access a Web service from my Web Part. When I do so, I get an InvalidOperationException as follows:

One or more assemblies referenced by the XmlSerializer cannot be called 
  from partially trusted code.

When you create a reference to a Web service, Microsoft Visual Studio®.NET creates and places one or more objects in your assembly to store the argument data passed to the method(s) in the Web service. These objects are serialized using the XmlSerializer class when you invoke one or more of the methods in the Web service. By default, if your assembly is strongly named and resides in the BIN directory, callers with partial trust cannot access objects within that assembly. When you make the call to the Web service method, the XmlSerializer detects that there are partially trusted callers on the callstack (i.e. your assembly) and prevents the serialization from taking place even though the object resides in the same assembly.