ProtectedConfigurationProvider Class

Definition

public ref class ProtectedConfigurationProvider abstract : System::Configuration::Provider::ProviderBase

public abstract class ProtectedConfigurationProvider : System.Configuration.Provider.ProviderBase

type ProtectedConfigurationProvider = class
 inherit ProviderBase

Public MustInherit Class ProtectedConfigurationProvider
Inherits ProviderBase

Inheritance

Object

ProviderBase

ProtectedConfigurationProvider

Derived

System.Configuration.DpapiProtectedConfigurationProvider

System.Configuration.RsaProtectedConfigurationProvider

Examples

The following example shows how to implement a custom ProtectedConfigurationProvider.

To be able to configure this provider, as shown in the next configuration excerpt, you must install it in the Global Assembly Cache (GAC). For more information, see Implementing a Protected Configuration Provider.

using System;
using System.Xml;
using System.Security.Cryptography;
using System.IO;
using System.Text;
using System.Configuration.Provider;
using System.Collections.Specialized;
using System.Configuration;

namespace Samples.AspNet
{
 // Shows how to create a custom protected configuration
 // provider.
 public class TripleDESProtectedConfigurationProvider :
 ProtectedConfigurationProvider
 {

 private TripleDESCryptoServiceProvider des =
 new TripleDESCryptoServiceProvider();

 private string pKeyFilePath;
 private string pName;

 // Gets the path of the file
 // containing the key used to
 // encryption or decryption.
 public string KeyFilePath
 {
 get { return pKeyFilePath; }
 }

 // Gets the provider name.
 public override string Name
 {
 get { return pName; }
 }

 // Performs provider initialization.
 public override void Initialize(string name,
 NameValueCollection config)
 {
 pName = name;
 pKeyFilePath = config["keyContainerName"];
 ReadKey(KeyFilePath);
 }

 // Performs encryption.
 public override XmlNode Encrypt(XmlNode node)
 {
 string encryptedData = EncryptString(node.OuterXml);

 XmlDocument xmlDoc = new XmlDocument();
 xmlDoc.PreserveWhitespace = true;
 xmlDoc.LoadXml("<EncryptedData>" +
 encryptedData + "</EncryptedData>");

 return xmlDoc.DocumentElement;
 }

 // Performs decryption.
 public override XmlNode Decrypt(XmlNode encryptedNode)
 {
 string decryptedData =
 DecryptString(encryptedNode.InnerText);

 XmlDocument xmlDoc = new XmlDocument();
 xmlDoc.PreserveWhitespace = true;
 xmlDoc.LoadXml(decryptedData);

 return xmlDoc.DocumentElement;
 }

 // Encrypts a configuration section and returns 
 // the encrypted XML as a string.
 private string EncryptString(string encryptValue)
 {
 byte[] valBytes =
 Encoding.Unicode.GetBytes(encryptValue);

 ICryptoTransform transform = des.CreateEncryptor();

 MemoryStream ms = new MemoryStream();
 CryptoStream cs = new CryptoStream(ms,
 transform, CryptoStreamMode.Write);
 cs.Write(valBytes, 0, valBytes.Length);
 cs.FlushFinalBlock();
 byte[] returnBytes = ms.ToArray();
 cs.Close();

 return Convert.ToBase64String(returnBytes);
 }

 // Decrypts an encrypted configuration section and 
 // returns the unencrypted XML as a string.
 private string DecryptString(string encryptedValue)
 {
 byte[] valBytes =
 Convert.FromBase64String(encryptedValue);

 ICryptoTransform transform = des.CreateDecryptor();

 MemoryStream ms = new MemoryStream();
 CryptoStream cs = new CryptoStream(ms,
 transform, CryptoStreamMode.Write);
 cs.Write(valBytes, 0, valBytes.Length);
 cs.FlushFinalBlock();
 byte[] returnBytes = ms.ToArray();
 cs.Close();

 return Encoding.Unicode.GetString(returnBytes);
 }

 // Generates a new TripleDES key and vector and 
 // writes them to the supplied file path.
 public void CreateKey(string filePath)
 {
 des.GenerateKey();
 des.GenerateIV();

 StreamWriter sw = new StreamWriter(filePath, false);
 sw.WriteLine(ByteToHex(des.Key));
 sw.WriteLine(ByteToHex(des.IV));
 sw.Close();
 }

 // Reads in the TripleDES key and vector from 
 // the supplied file path and sets the Key 
 // and IV properties of the 
 // TripleDESCryptoServiceProvider.
 private void ReadKey(string filePath)
 {
 StreamReader sr = new StreamReader(filePath);
 string keyValue = sr.ReadLine();
 string ivValue = sr.ReadLine();
 des.Key = HexToByte(keyValue);
 des.IV = HexToByte(ivValue);
 }

 // Converts a byte array to a hexadecimal string.
 private string ByteToHex(byte[] byteArray)
 {
 string outString = "";

 foreach (Byte b in byteArray)
 outString += b.ToString("X2");

 return outString;
 }

 // Converts a hexadecimal string to a byte array.
 private byte[] HexToByte(string hexString)
 {
 byte[] returnBytes = new byte[hexString.Length / 2];
 for (int i = 0; i < returnBytes.Length; i++)
 returnBytes[i] =
 Convert.ToByte(hexString.Substring(i * 2, 2), 16);
 return returnBytes;
 }
 }
}

Imports System.Xml
Imports System.Security.Cryptography
Imports System.IO
Imports System.Text
Imports System.Configuration.Provider
Imports System.Collections.Specialized
Imports System.Configuration


' Shows how to create a custom protected configuration
' provider.
Namespace Samples.AspNet

 Public Class TripleDESProtectedConfigurationProvider
 Inherits ProtectedConfigurationProvider

 Private des _
 As New TripleDESCryptoServiceProvider()

 Private pKeyFilePath As String
 Private pName As String

 ' Gets the path of the file
 ' containing the key used to
 ' encrypt/decrypt.

 Public ReadOnly Property KeyFilePath() As String
 Get
 Return pKeyFilePath
 End Get
 End Property

 ' Gets the provider name.

 Public Overrides ReadOnly Property Name() As String
 Get
 Return pName
 End Get
 End Property


 ' Performs provider initialization.
 Public Overrides Sub Initialize( _
 ByVal name As String, _
 ByVal config As NameValueCollection)
 pName = name
 pKeyFilePath = config("keyContainerName")
 ReadKey(KeyFilePath)
 End Sub


 ' Performs encryption.
 Public Overrides Function Encrypt( _
 ByVal node As XmlNode) As XmlNode
 Dim encryptedData As String = _
 EncryptString(node.OuterXml)

 Dim xmlDoc As New XmlDocument()
 xmlDoc.PreserveWhitespace = True
 xmlDoc.LoadXml( _
 ("<EncryptedData>" + encryptedData + _
 "</EncryptedData>"))

 Return xmlDoc.DocumentElement
 End Function 'Encrypt

 ' Performs decryption.
 Public Overrides Function Decrypt( _
 ByVal encryptedNode As XmlNode) As XmlNode
 Dim decryptedData As String = _
 DecryptString(encryptedNode.InnerText)

 Dim xmlDoc As New XmlDocument()
 xmlDoc.PreserveWhitespace = True
 xmlDoc.LoadXml(decryptedData)

 Return xmlDoc.DocumentElement
 End Function 'Decrypt



 ' Encrypts a configuration section and returns 
 ' the encrypted XML as a string.
 Private Function EncryptString( _
 ByVal encryptValue As String) As String
 Dim valBytes As Byte() = _
 Encoding.Unicode.GetBytes(encryptValue)

 Dim transform As ICryptoTransform = _
 des.CreateEncryptor()

 Dim ms As New MemoryStream()
 Dim cs As New CryptoStream(ms, _
 transform, CryptoStreamMode.Write)
 cs.Write(valBytes, 0, valBytes.Length)
 cs.FlushFinalBlock()
 Dim returnBytes As Byte() = ms.ToArray()
 cs.Close()

 Return Convert.ToBase64String(returnBytes)
 End Function 'EncryptString



 ' Decrypts an encrypted configuration section and 
 ' returns the unencrypted XML as a string.
 Private Function DecryptString( _
 ByVal encryptedValue As String) As String
 Dim valBytes As Byte() = _
 Convert.FromBase64String(encryptedValue)

 Dim transform As ICryptoTransform = _
 des.CreateDecryptor()

 Dim ms As New MemoryStream()
 Dim cs As New CryptoStream(ms, _
 transform, CryptoStreamMode.Write)
 cs.Write(valBytes, 0, valBytes.Length)
 cs.FlushFinalBlock()
 Dim returnBytes As Byte() = ms.ToArray()
 cs.Close()

 Return Encoding.Unicode.GetString(returnBytes)
 End Function 'DecryptString


 ' Generates a new TripleDES key and vector and 
 ' writes them to the supplied file path.
 Public Sub CreateKey(ByVal filePath As String)
 des.GenerateKey()
 des.GenerateIV()

 Dim sw As New StreamWriter(filePath, False)
 sw.WriteLine(ByteToHex(des.Key))
 sw.WriteLine(ByteToHex(des.IV))
 sw.Close()
 End Sub



 ' Reads in the TripleDES key and vector from 
 ' the supplied file path and sets the Key 
 ' and IV properties of the 
 ' TripleDESCryptoServiceProvider.
 Private Sub ReadKey(ByVal filePath As String)
 Dim sr As New StreamReader(filePath)
 Dim keyValue As String = sr.ReadLine()
 Dim ivValue As String = sr.ReadLine()
 des.Key = HexToByte(keyValue)
 des.IV = HexToByte(ivValue)
 End Sub



 ' Converts a byte array to a hexadecimal string.
 Private Function ByteToHex( _
 ByVal byteArray() As Byte) As String
 Dim outString As String = ""

 Dim b As [Byte]
 For Each b In byteArray
 outString += b.ToString("X2")
 Next b
 Return outString
 End Function 'ByteToHex


 ' Converts a hexadecimal string to a byte array.
 Private Function HexToByte(ByVal hexString As String) As Byte()
 Dim returnBytes(hexString.Length / 2) As Byte
 Dim i As Integer
 For i = 0 To returnBytes.Length - 1
 returnBytes(i) = _
 Convert.ToByte(hexString.Substring(i * 2, 2), 16)
 Next i
 Return returnBytes
 End Function 'HexToByte
 End Class

End Namespace

The following example shows how to use the previous custom ProtectedConfigurationProvider.

using System;
using System.Configuration;
using Samples.AspNet.Configuration;

namespace Samples.AspNet.Configuration
{

 // Show how to use a custom protected configuration
 // provider.
 public class TestingProtectedConfigurationProvider
 {

 // Protect the connectionStrings section.
 private static void ProtectConfiguration()
 {

 // Get the application configuration file.
 System.Configuration.Configuration config =
 ConfigurationManager.OpenExeConfiguration(
 ConfigurationUserLevel.None);

 // Define the provider name.
 string provider =
 "TripleDESProtectedConfigurationProvider";

 // Get the section to protect.
 ConfigurationSection connStrings =
 config.ConnectionStrings;

 if (connStrings != null)
 {
 if (!connStrings.SectionInformation.IsProtected)
 {
 if (!connStrings.ElementInformation.IsLocked)
 {
 // Protect the section.
 connStrings.SectionInformation.ProtectSection(provider);

 connStrings.SectionInformation.ForceSave = true;
 config.Save(ConfigurationSaveMode.Full);

 Console.WriteLine("Section {0} is now protected by {1}",
 connStrings.SectionInformation.Name,
 connStrings.SectionInformation.ProtectionProvider.Name);
 }
 else
 Console.WriteLine(
 "Can't protect, section {0} is locked",
 connStrings.SectionInformation.Name);
 }
 else
 Console.WriteLine(
 "Section {0} is already protected by {1}",
 connStrings.SectionInformation.Name,
 connStrings.SectionInformation.ProtectionProvider.Name);
 }
 else
 Console.WriteLine("Can't get the section {0}",
 connStrings.SectionInformation.Name);
 }

 // Unprotect the connectionStrings section.
 private static void UnProtectConfiguration()
 {

 // Get the application configuration file.
 System.Configuration.Configuration config =
 ConfigurationManager.OpenExeConfiguration(
 ConfigurationUserLevel.None);

 // Get the section to unprotect.
 ConfigurationSection connStrings =
 config.ConnectionStrings;

 if (connStrings != null)
 {
 if (connStrings.SectionInformation.IsProtected)
 {
 if (!connStrings.ElementInformation.IsLocked)
 {
 // Unprotect the section.
 connStrings.SectionInformation.UnprotectSection();

 connStrings.SectionInformation.ForceSave = true;
 config.Save(ConfigurationSaveMode.Full);

 Console.WriteLine("Section {0} is now unprotected.",
 connStrings.SectionInformation.Name);
 }
 else
 Console.WriteLine(
 "Can't unprotect, section {0} is locked",
 connStrings.SectionInformation.Name);
 }
 else
 Console.WriteLine(
 "Section {0} is already unprotected.",
 connStrings.SectionInformation.Name);
 }
 else
 Console.WriteLine("Can't get the section {0}",
 connStrings.SectionInformation.Name);
 }

 public static void Main(string[] args)
 {

 string selection = string.Empty;

 if (args.Length == 0)
 {
 Console.WriteLine(
 "Select createkey, protect or unprotect");
 return;
 }

 selection = args[0].ToLower();

 switch (selection)
 {

 // Create the key to use during 
 // encryption/decryption.
 case "createkey":
 string keyContainer = 
 "pcKey.txt";

 // Instantiate the custom provider.
 TripleDESProtectedConfigurationProvider 
 provider =
 new TripleDESProtectedConfigurationProvider();

 // Create the encryption/decryption key.
 provider.CreateKey(keyContainer);

 Console.WriteLine(
 "New TripleDES key created in {0}",
 keyContainer);
 break;

 case "protect":
 ProtectConfiguration();
 break;

 case "unprotect":
 UnProtectConfiguration();
 break;

 default:
 Console.WriteLine("Unknown selection");
 break;
 }

 Console.Read();
 }
 }
}

Imports System.Configuration

Namespace Samples.AspNet
 ' Show how to use a custom protected configuration
 ' provider.

 Public Class TestingProtectedConfigurationProvider


 ' Protect the connectionStrings section.
 Private Shared Sub ProtectConfiguration()

 ' Get the application configuration file.
 Dim config _
 As System.Configuration.Configuration = _
 ConfigurationManager.OpenExeConfiguration( _
 ConfigurationUserLevel.None)

 ' Define the provider name.
 Dim provider As String = _
 "TripleDESProtectedConfigurationProvider"

 ' Get the section to protect.
 Dim connStrings _
 As ConfigurationSection = config.ConnectionStrings

 If Not (connStrings Is Nothing) Then
 If Not connStrings.SectionInformation.IsProtected Then
 If Not connStrings.ElementInformation.IsLocked Then
 ' Protect the section.
 connStrings.SectionInformation.ProtectSection( _
 provider)

 connStrings.SectionInformation.ForceSave = True
 config.Save(ConfigurationSaveMode.Full)

 Console.WriteLine( _
 "Section {0} is now protected by {1}", _
 connStrings.SectionInformation.Name, _
 connStrings.SectionInformation.ProtectionProvider.Name)

 Else
 Console.WriteLine( _
 "Can't protect, section {0} is locked", _
 connStrings.SectionInformation.Name)
 End If
 Else
 Console.WriteLine( _
 "Section {0} is already protected by {1}", _
 connStrings.SectionInformation.Name, _
 connStrings.SectionInformation.ProtectionProvider.Name)
 End If

 Else
 Console.WriteLine( _
 "Can't get the section {0}", _
 connStrings.SectionInformation.Name)
 End If
 End Sub


 ' Unprotect the connectionStrings section.
 Private Shared Sub UnProtectConfiguration()

 ' Get the application configuration file.
 Dim config _
 As System.Configuration.Configuration = _
 ConfigurationManager.OpenExeConfiguration( _
 ConfigurationUserLevel.None)

 ' Get the section to unprotect.
 Dim connStrings _
 As ConfigurationSection = config.ConnectionStrings

 If Not (connStrings Is Nothing) Then
 If connStrings.SectionInformation.IsProtected Then
 If Not connStrings.ElementInformation.IsLocked Then
 ' Unprotect the section.
 connStrings.SectionInformation.UnprotectSection()

 connStrings.SectionInformation.ForceSave = True
 config.Save(ConfigurationSaveMode.Full)

 Console.WriteLine( _
 "Section {0} is now unprotected.", _
 connStrings.SectionInformation.Name)

 Else
 Console.WriteLine( _
 "Can't unprotect, section {0} is locked", _
 connStrings.SectionInformation.Name)
 End If
 Else
 Console.WriteLine( _
 "Section {0} is already unprotected.", _
 connStrings.SectionInformation.Name)
 End If

 Else
 Console.WriteLine( _
 "Can't get the section {0}", _
 connStrings.SectionInformation.Name)
 End If
 End Sub



 Public Shared Sub Main(ByVal args() As String)

 Dim selection As String = String.Empty

 If args.Length = 0 Then
 Console.WriteLine( _
 "Select createkey, protect or unprotect")
 Return
 End If

 selection = args(0).ToLower()

 Select Case selection

 ' Create the key to use during 
 ' encryption/decryption.
 Case "createkey"
 Dim keyContainer As String = "pcKey.txt"

 ' Instantiate the custom provider.
 Dim provider _
 As New TripleDESProtectedConfigurationProvider()

 ' Create the encryption/decryption key.
 provider.CreateKey(keyContainer)

 Console.WriteLine( _
 "New TripleDES key created in {0}", _
 keyContainer)

 Case "protect"
 ProtectConfiguration()

 Case "unprotect"
 UnProtectConfiguration()

 Case Else
 Console.WriteLine("Unknown selection")
 End Select

 Console.Read()
 End Sub
 End Class
End Namespace

Remarks

You can encrypt sections of a configuration file to protect sensitive information used by your application. This improves security by making it difficult for unauthorized access even if an attacker gains access to your configuration file.

.NET includes two protected configuration providers that can be used to encrypt sections of a configuration file. The RsaProtectedConfigurationProvider class uses the RSACryptoServiceProvider to encrypt configuration sections. The DpapiProtectedConfigurationProvider class uses the Windows Data Protection API (DPAPI) to encrypt configuration sections.

You might have a requirement to encrypt sensitive information using an algorithm other than the RSA or DPAPI providers. In this case, you can build your own custom protected-configuration provider. The ProtectedConfigurationProvider is an abstract base class that you must inherit from to create your own protected-configuration provider.

Whether you use a standard or a custom provider, you must ensure that it is configured with the add element in the providers section of the configProtectedData configuration section. (See next example.)

For details, see Implementing a Protected Configuration Provider.

See also

• ProtectedConfigurationProviderCollection
• ProtectedConfiguration
• ProtectedConfigurationSection
• DpapiProtectedConfigurationProvider
• RsaProtectedConfigurationProvider
• Encrypting Configuration Information Using Protected Configuration