machineKey Element (ASP.NET Settings Schema)

Configures algorithms and keys to use for encryption, decryption, and validation of forms-authentication data and view-state data, and for 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="HMACSHA256" [SHA1 | MD5 | 3DES | AES | HMACSHA256 | 
    HMACSHA384 | HMACSHA512 | alg:algorithm_name]
  decryption="Auto" [Auto | DES | 3DES | AES | alg:algorithm_name]
/>

Attributes and Elements

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

Attributes

Attribute

Description

decryption

Optional String attribute.

Specifies the algorithm that is used for encrypting and decrypting forms-authentication data.

This attribute can have one of the following values:

  • Auto  Specifies that ASP.NET automatically determines which decryption algorithm to use. This is the default value of this attribute.

  • AES  Specifies that ASP.NET uses the AES (Rijndael) algorithm to encrypt and decrypt data. AES is the default algorithm and is the one that is used when the value of this attribute is Auto. This algorithm is compliant with the United States Federal Information Processing Standards (FIPS).

  • DES  Specifies that ASP.NET uses the Data Encryption Standard (DES) algorithm to encrypt and decrypt data. This algorithm is included only for legacy purposes and should only be used if compatibility with earlier versions of ASP.NET is required.

  • 3DES  Specifies that ASP.NET uses the TripleDES algorithm (3DES) to encrypt and decrypt data. This algorithm is included only for legacy purposes and should only be used if compatibility with earlier versions of ASP.NET is required.

  • alg:algorithm_name  Specifies that ASP.NET uses a custom algorithm to encrypt and decrypt data. The encryption algorithm must be defined in a class that derives from SymmetricAlgorithm. ASP.NET calls the SymmetricAlgorithm.Create method and passes in the name of the algorithm that is specified here.

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 and decryption when view state is encrypted.

This attribute can have one of the following values:

  • AutoGenerate, IsolateApps  Specifies that the key is automatically generated. This is the default value. 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.

  • key value  Specifies a manually assigned key. The decryptionKey value must be manually set to a string of hexadecimal characters to ensure consistent configuration across all servers in a Web farm. The key should be 64 bits (16 hexadecimal characters) long for DES encryption, or 192 bits (48 hexadecimal characters) long for 3DES. For AES, the key can be 128 bits (32 characters), 192 bits (48 characters), or 256 bits (64 characters) long. The longest key provides the most security.Random keys can be manually generated by using the RNGCryptoServiceProvider class. For more information, see How To: Configure MachineKey in ASP.NET 2.0.

For more information, see DecryptionKey.

validation

Required MachineKeyValidation attribute.

Specifies the hash algorithm that is used to validate data.

By default, view state is transmitted as a base-64 encoded string. Although at first glance encoded data is unintelligible, base-64 encoding provides no security because it is easily decoded. If you store sensitive data in view state, you can specify that ASP.NET encrypts view-state data in addition to validating it. You can specify view-state encryption for all pages of your Web application or for selected pages. For information about this option, see ViewStateEncryptionMode and RegisterRequiresViewStateEncryption().

If you want to use view-state encryption, set this attribute to AES. In that case, the value of decryptionKey will be used to encrypt view-state data, and ASP.NET will use the HMACSHA1 hash algorithm for data validation.

This attribute can have one of the following values.

  • AES  Specifies that ASP.NET uses the AES (Rijndael) encryption algorithm to encrypt and decrypt data when view state is encrypted. If this option is specified for the validation attribute, the HMACSHA1 algorithm is used for validation.

  • MD5  Specifies that ASP.NET uses the Message Digest 5 (MD5) hash algorithm to validate data. This algorithm is included only for legacy purposes and should only be used if compatibility with earlier versions of ASP.NET is required.

  • SHA1  Specifies that ASP.NET uses the HMACSHA1 hash algorithm to validate data. This algorithm should only be used if you need to set this attribute to AES to support view-state encryption. Otherwise, use HMACSHA256, HMACSHA384, or HMACSHA512.

  • 3DES  Specifies that ASP.NET uses the TripleDES (3DES) algorithm to encrypt and decrypt data when view state is encrypted. If this option is specified for the validation attribute, the HMACSHA1 algorithm is used for validation. This algorithm is included only for legacy purposes and should only be used if compatibility with earlier versions of ASP.NET is required.

  • HMACSHA256  Specifies that ASP.NET uses the HMACSHA256 hash algorithm to validate data. This is the default value. This algorithm is compliant with the United Stated Federal Information Processing Standards (FIPS).

  • HMACSHA384  Specifies that ASP.NET uses the HMACSHA384 hash algorithm to validate data. This option is available for applications that require stronger security than is provided by the HMACSHA256 algorithm. This algorithm is compliant with the United States Federal Information Processing Standards (FIPS).

  • HMACSHA512  Specifies that ASP.NET uses the HMACSHA512 hash algorithm to validate data. This option is available for applications that require stronger security than is provided by the HMACSHA384 algorithm. This algorithm is compliant with the United States Federal Information Processing Standards (FIPS).

  • alg:algorithm_name  Specifies that ASP.NET uses a custom algorithm. The prefix "alg:" is followed by the name of a class that derives from KeyedHashAlgorithm. ASP.NET calls the Create() method and passes in the name of the algorithm that is specified here.

validationKey

Required String attribute.

Specifies the key that is used to validate data, or the process by which it is generated. The validationKey value is also used to generate out-of-process, application-specific session IDs to ensure that session-state variables are isolated between sessions.

This attribute can have one of the following values:

  • AutoGenerate, IsolateApps  Specifies that the key is automatically generated. This is the default value. 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.

  • key value  Specifies a manually assigned key. The validationKey value must be manually set to a string of hexadecimal characters to ensure consistent configuration across all servers in a Web farm. The length of the key depends on the hash algorithm that is used:

    • AES requires a 256-bit key (64 hexadecimal characters).

    • MD5 requires a 128-bit key (32 hexadecimal characters).

    • SHA1 requires a 160-bit key (40 hexadecimal characters).

    • 3DES requires a 192-bit key (48 hexadecimal characters).

    • HMACSHA256 requires a 256-bit key (64 hexadecimal characters).

    • HMACSHA384 requires a 384-bit key (96 hexadecimal characters).

    • HMACSHA512 requires a 512-bit key (128 hexadecimal characters).

    Random keys can be manually generated by using the RNGCryptoServiceProvider class. For more information, see How To: Configure MachineKey in ASP.NET 2.0. This topic does not list the HMACSHA256, HMACSHA384, or HMACSHA512 algorithms. However, the process works for those algorithms also, as long as you specify the correct key length.

For more information, see ValidationKey.

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" 
/>

The following code example demonstrates how to set the validationKey attribute and the decryptionKey attribute to manually generated random values. The validationKey attribute is set to a 256-bit long key for the HMACSHA256 hash algorithm, and the decryptionKey attribute is also set to a 256-bit long key, the longest possible for the AES encryption algorithm. These are examples only and should not be used in your application.

<machineKey 
    validationKey="32E35872597989D14CC1D5D9F5B1E94238D0EE32CF10AA2D2059533DF6035F4F" 
    decryptionKey="B179091DBB2389B996A526DE8BCD7ACFDBCAB04EF1D085481C61496F693DF5F4" 
/>

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

Reference

system.web Element (ASP.NET Settings Schema)

configuration Element (General Settings Schema)

System.Configuration

System.Web.Configuration

MachineKeySection

MachineKey

Concepts

Forms Authentication Across Applications

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

Other Resources

General Configuration Settings (ASP.NET)

ASP.NET Configuration Settings

ASP.NET Web Site Administration

ASP.NET Configuration API