Share via


machineKey Element (ASP.NET Settings Schema)

Configures keys to use for encryption and decryption of forms authentication cookie data and view-state data, and for verification of out-of-process session state identification.

configuration Element (General Settings Schema)
  system.web Element (ASP.NET Settings Schema)
    machineKey Element (ASP.NET Settings Schema)

<machineKey 
  validationKey="AutoGenerate,IsolateApps" [String]
  decryptionKey="AutoGenerate,IsolateApps" [String]
  validation=" " [SHA1 | MD5 | 3DES | AES]
  decryption="Auto" [Auto | DES | 3DES | AES]
/>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute

Description

decryption

Optional String attribute.

Specifies the type of hashing algorithm that is used for decrypting data.

This attribute can have one of the following values.

Value

Description

Auto

Specifies that ASP.NET determines which decryption algorithm to use, based on configuration settings. This is the default machineKey decryption value.

AES

Specifies that ASP.NET uses the AES (Rijndael) algorithm to decrypt data. AES is the default algorithm to decrypt data.

3DES

Specifies that ASP.NET uses the TripleDES algorithm to decrypt data. The TripleDES (3DES) algorithm uses three successive iterations of the DES algorithm.

DES

Specifies that ASP.NET uses the Data Encryption Standard (DES) algorithm to decrypt data.

Note

This attribute is new in the .NET Framework version 2.0.

decryptionKey

Required String attribute.

Specifies the key that is used to encrypt and decrypt data or the process by which the key is generated. This attribute is used for forms authentication encryption and decryption, and for view-state encryption when validation is set to the TripleDES field.

The IsolateApps modifier of the decryptionKey value indicates that ASP.NET generates a unique encrypted key for each application, using the application's ID. IsolateApps is included as part of the default value.

If you need to support configuration across a network of Web servers (a Web farm), set this attribute manually to ensure consistent configuration. For information about how to manually generate values for the validationKey and decryptionKey attributes, see How To: Configure MachineKey in ASP.NET 2.0.

This attribute can have one of the following values. The default is AutoGenerate,IsolateApps.

Value

Description

AutoGenerate, IsolateApps

The AutoGenerate modifier specifies that ASP.NET generates a random key and stores it in the Local Security Authority LSA. The IsolateApps modifier specifies that ASP.NET generates a unique encrypted key for each application using the application ID of each application. This is the default value.

value

Specifies a manually assigned key. This value must be manually set to a string of hexadecimal characters to guarantee consistent configuration across a Web farm. The key should be 16 hexadecimal characters in length when using DES encryption and 48 hexadecimal characters in length when using Triple DES (3DES) or AES encryption. If keys shorter than the maximum length are used, the keys should be created by a truly random means, such as by using the RNGCryptoServiceProvider class. ASP.NET can use Triple DES only on computers on which 128-bit encryption is available.

validation

Required MachineKeyValidation attribute.

Specifies the type of encryption that is used to validate data.

This attribute can have one of the following values. The default is SHA1.

Value

Description

AES

Specifies that ASP.NET uses the AES (Rijndael) algorithm to validate data.

MD5

Specifies that ASP.NET uses the Message Digest 5 (MD5) hash algorithm to validate data. This algorithm produces better performance than SHA1.

SHA1

Specifies that ASP.NET uses the SHA1 hash algorithm to validate data. Use this algorithm for increased security.

This is the default value.

3DES

Specifies that ASP.NET uses the TripleDES algorithm to validate data. The TripleDES algorithm uses three successive iterations of the DES algorithm.

validationKey

Required String attribute.

Specifies the key used to validate encrypted data. validationKey is used when enableViewStateMAC is true in order to create a message authentication code (MAC) to ensure that view state has not been tampered with. validationKey is also used to generate out-of-process, application-specific session IDs to ensure that session state variables are isolated between sessions.

The IsolateApps modifier of the validationKey value indicates that ASP.NET generates a unique encrypted key for each application, using the application's ID. IsolateApps is included as part of the default value.

If you must support configuration across a network of Web servers (a Web farm), set this attribute manually to ensure consistent configuration. For information about how to manually generate values for the validationKey and decryptionKey attributes, see How To: Configure MachineKey in ASP.NET 2.0.

This attribute can have one of the following values. The default is "AutoGenerate,IsolateApps".

Value

Description

AutoGenerate, IsolateApps

The AutoGenerate modifier specifies that ASP.NET generates a random key and stores it in the Local Security Authority (LSA). The IsolateApps modifier specifies that ASP.NET generates a unique encrypted key for each application using the application's ID. This is the default value.

value

Specifies a manually assigned key. This value must be set to a string of hexadecimal characters in order to guarantee consistent configuration across a Web farm.

The following tables lists the recommended length of the hexadecimal strings to use with each key type:

Value

Recommended Length

AES

64

SHA1

40

3DES

48

MD5

32

Important noteImportant Note:

MD5 is no longer recommended because it is not considered to be secure.

If keys shorter than the maximum length are used, the keys should be created by a truly random means, such as by using RNGCryptoServiceProvider class. ASP.NET can use Triple DES only on computers on which 128-bit encryption is available.

Child Elements

None.

Parent Elements

Element

Description

configuration

Specifies the required root element in every configuration file that is used by the common language runtime and in .NET Framework applications.

system.web

Specifies the root element for the ASP.NET configuration settings in a configuration file and contains configuration elements that configure ASP.NET Web applications and control how applications behave.

Remarks

The following code example demonstrates how to set both the validationKey and decryptionKey attributes to AutoGenerate. The isolateApps value is specified to generate unique keys for each application on the server.

<machineKey 
   validationKey="AutoGenerate,IsolateApps" 
   decryptionKey="AutoGenerate,IsolateApps" 
   validation="SHA1"
/>

Element Information

Configuration section handler

MachineKeySection

Configuration member

MachineKey

Configurable locations

Machine.config file

Root-level Web.config file

Application-level Web.config file

Requirements

Microsoft Internet Information Services (IIS) 5.0, 5.1, or 6.0

The .NET Framework version 1.0, 1.1, or 2.0

See Also

Tasks

Walkthrough: Encrypting Configuration Information Using Protected Configuration

How to: Configure Specific Directories Using Location Settings

How to: Lock ASP.NET Configuration Settings

Concepts

Securing Roles

Securing Membership

Securing Profile Properties

Securing Session State

ASP.NET Configuration File Hierarchy and Inheritance

Securing ASP.NET Configuration

ASP.NET Configuration Scenarios

Reference

system.web Element (ASP.NET Settings Schema)

configuration Element (General Settings Schema)

System.Configuration

System.Web.Configuration

MachineKeySection

MachineKey

Other Resources

General Configuration Settings (ASP.NET)

ASP.NET Configuration Settings

Administering ASP.NET Web Sites

ASP.NET Configuration API