Creating Encrypted Configuration Sections

If you need to protect sensitive information stored in a configuration file, you can encrypt the information. For example, you should always encrypt the connectionStrings section of a configuration file to prevent your database connection strings from being stolen by evil hackers.

You can encrypt just about any section in the web configuration file. You can encrypt any of the sections in the system.web section group with the sole exception of the processModel section. You also can encrypt a custom configuration section.

The .NET Framework uses the Provider Model for encrypting configuration sections. The Framework ships with two ProtectedConfigurationProviders: the RsaProtectedConfigurationProvider and the DpapiProtectedConfigurationProvider.

The RsaProtectedConfigurationProvider protect sensitive information stored in a configuration file, you can encrypt is the default provider. It uses the RSA algorithm to protect a configuration section. The RSA algorithm uses public key cryptography. It depends on the fact that no one has discovered an efficient method to factor large prime numbers.

The second provider, the DpapiProtectedConfigurationProvider, uses the Data Protection API (DPAPI) to encrypt a configuration section. The DPAPI is built into the Windows operating system (Microsoft Windows 2000 and later). It uses either Triple-DES or AES (the United States Governmentstandard encryption algorithm) to encrypt data.

The RsaProtectedConfigurationProvider is the default provider, and it is the one that you should almost always use. The advantage of the RsaProtectedConfigurationProvider is that this provider supports exporting and importing encryption keys. This means that you can move an application that contains an encrypted configuration file from one web server a new web server. For example, you can encrypt a configuration section on your development web server and deploy the application to a production server.

If you use the DpapiProtectedConfigurationProvider to encrypt a configuration section, on the other hand, then you cannot decrypt the configuration section on another web server. If you need to move the configuration file from one server to another, then you need to first decrypt the configuration file on the source server and re-encrypt the configuration file on the destination server.

Web Standards Note

The .NET Framework uses the World Wide Web Consortium (W3C) recommendation for encrypting XML files. This recommendation is located at http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/.

You can use encryption not only with configuration files, but also with other XML files. To learn more about encrypting XML files, look up the EncryptedXml class in the Microsoft .NET Framework 2.0 SDK Documentation.

Encrypting Sections with the aspnet_regiis tool

The easiest way to encrypt a section in the web configuration file is to use the aspnet_regiis command-line tool. This tool is located at the following path:

\WINDOWS\Microsoft.NET\Framework\[version]\aspnet_regiis.exe 

Note

You don't need to navigate to the Microsoft.NET directory to execute the aspnet_regiis tool if you open the SDK Command Prompt.

If you want to encrypt a particular section of a configuration file, then you can use the -pef option when executing the aspnet_regiis tool. For example, the following command encrypts the connectionStrings section of a configuration file located in a folder named MyWebApp:

aspnet_regiis -pef connectionStrings c:\Websites\MyWebApp 

If you prefer, rather than specify the location of a web application by its file system path, you can use its virtual path. The following command encrypts the connectionStrings section of a configuration file located in a virtual directory named /MyApp:

aspnet_regiis -pe connectionStrings -app /MyApp 

Notice that the -app option is used to specify the application's virtual path.

You can decrypt a configuration section by using the -pdf option. The following command decrypts a configuration file located in a folder named MyWebApp:

aspnet_regiis -pdf connectionStrings c:\Websites\MyWebApp 

You also can decrypt a configuration section by specifying a virtual directory. The following command uses the -pd option with the -app option:

aspnet_regiis -pd connectionStrings -app /MyApp 

When you encrypt a configuration section, you can specify the ProtectedConfigurationProvider to use to encrypt the section. The Machine.config file configures two providers: the RsaProtectedConfigurationProvider and the DataProtectionConfigurationProvider. The RsaProtectedConfigurationProvider is used by default.

If you execute the following command, then the connectionStrings section is encrypted with the DataProtectionConfigurationProvider:

aspnet_regiis -pe connectionStrings -app /MyApp -prov ProtectedConfigurationProvider 

Notice that this command includes a -prov option that enables you to specify the ProtectedConfigurationProvider.

Encrypting Sections Programmatically

Instead of using the aspnet_regiis tool to encrypt configuration sections, you can use the Configuration API. Specifically, you can encrypt a configuration section by calling the SectionInformation.ProtectSection() method.

For example, the ASP.NET page in Listing 26.26 displays all the sections contained in the system.web section group in a GridView control. You can click Protect to encrypt a section, and you can click UnProtect to decrypt a section (see Figure 26.14).

Figure 26.14. Encrypting and decrypting configuration sections.

Listing 26.26. EncryptConfig.aspx

[View full width]

<%@ Page Language="VB" %> <%@ Import Namespace="System.Web.Configuration" %> <%@ Import Namespace="System.Collections.Generic" %> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <script runat="server">     Private Sub Page_Load()         If Not Page.IsPostBack Then             BindSections()         End If     End Sub     Protected Sub grdSections_RowCommand(ByVal sender As Object, ByVal e As  GridViewCommandEventArgs)         Dim rowIndex As Integer = Int32.Parse(CType(e.CommandArgument, String))         Dim sectionName As String = CType(grdSections.DataKeys(rowIndex).Value, String)         If e.CommandName = "Protect" Then             ProtectSection(sectionName)         End If         If e.CommandName = "UnProtect" Then             UnProtectSection(sectionName)         End If         BindSections()     End Sub     Private Sub ProtectSection(ByVal sectionName As String)         Dim config As Configuration = WebConfigurationManager.OpenWebConfiguration(Request .ApplicationPath)         Dim section As ConfigurationSection = config.GetSection(sectionName)         section.SectionInformation.ProtectSection("RsaProtectedConfigurationProvider")         config.Save(ConfigurationSaveMode.Modified)     End Sub     Private Sub UnProtectSection(ByVal sectionName As String)         Dim config As Configuration = WebConfigurationManager.OpenWebConfiguration(Request .ApplicationPath)         Dim section As ConfigurationSection = config.GetSection(sectionName)         section.SectionInformation.UnprotectSection()         config.Save(ConfigurationSaveMode.Modified)     End Sub     Private Sub BindSections()         Dim config As Configuration = WebConfigurationManager.OpenWebConfiguration(Request .ApplicationPath)         Dim colSections As New List(Of SectionInformation)()         For Each section As ConfigurationSection In config.SectionGroups("system.web") .Sections             colSections.Add(section.SectionInformation)         Next         grdSections.DataSource = colSections         grdSections.DataBind()     End Sub </script> <html xmlns="http://www.w3.org/1999/xhtml" > <head  runat="server">     <title>Encrypt Config</title> </head> <body>     <form  runat="server">     <div>     <asp:GridView                  DataKeyNames="SectionName"         AutoGenerateColumns="false"         OnRowCommand="grdSections_RowCommand"         Runat="server" >         <Columns>         <asp:ButtonField ButtonType="Link" Text="Protect"           CommandName="Protect" />         <asp:ButtonField ButtonType="Link" Text="UnProtect"           CommandName="UnProtect" />         <asp:CheckBoxField DataField="IsProtected" HeaderText="Protected" />         <asp:BoundField DataField="SectionName" HeaderText="Section" />         </Columns>     </asp:GridView>     </div>     </form> </body> </html> 

When you click the Protect link, the grdSection_RowCommand() event handler executes and calls the ProtectSection() method. This method calls the SectionInformation.ProtectSection() method to encrypt the selected section. Notice that the name of a ProtectedConfigurationProvider is passed to the ProtectSection() method.

Warning

The page in Listing 26.26 saves the configuration file. By default, the ASPNET and NETWORK SERVICE accounts do not have permission to write to the file system. If you want the page in Listing 26.26 to execute within the security context of the user requesting the page, then you can enable per-request impersonation by adding the configuration file in Listing 26.16 to the root of your application.

Deploying Encrypted Web Configuration Files

If you need to copy an encrypted configuration file from one server to a new server, then you must copy the keys used to encrypt the configuration file to the new server. Otherwise, your application can't read encrypted sections of the configuration file on the new server.

Warning

You can't copy an encrypted configuration file from one server to another when you are using the DpapiProtectedConfigurationProvider. This section assumes that you are using the RsaProtectedConfigurationProvider.

By default, the RsaProtectedConfigurationProvider uses a public/private key pair stored in a key container named NetFrameworkConfigurationKey. This key container is located at the following path:

\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys 

If you want to deploy an application that contains an encrypted configuration file to a new server, then you must configure a new key container and import the key container to the new server. You must complete five configuration steps:

1.	Create a new key container.
2.	Configure your application to use the new key container.
3.	Export the keys from the origin server.
4.	Import the keys on the destination server.
5.	Grant access to the key container to your ASP.NET application.

You need to perform this sequence of configuration steps only once. After you have set up both servers to use the same encryption keys, you can copy ASP.NET applications back and forth between the two servers and read the encrypted configuration sections. Let's examine each of these steps one by one.

First, you need to create a new key container because the default key container, the NetFrameworkConfigurationKey key container, does not support exporting both the public and private encryption keys. Execute the following command from a command prompt:

aspnet_regiis -pc "SharedKeys" -exp 

This command creates a new key container named SharedKeys. The -exp option is used to make any keys added to the container exportable.

After you create the new key container, you must configure your application to use it. The web configuration file in Listing 26.27 configures the RsaProtectedConfigurationProvider to use the SharedKeys key container.

Listing 26.27. Web.config

<?xml version="1.0"?> <configuration>   <configProtectedData     defaultProvider="MyProtectedConfigurationProvider">     <providers>     <add       name="MyProtectedConfigurationProvider"       type="System.Configuration.RsaProtectedConfigurationProvider"       cspProviderName=""       useMachineContainer="true"       useOAEP="false"       keyContainerName="SharedKeys" />     </providers>   </configProtectedData>   <connectionStrings>     <add       name="Movies"       connectionString="Data Source=DataServer;Integrated Security=true;         Initial Catalog=MyDB" />  </connectionStrings> </configuration> 

Notice that the configuration file in Listing 26.27 includes a configProtectedData section. This section is used to configure a new ProtectedConfigurationProvider named MyProtectedConfigurationProvider. This provider includes a keyContainerName attribute that points to the SharedKeys key container.

The next step is to export the keys contained in the SharedKeys key container to an XML file. You can export the contents of the SharedKeys key container by executing the following command:

aspnet_regiis -px "SharedKeys" keys.xml -pri 

Executing this command creates a new XML file named keys.xml. The -pri option causes both the private and public keyand not only the public keyto be exported to the XML file.

Warning

The XML key file contains very secret information (the keys to the kingdom). After importing the XML file, you should immediately destroy the XML file (or stick the XML file on a CD and lock the CD away in a safe location).

After you create the keys.xml file on the origin server, you need to copy the file to the destination server and import the encryption keys. Execute the following command on the destination server to create a new key container and import the encryption keys:

aspnet_regiis -pi "SharedKeys" keys.xml 

The final step is to grant access to the key container to your ASP.NET application. By default, a page served from Internet Information Server executes within the security context of either the NETWORK SERVICE account (Windows 2003 Server) or the ASPNET account (other operating systems). You can grant access to the SharedKeys key container to the ASPNET account by executing the following command:

aspnet_regiis -pa "SharedKeys" "ASPNET" 

Executing this command modifies the ACLs for the SharedKeys key container so that the ASPNET account has access to the encryption keys.

After you complete this final step, you can transfer ASP.NET applications with encrypted configuration files back and forth between the two servers. An application on one server can read configuration files that were encrypted on the other server.

Note

As an alternative to using the aspnet_regiis tool, you can transfer encryption keys with the help of the RsaProtectedConfigurationProvider class. The RsaProtectedConfigurationProvider class contains methods for exporting and importing keys to and from XML files programmatically.