Configuration Protector Tutorial
Introduction
Blayd Software's Configuration Protector is a developer tool designed to simplify
the tasks of encrypting and decrypting configuration file sections and managing
RSA key containers and their keys during application development.
When a configuration section has been encrypted using a defined protected configuration
provider, the .Net Framework will automatically decrypt it at run time. However,
whilst developing an application you may need to make changes to the settings in
an encrypted section, to add a new value, update an existing value or delete an
existing value. To make changes such as these you will have to manually decrypt
the section, make the change or changes and then encrypt the section again. The
Configuration Protector provides a graphical user interface that enables configuration
sections to be encrypted and decrypted using a point and click technique that reduces
typing and therefore mistakes and speeds up the whole process.
In addition to providing a simple and intuitive user interface for encrypting and
decrypting configuration file sections the Configuration Protector also provides
a graphical user interface for managing RSA key containers and their keys.
This tutorial steps through some of the more common tasks relating to the use of
protected configuration. To follow the article you will need to have a copy of the
Configuration Protector application installed. If you do not already have a copy
of the Configuration Protector you can download an evaluation version from
www.blayd.co.uk. The evaluation version
of Configuration Protector will be fine for the tasks that we are going to step
through in this article.
Prerequisites
As a developer tool the Configuration Protector performs actions that will not,
typically, be permitted when running under a standard user account. For example,
in this article we will be using the Configuration Protector to load a configuration
file and update it's settings, we will also be creating an RSA key container and
it's keys. Therefore, the account under which the Configuration Protector is running
will need to be an administrator account or an account with similar elevated permissions.
This article assume that you have just loaded the Configuration Protector i.e. you
have not already encrypted or decrypted a configuration section or used one of the
RSA key management functions. The Configuration Protector content pages retain their
state between page visits, therefore, if you have already used the Configuration
Protector before starting to follow the steps in this article you may see different
values and/or get different results.
We recommend that you treat each of the walk through sections in this article as
a separate mini-tutorial and load Configuration Protector afresh before starting
to follow the steps. To load Configuration Protector use the shortcut which is,
typically, installed in the following start menu folder:
Start Menu\Programs\Blayd Software\Configuration Protector
Encrypt | Decrypt using Predefined RSA Provider
In a typical .Net Framework installation the machine.config file contains a
configProtectedData section element defining the attributes or properties of
two protected configuration provider instances. This section of the tutorial uses one of
those providers, the RSA protected provider instance named 'RsaProtectedConfigurationProvider'.
The prerequisites to complete this tutorial section are as follows:
- You will need an
app.config file that contains an appSettings section element
with one or more key | value entries.
- You will need write access to the
app.config file, as we are going to encrypt
and then decrypt the appSettings section.
- You will need read access to the RSA key container defined in the
keyContainerName
attribute of the 'RsaProtectedConfigurationProvider' protected configuration provider
in the machine.config file. The container is named 'NetFrameworkConfigurationKey'.
To encrypt or decrypt a configuration file section using the RSA protected provider
instance defined in the machine.config file:
- Start the Configuration Protector.
- Hover the mouse over the section item named 'Protection' in the navigation bar
to the left of the Configuration Protector's main Window. The text will be displayed
as a link, click the link to expand the Protection section.
- Hover the mouse over the Protection section sub item named 'Configuration File'
and then click the link to navigate to the Configuration File content page, which
will be displayed to the right of the navigation bar in the Configuration Protector's
main Window.
- In this example we going to encrypt and then decrypt the
appSettings section
of a Windows Forms application configuration file. Therefore, click the 'App.config'
radio button to select the configuration file type. Then click the browse button
to the right of the 'Configuration File' edit control to display a file open dialog.
In the file open dialog, browse to and select the relevant app.config file.
- By default, the Configuration Protector selects the RSA protected configuration
provider defined in the
machine.config file as the current provider, therefore,
we do not, in this example, have to specify a provider as we are using the Configuration
Protector's default value.
- Hover the mouse over the Protection sub item named 'Encrypt | Decrypt' and then
click the link to navigate to the Encrypt | Decrypt content page.
- You should see the path of the configuration file that you selected in step 4
displayed under the 'Configuration File' label. You should also see the 'RsaProtectedConfigurationProvider'
provider displayed under the 'Protected Configuration Provider Name' label. Select
the
appSettings section in the 'Configuration Sections' list, if it is not already
selected.
- You can check the current state of the
appSettings section in the configuration
file by clicking the 'Check State' button. This is an optional step as you do not
have to do this in order to encrypt or decrypt the section. However, if you are
not sure whether or not the section is currently encrypted, checking it's current
state will prevent you from trying to encrypt a section that is already encrypted!
The Configuration Protector will not encrypt a configuration file section if it
does not exist in the file, is already encrypted or is locked.
- Click the 'Encrypt' button to encrypt the
appSettings configuration section.
You should see the values in the 'Configuration Section State' group box update
to reflect the fact that the appSettings section is now encrypted. You can now use
a text editor to examine the configuration file and ensure that the appSettings
section values are indeed encrypted.
- Close the configuration file in the text editor and then click the 'Decrypt'
button to decrypt the
appSettings configuration section. Again, you should see the
section's sate update to show that it is now decrypted. Open the configuration file
again in the text editor to ensure that the appSettings section values have been
decrypted.
Encrypt | Decrypt using Predefined DPAPI Provider
In a typical .Net Framework installation the machine.config file contains a
configProtectedData section element defining the attributes or properties of
two protected configuration provider instances. This section of the tutorial uses one of
those providers, the DPAPI protected provider instance named 'DataProtectionConfigurationProvider'.
The prerequisites to complete this tutorial section are as follows:
- You will need an
app.config file that contains an appSettings section element
with one or more key | value entries.
- You will need write access to the
app.config file as we are going to encrypt
and then decrypt the appSettings section.
To encrypt or decrypt a configuration file section using the DPAPI protected provider
instance defined in the machine.config file:
- Start the Configuration Protector.
- Hover the mouse over the section item named 'Protection' in the navigation bar
to the left of the Configuration Protector's main Window. The text will be displayed
as a link, click the link to expand the Protection section.
- Hover the mouse over the Protection section sub item named 'Configuration File'
and then click the link to navigate to the Configuration File content page, which
will be displayed to the right of the navigation bar in the Configuration Protector's
main Window.
- In this example we going to encrypt and then decrypt the
appSettings section
of a Windows Forms application configuration file. Therefore, click the 'App.config'
radio button to select the configuration file type. Then click the browse button
to the right of the 'Configuration File' edit control to display a file open dialog.
In the file open dialog, browse to and select the relevant app.config file.
- Hover the mouse over the Protection section sub item named 'Provider' and then
click the link to navigate to the Provider content page. We are going to use the
predefined DPAPI provider, therefore, click the 'DPAPI protected configuration provider'
radio button. You should now see the name of the DPAPI provider displayed in the
'Provider Name' control, this signifies that the provider is now the selected provider
and it will be used to encrypt and decrypt configuration sections.
- Hover the mouse over the Protection sub item named 'Encrypt | Decrypt' and then
click the link to navigate to the Encrypt | Decrypt content page.
- You should see the path of the configuration file that you selected in step 4
displayed under the 'Configuration File' label. You should also see the 'DataProtectionConfigurationProvider'
provider displayed under the 'Protected Configuration Provider Name' label. Select
the
appSettings section in the 'Configuration Sections' list, if it is not already
selected.
- You can check the current state of the
appSettings section in the configuration
file by clicking the 'Check State' button. This is an optional step as you do not
have to do this in order to encrypt or decrypt the section. However, if you are
not sure whether or not the section is currently encrypted, checking it's current
state will prevent you from trying to encrypt a section that is already encrypted!
The Configuration Protector will not encrypt a configuration file section if it
does not exist in the file, is already encrypted or is locked.
- Click the 'Encrypt' button to encrypt the
appSettings configuration section.
You should see the values in the 'Configuration Section State' group box update
to reflect the fact that the appSettings section is now encrypted. You can now use
a text editor to examine the configuration file and ensure that the appSettings
section values are indeed encrypted.
- Close the configuration file in the text editor and then click the 'Decrypt'
button to decrypt the
appSettings configuration section. Again, you should see the
section's sate update to show that it is now decrypted. Open the configuration file
again in the text editor to ensure that the appSettings section values have been
decrypted.
Create the Settings for a Named RSA Provider Instance
In a typical .Net Framework installation the machine.config file contains a configProtectedData
section element defining the attributes or properties of two protected configuration
provider instances. You do not, however, have to use either of these provider instances,
you can define your own attributes or properties for an instance of either of the
two protected configuration providers implemented in the .Net Framework i.e. RsaProtectedConfigurationProvider
and DpapiProtectedConfigurationProvider classes. This section of the tutorial creates
custom attributes for an instance of the RSA protected configuration provider class.
The prerequisites to complete this tutorial section are as follows:
- You will need an
app.config file that contains an appSettings section element
or another section element.
- You will need write access to the
app.config file as we are going to save the
custom attributes for an instance of the RSA protected configuration provider to
the app.config file.
- You will need to be running Configuration Protector under an administrator account
or an account with similar elevated privileges as we are going to create an RSA
key container.
To create custom attributes for an instance of the RSA protected configuration provider
and save the settings to the app.config file:
- Start the Configuration Protector.
- Hover the mouse over the section item named 'RSA Key Management' in the navigation
bar to the left of the Configuration Protector's main Window. The text will be displayed
as a link, click the link to expand the RSA Key Management section.
- Hover the mouse over the RSA Key Management section sub item named 'Create Key
Container' and then click the link to navigate to the Create Key Container content
page, which will be displayed to the right of the navigation bar in the Configuration
Protector's main Window.
- Enter the name 'SampleContainer' in the 'Key Container Name' edit control. The
default values will be fine for the other fields. Click the 'Create' button to generate
an RSA public/private key pair in a container named 'SampleContainer'. The Configuration
Protector will display a message to inform you that the container has been created
successfully.
- Hover the mouse over the section item named 'Protection' in the navigation bar
to the left of the Configuration Protector's main Window. The text will be displayed
as a link, click the link to expand the Protection section.
- Hover the mouse over the Protection section sub item named 'Configuration File'
and then click the link to navigate to the Configuration File content page.
- In this example we going to save the attributes of the provider instance to an
app.config file. Therefore, click the 'App.config' radio button to select the configuration
file type. Then click the browse button to the right of the 'Configuration File'
edit control to display a file open dialog. In the file open dialog, browse to and
select the relevant app.config file.
- Hover the mouse over the Protection section sub item named 'RSA Provider' and
then click the link to navigate to the RSA Provider content page.
- In the 'Provider Name' control enter a name for the provider instance, in this
example type in the name 'SampleRSAProvider'. You can add a description for the
provider if you want but 'Description' is an optional field. Leave the 'Set as the
default protected configuration provider' check box un-checked. In the 'Key Container
Name' edit control enter the name of the container you created in step 4 i.e. 'SampleContainer'.
Leave the other fields with their defaults and click the 'Save' button. The Configuration
Protector will save the attributes of the RSA protected configuration provider to
the
app.config file you selected in step 7. Open the app.config file in a text editor
to check that the provider settings have indeed been saved.
Conclusion
The Configuration Protector has context sensitive help for each content page, just
hover the mouse over the Help text, in the content pane header and it will be displayed
as a link, click the link to get information relating to the current content page.
Although this article has not covered all of the features of the Configuration Protector,
we think that there is enough information here to get you going. The help file that
ships with Configuration Protector contains a series of 'How To' topics that cover
the features that we have not been able to cover in this article. Therefore, if
you have been unable to find the information that you require in this article, you
should find it in the Configuration Protector help file.
Copyright ©Blayd Software Limited 2007-2010. All rights reserved.