Entering Configuration Information

  • Article
Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

These procedures explain how to configure the Cryptography Application Block. Also see Using the Cryptographic Key Wizard.

Properties associated with the nodes appear in the right pane of the Configuration Console and in the Properties window of the Visual Studio Configuration Editor. For details of the configuration schema, see Source Schema for the Cryptography Application Block.

To add the Cryptography Application Block

  1. Open the configuration file. For more information, see Configuring Enterprise Library.
  2. Right-click Application Configuration, point to New, and then click Cryptography Application Block.
  3. The configuration tool automatically adds the Cryptography Application Block node, and the Hash Providers and Symmetric Providers sub nodes, with default settings.

To configure the Cryptography Application Block

  1. (Optional) In the properties pane, set the DefaultHashProvider property. This sets the instance of the hash provider that the Cryptography Application Block uses if the application code does not specify another provider. In the drop-down list, click the hash provider. The default is none.
  2. (Optional) In the properties pane, set the DefaultSymmetricCryptoProvider property. This sets the instance of the symmetric cryptography provider that the Cryptography Application Block uses if the application code does not specify another provider. In the drop-down list, click the symmetric provider. The default is none.

To configure a custom hash provider

  1. Click Hash Providers, point to New, and then click Custom Hash Provider.
  2. In the Attributes section of the properties pane, click the ellipsis button (...).
  3. In the EditableKeyValue Collection Editor dialog box, click Add to add a new name/value pair.
  4. In the right pane of the EditableKeyValue Collection Editor dialog box, enter the key name and the value of the property.
  5. Add more name/value pairs as appropriate, and then click OK.
  6. (Optional) In the Name property section located in the properties pane of the configuration tool, change the name of the custom hash provider. The default name is Custom Hash Provider.
  7. In the Type section of the properties pane, click the ellipsis button (…).In the Filter edit box type the string to use to filter the list, for example type "string" to filter for all classes containing the word "string". If the type you want is not included in the Assemblies folder, click Load form File or Load from GAC in the Type Selector dialog box to find the assembly that contains the type you want.

To configure a hash algorithm provider

  1. Click Hash Providers, point to New, and then click HashAlgorithm Provider.
  2. In the Type Selector dialog box, select the hash algorithm provider type you want to use. If the hash provider is not included, click Load from File or Load from GAC in the Type Selector dialog box to find the assembly that contains the type you want.
  3. (Optional) In the Name property section located in the properties pane of the configuration tool, change the name of the hash algorithm provider. The default name is the type name you selected in step 2.
  4. Set the SaltEnabled property. In the drop-down list, click True or False. The default is False.

Note

The Cryptographic Key Wizard appears for keyed hash algorithm providers. For information about generating and importing keys, see the section Using the Cryptographic Key Wizard later in this topic.

To configure a custom symmetric cryptography provider

  1. Click Symmetric Providers, point to New, and then click Custom Symmetric Cryptography Provider.
  2. In the Attributes section of the properties pane, click the ellipsis button (...).
  3. In the EditableKeyValue Collection Editor dialog box, click Add to add a new name/value pair.
  4. In the right pane of the EditableKeyValue Collection Editor dialog box, enter the key name and the value of the property.
  5. Add more name/value pairs as appropriate, and then click OK.
  6. (Optional) In the Name property section located in the properties pane of the configuration tool, change the name of the custom symmetric cryptography provider. The default name is Custom Hash Provider.
  7. In the Type property section of the properties pane, click the ellipsis button (…). If the type you want is not included in the Assemblies folder, click Load Assembly in the Type Selector dialog box to find the assembly that contains the type you want.

To configure a DPAPI symmetric cryptography provider

  1. Click Symmetric Providers, point to New, and then click DPAPI Symmetric Cryptography Provider.

  2. (Optional) In the Name section located in the properties pane of the configuration tool, change the name of the DPAPI symmetric cryptography provider. The default name is DPAPI Symmetric Cryptography Provider.

  3. Set the ProtectionScope property. In the drop-down list, click CurrentUser or LocalMachine.

    The CurrentUser value means that DPAPI uses a loaded user profile to generate the key. Only that particular user account can decrypt the encrypted data. The LocalMachine value means that that any code running on the machine has access to the protected key; therefore, it can decrypt any secret encrypted in LocalMachine mode. To counteract this, your application code can pass an entropy value when it calls the Encrypt or Decrypt methods. Entropy makes it more difficult for one application, running on the same computer, to compromise another application's encryption key. However, you must protect the entropy value. If it is simply saved to an unprotected file, attackers can access the file, retrieve the entropy value, and use it to decrypt an application's data. The application block configuration does not include the entropy value. This means that you cannot use the configuration tools to create or save an entropy value.

To configure a symmetric algorithm provider

  1. Click Symmetric Providers, point to New, and then click Symmetric Algorithm Provider.
  2. In the Type Selector, select the symmetric algorithm provider type you want to use. If the provider is not included, click Load Assembly in the Type Selector to find the assembly that contains the type you want. The default type is RijndaelMananged.
  3. Use the Cryptographic Key Wizard to either import or generate a key. For more information, see the next section, "Using the Cryptographic Key Wizard."

Using the Cryptographic Key Wizard

By using the Cryptographic Key Wizard, you can do the following:

  • Create a new key.
  • Use an existing DPAPI-protected key file.
  • Import a password-protected key file.

Enterprise Library uses DPAPI to protect your keys. You can use the Cryptographic Key Wizard to create a key; each key is stored in a separate file that is protected with DPAPI. When you create the key, you choose either machine mode or user mode to limit access to the key.

Use machine mode in the following situations:

  • Your application runs on its own dedicated server with no other applications.
  • You have multiple applications that run on the same server and you want those applications to be able to share sensitive information.

Use user mode if you run your application in a shared hosting environment and you want to make sure that your application's sensitive data is not accessible to other applications on the server. In this situation, each application should run under a separate identity, and the resources for the application—such as files and databases—should be restricted to that identity.

Note

If you use DPAPI with machine mode, the encrypted string is specific to a particular computer, so you must generate the encrypted data on every computer. Do not copy the encrypted data across computers that are in a server farm or a cluster.

The following procedures describe how to use the Cryptographic Key Wizard.

To create a new key

  1. Select Create a new key, and then click Next.
  2. Enter the hexadecimal key you want to use or click Generate to create a new key. Click Next.
  3. Choose where you want to store the key file. Enter the location or click the ellipsis button (…) and select the location. Click Next.
  4. Select either User mode or Machine mode. User mode uses the credentials of the user who is currently logged on to encrypt the key. In machine mode, any user who is logged on can encrypt and decrypt the key. Click Finish.
  5. The Key property appears in the right pane of the configuration console. Click the ellipsis button (…) to use the Cryptographic Key Wizard again to generate a different key.

To use an existing DPAPI-protected key file

  1. Select Use an existing DPAPI-protected key file, and then click Next.
  2. Enter the location of the key file. The file must contain a key that is associated with the same algorithm type as the type you are using now. For example, if you are currently configuring a RijndaelManaged type algorithm, the key you are importing must also be associated with a RijndaelManaged type algorithm. For more information, see the section "Usage Notes" later in this topic. Enter the location or click the ellipsis button (…) and select the location. Click Next.
  3. Select either User mode or Machine mode. User mode uses the credentials of the user who is currently logged on to encrypt the key. In machine mode, any user who is logged on can encrypt and decrypt the key. Click Finish.
  4. The Key property appears in the properties pane of the configuration tool. Click the ellipsis button (…) to use the Cryptographic Key Wizard again to generate a different key.

To import a password-protected key file

  1. Select Import a password-protected key file, and then click Next.
  2. Enter the location of the key file or click the ellipsis button (…) and select the location. The file must contain a key that is associated with the same algorithm type as the type you are currently using. For example, if you are currently configuring a RijndaelManaged type algorithm, the key you are importing must also be associated with a RijndaelManaged type algorithm. For more information, see the section "Usage Notes" later in this section. Enter the password that was used to encrypt the file, and then click Next.
  3. Choose where you want to store the key file. Enter the location or click the ellipsis button (…) and select the location, and then click Next.
  4. Select either User mode or Machine mode, and then click Finish. User mode uses the credentials of the user who is currently logged on to encrypt the key. In machine mode, any user who is logged on can encrypt and decrypt the key.
  5. The Key property appears in the properties pane of the configuration tool. Click the ellipsis button (…) to use the Cryptographic Key Wizard again to generate a different key.

Usage Notes

Consider these points when you import and store keys.

  • When you import a key for an algorithm, you must select a key file that was exported for the same algorithm type. If you select a key for a different algorithm type, you will receive an exception at application run time.
  • The configuration tools store the absolute path to each key file in the <securityCryptographyConfiguration> section of the configuration source. For example, when you use the default configuration source, your application configuration file contains the absolute path to your key files. If you deploy your application to another computer, you must either copy your key files to the same absolute path or update the <securityCryptographyConfiguration> section of the computer's configuration source to reflect the new location.