How To: Configure MachineKey in ASP.NET 2.0

How To: Configure MachineKey in ASP.NET 2.0

Summary

This How To explains the <machineKey> element in the Web.config file and shows how to configure the <machineKey> element to control tamper proofing and encryption of ViewState, forms authentication tickets, and role cookies. ViewState is signed and tamper proof by default. You can request encryption for pages that contain sensitive items in their ViewState by using the ViewStateEncryptionMode attribute. Forms authentication and role cookies are signed and encrypted by default. You do not need to modify the default settings unless your application is in a Web farm or if you need to share authentication tickets across applications. In these cases, you need to manually generate encryption and hashing keys.

Overview

The default ASP.NET settings ensure that forms authentication tickets are tamper proof and encrypted, and that ViewState is tamper proof. This ensures that any modification of the ViewState or authentication tickets either on the client's computer or over the network is detected when the server processes the data.

To provide tamper proof ViewState, a hashed message authentication code (HMAC) is generated from the ViewState content and the hash is compared on subsequent requests. The validation attribute of the <machineKey> indicates which hashing algorithm to use, and it defaults to SHA1, which uses the HMACSHA1 algorithm. Valid choices for hashing include SHA1 or MD5, although SHA1 is preferable because it produces a larger hash and is considered cryptographically stronger than MD5. The validationKey attribute of <machineKey> is used in conjunction with the ViewState content to produce the HMAC. If your application is installed in a Web farm, you need to change the validationKey from AutoGenerate,IsolateApps to a specific manually generated key value.

If you need to use round trips for potentially sensitive data, you can force encryption of ViewState for a specific page. To do this, set ViewStateEncryptionMode="Always" on the **@Page** directive for that page. Alternatively, you can use a control to request that the page's ViewState be encrypted by calling the Page.RegisterRequiresViewStateEncryption method. Using this method in conjunction with the default setting of ViewStateEncryptionMode="Auto" ensures that ViewState is only encrypted for those pages that need it.

To encrypt ViewState in a Web farm, you need to manually set the validationKey value. The encryption algorithm is determined by the validation attribute of the <machineKey>. The validation attribute defaults to SHA1, which provides tamper proofing but not encryption. To support ViewState encryption, you should set the validation attribute to AES, the recommended symmetric encryption algorithm.

Forms authentication tickets are tamper proof and encrypted by default. The decryption and decryptionKey attributes control the encryption. The validationKey controls the hashing. If your application is in a Web farm, you need to manually set the validationKey and decryptionKey. Also, if you need to share forms authentication tickets across applications in separate virtual directories, you need to manually set the keys to ensure that they match in each application's Web.config file.

If you use the Role Manage feature, and choose to cache roles, a roles cookie is created. The roles cookie is also signed and encrypted by default, using the same mechanisms as forms authentication tickets.

Machine Key Explained

The default settings for the <pages> and <machineKey> elements are defined in the machine-level web.config.comments file. The relevant default settings are shown here for reference.

<pages enableViewStateMac="true" viewStateEncryptionMode="Auto" ... />

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

When you configure ViewState, the <pages> element is used in conjunction with the <machineKey> element.

The <machineKey> attributes are as follows:

• validationKey. This specifies the key that the HMAC algorithm uses to make ViewState tamper proof. The ViewState MAC is checked at the server when either the enableViewStateMAC attribute of the <pages> element or the EnableViewStateMac attribute of the **@Page** directive is set to true.

  code复制

   

  <pages enableViewStateMAC="true" ... /> 
  or
  <%@Page EnableViewStateMac="true" ... %>
  

  Forms authentication also uses this key for signing the authentication ticket. Role manager and anonymous identification if enabled also uses this key for signing their cookies. If you use anonymous identification in cookieless mode, the data on the URL is also signed with this value,

• decryptionKey. This specifies the key used to encrypt and decrypt data. Forms authentication, role manager and anonymous identification features use this key to encrypt and decrypt the authentication ticket, roles cookie and anonymous identification cookie. ASP.NET uses the key to encrypt and decrypt ViewState, but only if the validation attribute is set to AES or 3DES.

• decryption. This specifies the symmetric encryption algorithm used to encrypt and decrypt forms authentication tickets.

• validation. This specifies the hashing algorithm used to generate HMACs to make ViewState and forms authentication tickets tamper proof. This attribute is also used to specify the encryption algorithm used for ViewState encryption. This attribute supports the following options:

  • SHA1–SHA1 is used to tamper proof ViewState and, if configured, the forms authentication ticket. When SHA1 is selected for the validation attribute, the algorithm used is HMACSHA1.
  • MD5–MD5 is used to tamper proof ViewState and, if configured, the forms authentication ticket.
  • AES–AES is used to encrypt ViewState with the key specified in the decryptionKey attribute.
  • 3DES–3DES is used to encrypt ViewState with the key specified in the decryptionKey attribute. This is the only way to encrypt ViewState in ASP.NET 1.1. Both the forms authentication ticket and the ViewState are tamper-proofed using SHA-1 and the key specified in the validationKey attribute. Because the validation attribute is overloaded in ASP.NET 1.1, ASP.NET 2.0 introduces a new decryption attribute.

In general, you should choose SHA1 over MD5 for tamper-proofing because this produces a larger hash than MD5 and is considered cryptographically stronger.

Forms authentication defaults to SHA1 for tamper proofing (if <forms protection="validation" or "All"). When <forms protection="All"> or <forms protection = "Encryption">, then forms authentication hashes the forms authentication ticket by using either MD5 or HMACSHA1 (HMACSHA1 is used even if validation is set to AES or 3DES). Forms authentication then encrypts the ticket using the algorithm specified in the decryption attribute. (The decryption attribute was introduced in ASP.NET 2.0.)

ViewState

You can protect ViewState in the following ways:

• Use an HMAC to make ViewState tamper proof.
• Use encryption to turn ViewState into unintelligible cipher text. This ensures that any sensitive data in ViewState cannot be viewed.

To enable hashing of ViewState, you must use one of the following configurations.

<pages enableViewStateMAC="true" ... /> 

Or

<%@Page EnableViewStateMac="true" ... %>

To enable encryption of ViewState, you must use one of the following configurations.

<pages viewStateEncryptionMode="Auto" ... />
<pages viewStateEncryptionMode="Always" ... />

or

<%@Page ViewStateEncryptionMode="Auto" ... %>
<%@Page ViewStateEncryptionMode="Always" ... %>

With viewStateEncryptionMode set to Auto, the page is only encrypted if a control has specifically asked for it by calling the Page.RegisterRequiresViewStateEncryption method to request encryption. If it set to Always, this forces encryption even if a control does not request it.

Note: Do not encrypt ViewState unless it contains sensitive data. To avoid the performance overhead of encryption, consider storing sensitive data on the server and not in ViewState.

Verifying that ViewState Is Tamper Proof

ViewState is tamper proof by default. ViewState tamper proofing is enabled by the enableViewStateMac attribute on the <pages> element and the validationKey and validation attributes on the <machineKey> element.

Note: You can see the default <machineKey> setting in the Machine.config.comments file.

To verify that tamper proofing is enabled for ViewState

1. Verify the enableViewStateMac attribute of the <pages> element is set to true, as shown in the following example.

   code复制

    

   <pages enableViewStateMac="true" ... />
   

   Note: You can override the machine's enableViewStateMac setting at the application or page level.

2. Verify that the validation attribute of the <machineKey> element is set to SHA1, as shown in the following example.

   code复制

    

   <machineKey ...  validation="SHA1" ... />
   

   The validation attribute specifies the hashing algorithm used to tamper proof ViewState. The default value is "SHA1", and you should use this rather than MD5 because it produces a larger hash than MD5 and is cryptographically stronger.

3. Review the validationKey setting of the <machineKey> element.

   code复制

    

   <machineKey validationKey="AutoGenerate,IsolateApps" ... />
   

   In the default settings shown above, the AutoGenerate setting instructs ASP.NET to generate a random key. The IsolateApps modifier causes ASP.NET to generate a unique key for each application on your server by using the application ID of each application.

   The default value is correct for a single server deployment. You do not need to change the default settings unless your application is deployed in a Web farm. In a Web farm, you must manually generate the validationKey value and make sure that it is the same on all servers in the farm. For more information, see the section, Web Farm Deployment Considerations in this document.

Configuring <machineKey> to Encrypt ViewState

By default, information in ViewState is encoded, but not encrypted. A user could decode and view the ViewState data.

To encrypt ViewState, either a control on a page needs to explicitly request ViewState encryption or the viewStateEncryptionMode attribute of the <pages> element must be set to Always. To request encryption, a control must call the RegisterRequiresViewStateEncryption method of the Page class.

The viewStateEncryptionMode attribute can take one of three possible attributes:

• Auto. This is the default setting, which means the ViewState on the page is only encrypted if a control has specifically asked for it.

  Note: If a control on the page requests encryption, then the entire ViewState is encrypted (not just the ViewState for the control).

• Always. This forces encryption even if a control does not ask for it.

• Never. This disables encryption even if a control does ask for it.

Ideally, you should not store sensitive data in ViewState and thereby avoid the need to encrypt it. If you do need to encrypt ViewState, then you need to specify the encryption algorithm to use on the validation attribute.

To encrypt ViewState

1. Check that the viewStateEncryptionMode attribute of the <pages> element is set to Always, as shown in the following example.

   code复制

    

   <pages ... viewStateEncryptionMode="Always" ... />
   

   If you do not want every page to used encrypted ViewState, check that the viewStateEncryptionMode attribute of the <pages> element is set to Auto, as shown in the following example.

   code复制

    

   <pages ... viewStateEncryptionMode="Auto" ... />   
   

   Then, from within your code, call the RegisterRequiresViewStateEncryption method as shown in the following example.

   code复制

    

   Page.RegisterRequiresViewStateEncryption();
   

2. Specify the encryption algorithm to use on the validation attribute, as shown in the following example.

   code复制

    

   <machineKey ... validation="AES" ... />
   

   The validation attribute is overloaded and can be used to specify either the hashing algorithm or the encryption algorithm. You can specify either 3DES or AES. (ASP.NET 2.0 introduces support for AES.) Because AES offers larger key sizes (128 bits, 192 bits, or 256 bits) than 3DES (56 bits), it is considered more secure and should be used.

3. Review the decryptionKey attribute of the <machineKey> element:

   code复制

    

   <machineKey decryptionKey="AutoGenerate,IsolateApps" ... />
   

   Unless your application is installed in a Web farm, you should leave the decryptionKey attribute with the default values shown in the example. In a Web farm, you must manually generate the decryptionKey value and ensure that the value is the same across all servers in the farm. For more information, see the section, Web Farm Deployment Considerations in this document.

For ViewState encryption, your <machineKey> configuration should resemble the following example

code复制

 

<machineKey 
    validationKey="AutoGenerate,IsolateApps"   
    decryptionKey="AutoGenerate,IsolateApps" 
    validation="AES" 
    decryption="Auto" />

Note: By default, ViewState is transmitted as a Base64 encoded string. Although at first glance it is unintelligible, Base64 encoding provides no security because it is easily decoded. If you need to ensure that ViewState contents remain confidential, you must use encryption.