How to use the ASP.NET utility to encrypt credentials and session state connection strings

This step-by-step article describes how to use the Aspnet_setreg.exe utility to encrypt credentials and session state connection strings. Microsoft ASP.NET version 1.0 requires that you store plain text credentials in configuration files if you want to do any of the following:

• Change the ASP.NET worker process identity.
• Specify an impersonation identity.
• Specify a connection string for session state.

When you apply the hotfix that is described in Microsoft Knowledge Base article 329250 (see "References"), you can use encrypted data that is stored in the registry instead of plain text in the following configuration sections:

• <identity userName= password= />
• <processModel userName= password= />
• <sessionState stateConnectionString= sqlConnectionString= />

Introduction

Use the Aspnet_setreg.exe utility to encrypt and to store these attribute values in the registry under a secure key. Use the CryptProtectData function with the CRYPTPROTECT_LOCAL_MACHINE flag to encrypt the credentials. Because anyone with access to the computer can call CryptUnprotectData, the encrypted data is stored under a secure registry key with a strong discretionary access control list (DACL). When ASP.NET parses the configuration file, it reads the secure registry key and then uses CryptUnprotectData to decrypt the data.

Inetinfo.exe, which runs under the System identity, reads the <processModel /> section. To read the registry keys that store a user name and password for the ASP.NET worker process, the System account must have Read permission to these keys.

The ASP.NET worker process (Aspnet_wp.exe) reads the <identity /> and <sessionState /> sections. To read these registry keys, the worker process account must have Read permission to these keys. If content is hosted on a Universal Naming Convention (UNC) share, the account that is used to access the UNC share must have permission to read these keys.

By default, the registry keys that Aspnet_setreg.exe creates grant full control to the System, Administrator, and Creator Owner accounts. You can use Regedt32.exe to modify the DACL on the registry key. Make sure that arbitrary users cannot read the registry keys.

Restart IIS

For your changes to take effect, you must restart Microsoft Internet Information Services (IIS). By restarting IIS, you start a new ASP.NET worker process. To do this, click Start, click Run, type iisreset in the Open box, and then click OK.

Note If the server that you have reconfigured is a domain controller, you may have to restart the server.

Download and run Aspnet_setreg.exe

The following file is available for download from the Microsoft Download Center:

Download the Aspnet_setreq.exe package now. (http://download.microsoft.com/download/2/9/8/29829651-e0f0-412e-92d0-e79da46fd7a5/aspnet_setreg.exe)
Release Date: April 11, 2003

For more information about how to download Microsoft support files, click the following article number to view the article in the Microsoft Knowledge Base: Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help prevent any unauthorized changes to the file.

To display all the available command-line switches and their usage, run this tool from the command prompt without any command-line switches. If you saved this tool to C:\Tools\, run the following command from the command prompt to display all of its available switches and help for the switches:

Use encrypted attributes in the configuration file

Important This section, method, or task contains steps that tell you how to modify the registry. However, serious problems might occur if you modify the registry incorrectly. Therefore, make sure that you follow these steps carefully. For added protection, back up the registry before you modify it. Then, you can restore the registry if a problem occurs. For more information about how to back up and restore the registry, click the following article number to view the article in the Microsoft Knowledge Base:

Note This tool creates the registry keys under the HKEY_LOCAL_MACHINE subtree. By default, only administrators can create keys under this subtree. Make sure that you are logged on as an administrator to successfully create these registry keys.

1. Encrypt the userName and password attributes to be used with the <identity> section. (You can also do this for the other sections that are mentioned in this article). To do this, type the following command at the command line:
   c:\Tools>aspnet_setreg.exe -k:SOFTWARE\MY_SECURE_APP\identity -u:"yourdomainname\username" -p:"password"
   This command encrypts the userName and password attributes, creates registry keys at any location that you specify, and then stores the attributes in those registry keys. This command also generates output that specifies how to change your Web.config or Machine.config file so that ASP.NET will use these keys to read that information from the registry.
   
   After you execute this command, you receive output that is similar to the following:
   Please edit your configuration to contain the following:
   
   userName="registry:HKLM\SOFTWARE\MY_SECURE_APP\identity\ASPNET_SETREG,userName"
   password="registry:HKLM\SOFTWARE\MY_SECURE_APP\identity\ASPNET_SETREG,password"
   
   The DACL on the registry key grants Full Control to System, Administrators, and Creator Owner.
   
   If you have encrypted credentials for the <identity/> configuration section, or a connection
   string for the <sessionState/> configuration section, ensure that the process identity has
   Read access to the registry key. Furthermore, if you have configured IIS to access content on a
   UNC share, the account used to access the share will need Read access to the registry key.
   Regedt32.exe may be used to view/modify registry key permissions.
   
   You may rename the registry subkey and registry value in order to prevent discovery.
2. Modify the corresponding configuration file to point to these registry keys. If these values must be used in the <identity> section, the resulting <identity> section resembles the following.

   <identity impersonate="true"
   userName="registry:HKLM\SOFTWARE\MY_SECURE_APP\identity\ASPNET_SETREG,userName"
   password="registry:HKLM\SOFTWARE\MY_SECURE_APP\identity\ASPNET_SETREG,password" />
   					

3. Grant Read permissions to the Aspnet_wp.exe process account. For more information about how to change permissions for registry keys, see the "Use Regedt32.exe to grant permissions for the ASP.NET account on these registry keys" section.

Use Regedt32.exe to grant permissions for the ASP.NET account on these registry keys

Important This section, method, or task contains steps that tell you how to modify the registry. However, serious problems might occur if you modify the registry incorrectly. Therefore, make sure that you follow these steps carefully. For added protection, back up the registry before you modify it. Then, you can restore the registry if a problem occurs. For more information about how to back up and restore the registry, click the following article number to view the article in the Microsoft Knowledge Base:

1. Click Start, click Run, type regedt32 in the Open box, and then click OK.
2. Click the HKEY_LOCAL_MACHINE\SOFTWARE\MY_SECURE_APP\ subkey.
3. On the Security menu, click Permissions to open the Permissions dialog box.
   
   On Microsoft Windows XP or on Windows Server 2003, right-click the registry key, and then click Permissions.
4. Click Add. In the dialog box that opens, type yourservername\ASPNET(or yourservername\NetWork Service when using Windows Server 2003 (IIS 6.0)), and then click OK.
5. Make sure that the account that you just added has Read permissions, and then click OK.
6. Close Registry Editor.

For more information about a hotfix that lets you use the features that are described in this article, click the following article number to view the article in the Microsoft Knowledge Base: Note The fix that is described in article 329250 is only available for the .NET Framework 1.0.

For more information about the Microsoft Windows registry, click the following article number to view the article in the Microsoft Knowledge Base: For more information about ASP.NET, click the following article numbers to view the articles in the Microsoft Knowledge Base: Note The fix that is described in article 315158 is only available for the .NET Framework 1.0.