Introduction to the Cryptography Application Block

The Microsoft Enterprise Library Cryptography Application Block simplifies how developers incorporate cryptographic functionality in their applications. Applications can use the application block for a variety of tasks, such as encrypting information, creating a hash from data, and comparing hash values to verify that data has not been altered.

The Cryptography Application Block has the following features:

• It reduces the requirement to write boilerplate code to perform standard tasks, providing implementations that you can use to solve common application cryptography problems.
• It helps maintain consistent cryptography practices, both within an application and across the enterprise.
• It eases the learning curve for developers by using a consistent architectural model across the various areas of functionality that are provided.
• It provides implementations that you can use to solve common application cryptography problems.
• It is extensible; supporting additional implementations of cryptography providers.

Common Scenarios

Developers frequently write applications that require encryption and hashing capabilities to meet the security requirements of their organization. Data that is created and maintained by applications, as well as configuration information, often needs to be encrypted. Additionally, passwords that are used to access application functionality or data need to be hashed.

The Cryptography Application Block simplifies the work of developers by abstracting application code from specific cryptography providers. You can change underlying providers through configuration changes without changing the underlying application code.

The Cryptography Application Block supports only symmetric algorithms. Symmetric algorithms use the same key for both encryption and decryption. The application block does not support asymmetric (also known as public-key) encryption, which uses one key to encrypt a message and another to decrypt the message.

Example Code

The following code shows how to encrypt and decrypt data. This code shows how to use the overloads that accept a string.

string encryptedContentsBase64 = Cryptographer.EncryptSymmetric("symmProvider", "SensitiveData");

// Decrypt the base64 encoded string
string readableString; 
readableString = Cryptographer.DecryptSymmetric("symmProvider", encryptedContentsBase64);

'Usage
Dim encryptedContentsBase64 As String
encryptedContentsBase64 = Cryptographer.EncryptSymmetric("symmProvider", "SensitiveData")

' Decrypt the base64 encoded string
Dim readableString As String
readableString = Cryptographer.DecryptSymmetric("symmProvider", encryptedContentsBase64)

Audience Requirements

This guide is intended for software architects, software developers, and policy makers. To benefit fully from this guide, you should understand the following technologies:

• Microsoft Visual Studio 2005 development system
• Microsoft .NET Framework 2.0

Migrating From Enterprise Library – June 2005

The Cryptography Application Block public API for hashing and encryption in this release is identical to the June 2005 release. This means that you do not need to modify your application code that uses this functionality when you upgrade to the January 2006 release. However, the implementation of custom providers, the management of keys, and the handling of configuration data has changed in Enterprise Library – January 2006. You must perform the following tasks when you upgrade your application:

• Migrate existing configuration information. The January 2006 release uses the application configuration file as the default storage location for the Cryptography Application Block configuration data. The June 2005 release stored the configuration data in the SecurityCryptographyConfiguration.config file. For a description of how to migrate your existing configuration information for use with Enterprise Library – January 2006, see Migration Information.
• Migrate existing custom providers. You must change existing custom providers to use the configuration classes in this release. For information about creating custom providers for this release, see Extending the Cryptography Application Block.
• Migrate existing keys. Earlier releases stored keys in the SecurityCryptographyConfiguration.config file. The January 2006 release stores each key in a separate file that you name using the Enterprise Library Configuration Console. The Data Protection API (DPAPI) encrypts the key in the file. The following procedure describes how to migrate existing keys.

To migrate existing keys

1. Open the application configuration file with the June 2005 release of the configuration console.
2. In the right pane, click the ellipsis button (…) in the Key property section. The Key Creation dialog box appears. Click Export Key. This will export the key to a text file.
3. In the Export Destination text box, enter the destination of the text file or click Browse and select the destination. Click OK.
4. Add a new cryptography provider of the same type as the one associated with the key you exported. For example, if you exported a key used by a RijndaelManaged symmetric provider, add a new RijndaelManaged symmetric provider. In this example, right-click Symmetric Provider, point to New, and then click Symmetric Algorithm Provider. In the Type Selector dialog box, click RijndaelManaged, and then click OK.
5. When the configuration console displays the Key Creation dialog box, click ImportKey.
6. In the Import Key dialog box, click the Browse button and select the key file that you created in step 3.
7. The configuration console displays a message to indicate that the key has been successfully imported. Click OK.
8. The configuration console displays the key in the Key Creation dialog box. Select the key and copy it to the clipboard.
9. Close the configuration console.
10. Use the January 2006 release of the configuration console to configure the Cryptography Application Block and to add a provider. The configuration console will launch the Cryptographic Key Wizard. For more information about configuring the Cryptography Application block, see Entering Configuration Information.
11. Click Create a new key, and then click Next.
12. In the text box, paste the key that you copied to the clipboard and click Next.
13. Click the ellipsis button (…) and browse to the location where you want to store the key, and then click Next.
14. Select either User mode or Machine mode, and then click Finish.

System Requirements

The requirements to run the Cryptography Application Block are the following:

• Microsoft Windows 2000, Windows XP Professional, or Windows Server 2003 operating system
• Microsoft .NET Framework 2.0
• Microsoft Visual Studio 2005 development system (any of the following editions):
  • Microsoft Visual Studio 2005 Standard Edition
  • Microsoft Visual Studio 2005 Professional Edition
  • Microsoft Visual Studio 2005 Team Edition for Software Developers
  • Microsoft Visual Studio 2005 Team Edition for Software Testers
  • Microsoft Visual Studio 2005 Team Edition for Software Architects
  • Microsoft Visual Studio 2005 Team Suite

Cryptography Application Block Dependencies

The Cryptography Application depends on other code included in the Enterprise Library:

• Core library functionality. The Enterprise Library Core provides services such as instrumentation and configuration and is a shared dependency of all Enterprise Library application blocks. The core library functionality is contained in the assembly Microsoft.Practices.EnterpriseLibrary.Common.dll.
• The ObjectBuilder subsystem. The ObjectBuilder subsystem performs all the repetitive and necessary tasks for creating and disposing of object instances, while still providing a high level of flexibility. Enterprise Library uses the ObjectBuilder subsystem for tasks such as injecting configuration into block classes and connecting instrumentation classes to application blocks. The ObjectBuilder subsystem is contained in the assembly Microsoft.Practices.ObjectBuilder.dll.

The recommended way to modify the configuration settings for the Cryptography Application Block is to use the Enterprise Library Configuration Console.

Cryptography Application Block Documentation

Together with the introduction, the documentation contains the following topics:

• Developing Applications with the Cryptography Application Block. This topic describes how to download and install the application block so that you can use it in your applications. It also describes how to configure the application block for common operations. The Key Scenarios subtopic then shows how to use the application block to perform the most typical cryptography tasks.
• Design of the Cryptography Application Block. This topic explains the decisions that went into designing the application block and the rationale behind those decisions.
• Extending and Modifying the Cryptography Application Block. This topic explains how to extend the application block by creating your own providers and how to modify the source code.
• Deployment and Operations. This topic explains how to deploy and update the application block's assemblies and also contains information about configuration.
• QuickStarts. This topic explains how to install and configure the QuickStart applications and contains a series of walkthroughs that demonstrate how to incorporate common cryptography operations into an application.

More Information

For more information, see the following resources:

• **Improving Web Application Security: Threats and Countermeasures
• Building Secure ASP.NET Applications: Authentication, Authorization, and Secure Communication
• patterns & practices Security Guidance for Applications Index