Protecting .NET Framework Configuration Sections

Overview

The .NET Framework’s configuration system provides a mechanism for protecting sensitive sections of a web.config file. This topic distills the steps needed to protect configuration secrets in a web farm deployment:

1. Use .NET’s aspnet_regiis utility to create an RSA keypair and export it to a file.

2. Import the keypair on every web server in your farm.

3. Grant access to the keypair for the user identity that will be running your web application.

4. Encrypt the sensitive web.config section.

5. Deploy the web.config file containing the encrypted section.

See the topic Encrypting Configuration Information Using Protected Configuration in Microsoft’s documentation for full coverage of this feature.

Creating Keys

1. On a Windows system with the .NET Framework 4.x installed, open an Administrator command prompt in the C:\Windows\Microsoft.NET\Framework64\v4.0.30319 directory.

2. Run the following command to create an RSA key container that will be used by servers in your web farm to protect web.config sections:

   aspnet_regiis.exe -pc "SharedConfigCryptoKeys" -exp
   

3. Export the new key to the filesystem:

   aspnet_regiis -px "SharedConfigCryptoKeys" c:\keys.xml -pri
   

   This file should be backed up in a secure location–if additional web servers need to be added to your farm at a later date, they must import this keypair.

   Note

   If the XML file is lost, it can be re-exported from the machine that originally generated it. Otherwise, a new keypair will need to be generated and deployed to all the servers in the farm, and the protected section of the web.config file will need to be re-encrypted using the new keypair.

Deploying the RSA keypair

Copy the keys.xml file to every web server in your farm and import it. To import, open an administrative command prompt on each web server and run:

aspnet_regiis -pi "SharedConfigCryptoKeys" c:\keys.xml

After running the import command on a web server, the keys.xml file should be deleted from the web server’s filesystem.

Granting Access to Keys

The account used by your IIS worker process will need to be granted access to the RSA keypair that you imported in the prior step. On every web server, run the “aspnet_regiis -pa” command to grant access to the RSA keypair.

• Built-in Windows Network Service account:

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

• Domain account:

  aspnet_regiis -pa "SharedConfigCryptoKeys" "MyDomain\AppPoolUserName"
  

• If the app runs as the ApplicationPoolIdentity, the account will be IIS APPPOOL\ followed by the name of the IIS application pool:

  aspnet_regiis -pa "SharedConfigCryptoKeys" "IIS APPPOOL\DefaultAppPool"
  

Protecting the Config Section

1. Add the following <configProtectedData/> section to your app’s web.config file:

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

2. Run the following command to perform encryption of a configuration section, substituting the C:\inetpub\wwwroot\MyWebApplication path with the actual path to your web application. In this example, we encrypt the <scaleoutEncryptedSessions/> configuration section containing the encryption password used by ScaleOut’s session state providers:

   aspnet_regiis.exe -pef "scaleoutEncryptedSessions" "C:\inetpub\wwwroot\MyWebApplication" -prov "ConfigCryptoProvider"
   

   This command modifies the web.config file in the specified directory, replacing the <scaleoutEncryptedSessions/> element with an encrypted section.

3. This modified web.config can now be deployed to the web servers in your farm. Assuming that all web servers have imported the RSA keypair (aspnet_regiis -pi) and the web pool’s identity has been granted access to the keypair (aspnet_regiis -pa), the web app will be able to decrypt the <scaleoutEncryptedSessions/> section at runtime.

Decrypting the Config Section

The encryped config section can be decrypted using the “aspnet_regiis.exe -pdf” command:

aspnet_regiis.exe -pdf "scaleoutEncryptedSessions" "C:\inetpub\wwwroot\MyWebApplication"

In this example, we decrypted the <scaleoutEncryptedSessions/> configuration section containing the encryption password used by ScaleOut’s session state providers.