Importing and Exporting Protected Configuration RSA Key Containers

Protected configuration provides the capability to create, delete, export, and import RSA key containers when using the RsaProtectedConfigurationProvider. One scenario where this is useful is in a Web farm where the same encrypted Web.config file will be deployed to several servers. In that case, the same RSA key container must also be deployed to those servers. To accomplish this, you would create an RSA key container for the application, export it to an XML file, and import it on each server that needs to decrypt the encrypted Web.config file.

Creating RSA key containers can also be useful on a single Web server that hosts multiple ASP.NET applications. By creating an RSA key container for each application or for each set of applications for a single customer, you can improve the security of an application's sensitive configuration information by ensuring that the Web.config file for one application cannot be decrypted using the RSA key container from another application.

Creating an RSA Key Container

To create an RSA key container, you use the ASP.NET IIS registration tool (Aspnet_regiis.exe) with the –pc switch. You must give the key container a name, which identifies the key container used by the RsaProtectedConfigurationProvider specified in the configProtectedData section of your application's Web.config file. To ensure that your newly created RSA key container can be exported, you must include the -exp option.

For example, the following command creates an RSA key container named SampleKeys that is a machine-level key container and is exportable.

aspnet_regiis -pc "SampleKeys"–exp

The following example shows the configProtectedData section of a Web.config file. The section specifies an RsaProtectedConfigurationProvider that uses a machine-level RSA key container named SampleKeys.

<configProtectedData>
   <providers>
      <add name="SampleProvider" 
           type="System.Configuration.RsaProtectedConfigurationProvider, System.Configuration, Version=2.0.0.0,
                 Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a
                 processorArchitecture=MSIL"
           keyContainerName="SampleKeys" 
           useMachineContainer="true" />
   </providers>
</configProtectedData>

Note
To guard against encryption and decryption keys for protected configuration sections being unintentionally deleted, RSA key containers are not deleted if the .NET Framework is uninstalled.

Granting Authority to Access an RSA Key Container

By default, RSA key containers are tightly protected by NTFS access control lists (ACLs) on the server where they are installed. This improves the security of the encrypted information by restricting who can access the encryption key.

Before ASP.NET can use an RSA key container, the process identity of your ASP.NET application must be authorized to have read access to that RSA key container. For information on setting and determining the identity of your ASP.NET application, see ASP.NET Impersonation.

You can use the Aspnet_regiis.exe tool with the -pa switch to give the identity of your ASP.NET application permission to read an RSA key container. For example, the following command grants the Windows Server 2003 NETWORK SERVICE account access to read the machine-level RSA key container named SampleKeys:

aspnet_regiis -pa "SampleKeys" "NT AUTHORITY\NETWORK SERVICE"

Note
If the RSA key container is a user-level container, you must be logged on as the user in whose Windows profile the key is stored, and you must include the -pku option to grant access to the user-level RSA key container. For more information, see Understanding Machine-Level and User-Level RSA Key Containers.

To use the default RsaProtectedConfigurationProvider specified in the machine configuration, you must first grant the application's Windows identity access to the machine key container named NetFrameworkConfigurationKey, which is the key container specified for the default provider. For example, the following command grants the NETWORK SERVICE account access to the RSA key container used by the default RsaProtectedConfigurationProvider:

aspnet_regiis -pa "NetFrameworkConfigurationKey" "NT AUTHORITY\NETWORK SERVICE"

The NetFrameworkConfigurationKey RSA key container is the default key container for commands issued by the Aspnet_regiis.exe tool. The preceding command could therefore also be issued as the following:

aspnet_regiis -pa "NT AUTHORITY\NETWORK SERVICE"

Exporting an RSA Key Container

To export an RSA key container to an XML file, you can use the Aspnet_regiis.exe tool with the –px switch. You can use the XML file as backup for the RSA key container or to import the RSA key container on a different server. The private key portion of the RSA key container is required in order to decrypt encrypted information. To make use of your exported key container on another server, you will need to import the private key as well. You can include the private key in your XML file by specifying the –pri option when exporting the key. You must also specify whether the exported key container is machine-level or user-level. To export a user-level key container, you must be logged on as the user in whose Windows profile the key is stored. To specify a user-level key, include the -pku option when exporting the encryption key information; otherwise the exported key will be from the machine key store. For more information on machine-level and user-level encryption keys, see Understanding Machine-Level and User-Level RSA Key Containers.

For example, the following command exports the machine-level RSA key container named SampleKeys to the file named keys.xml and includes the private key information.

aspnet_regiis -px "SampleKeys" keys.xml -pri

Note
For security, after you export an RSA key container to an XML file, copy the XML file to a location external to the server and delete the XML file from the server. This reduces the chance of an attacker gaining access to your RSA key container and thereby the ability to decrypt Web.config files encrypted using that RSA key container.

Importing an RSA Key Container

You can use the Aspnet_regiis.exe tool with the –pi switch to import an RSA key container from an XML file. You must also specify whether the imported key container is a machine-level or user-level key container. To import a user-level key container, you must be logged on as the user in whose Windows profile the key will be stored. To specify a user-level key, include the -pku option when importing the encryption key information; otherwise the exported key will be imported to the machine key store.

For example, the following command imports a machine-level RSA key container named SampleKeys from the file named keys.xml:

aspnet_regiis -pi "SampleKeys" keys.xml

The identity of the ASP.NET application that will use the imported RSA key container must be granted authority to read the contents of the RSA key container. For more information, see Granting Authority to Access an RSA Key Container earlier in this topic.

Deleting an RSA Key Container

To delete an RSA key container, you can use the Aspnet_regiis.exe tool with the –pz switch. Before you delete an RSA key container, ensure that you have either exported the key to an XML file so that it can be imported later, or that there is no information encrypted with the RSA key container that will ever need to be decrypted.

When deleting an RSA key container, you must specify the name of the key container and identify the container as machine-level or user-level. To delete a user-level key container, you must be logged on as the user in whose Windows profile the key is stored.

For example, the following command deletes the machine-level RSA key container named SampleKeys.

aspnet_regiis -pz "SampleKeys"

See Also

Tasks

Walkthrough: Creating and Exporting an RSA Key Container

Other Resources

Encrypting Configuration Information Using Protected Configuration