MachineKeySection.CompatibilityMode Property

Definition

Namespace:

System.Web.Configuration

Assembly:

System.Web.dll

Gets or sets a value that specifies whether upgraded encryption methods for view state that were introduced after the .NET Framework version 2.0 Service Pack 1 release are used.

public:
 property System::Web::Configuration::MachineKeyCompatibilityMode CompatibilityMode { System::Web::Configuration::MachineKeyCompatibilityMode get(); void set(System::Web::Configuration::MachineKeyCompatibilityMode value); };

[System.Configuration.ConfigurationProperty("compatibilityMode", DefaultValue=System.Web.Configuration.MachineKeyCompatibilityMode.Framework20SP1)]
public System.Web.Configuration.MachineKeyCompatibilityMode CompatibilityMode { get; set; }

[<System.Configuration.ConfigurationProperty("compatibilityMode", DefaultValue=System.Web.Configuration.MachineKeyCompatibilityMode.Framework20SP1)>]
member this.CompatibilityMode : System.Web.Configuration.MachineKeyCompatibilityMode with get, set

Public Property CompatibilityMode As MachineKeyCompatibilityMode

Property Value

MachineKeyCompatibilityMode

A value that indicates whether encryption methods that were introduced after the .NET Framework 2.0 SP1 release are used.

Attributes

ConfigurationPropertyAttribute

Remarks

The upgraded encryption methods in later versions of the .NET Framework reduce the risk that an attacker can successfully reverse-engineer the DecryptionKey value. The older encryption methods are available in order to maintain backward compatibility.

All servers in a Web farm should have the CompatibilityMode property set to the same value. If the server that reads a forms authentication ticket has a different CompatibilityMode setting than the server that created the ticket, the ticket won't be recognized.

The following values can be specified for the CompatibilityMode property:

• Framework20SP1. This value specifies that ASP.NET uses encryption methods that were available in versions of ASP.NET earlier than 2.0 SP2. Use this value for all servers in a web farm if any server has a version of the .NET Framework earlier than 2.0 SP2. This is the default value unless the application Web.config file has the targetFramework attribute of the httpRuntime element set to "4.5".

• Framework20SP2. This value specifies that ASP.NET uses upgraded encryption methods that were introduced in the .NET Framework 2.0 SP2. Use this value for all servers in a web farm if all servers have the .NET Framework 2.0 SP2 or later but at least one does not have the .NET Framework 4.5.

• Framework45. Cryptographic enhancements for ASP.NET 4.5 are in effect. This is the default value if the application Web.config file has the targetFramework attribute of the httpRuntime element set to "4.5".

When this property is set to Framework45, the following restrictions are in effect:

• If the DataProtectorType property has a value, the ApplicationName property must also have a value. The DataProtector class mandates that a non-empty application name be provided.

• The Validation attribute must be an actual validation algorithm (for example, MD5, SHA1, HMACSHA256, HMACSHA384, HMACSHA512) or a custom algorithm that subclasses the KeyedHashAlgorithm type. The values AES and 3DES are forbidden.

• The framework will not produce signed-only payloads. Forms authentication tickets will always be both encrypted and signed, regardless of how the protection attribute of the forms element is set in the Web.config file. View state will always be both encrypted and signed if either EnableViewStateMac or RequireViewStateEncryption is set for a given page.

As a result of the security update that is described in Microsoft security bulletin MS10-070, the default encryption behavior is the same for the Framework20SP1 and Framework20SP2 settings. Changing the default behavior is not recommended, but if you want to do that, see How to configure legacy encryption mode in ASP.NET.