Design of the Cryptography Application Block of Enterprise Library

The Cryptography Application Block includes support for the following features:

• Encryption algorithms
• Hashing algorithms
• Multiple cryptography providers
• Additional implementations of cryptography providers
• Key protection with DPAPI

Design Goals

The Cryptography Application Block was designed to achieve the following goals:

Provide a simple and intuitive interface to the commonly required functionality.
Encapsulate the logic that is used to perform the most common application cryptography tasks.
Present a standard consistent model for common cryptography tasks, using common names for algorithms.
Make sure the application block is extensible.
Exert minimal or negligible performance impact compared to manually written cryptography code that accomplishes the same functionality.
Provide a key management model that can be customized to satisfy your organization's security requirements.

Design Highlights
Figure 1 illustrates the design of the Cryptography Application Block.

Figure 1
Design of the Cryptography Application Block

The Cryptography Application Block separates decisions about how cryptographic functions are implemented from how an application uses them. The application block is designed so you change the behavior of a cryptography provider without changing the application code.

The Cryptographer class is a façade that mediates between the client code and the Cryptography Application Block's cryptographic functions. The client code calls static methods on the Cryptographer class to create hashes, compare hashes, encrypt data, and decrypt data. Unless you are using the Unity Integration approach, each static method instantiates a factory class and passes the configuration source to the factory class's constructor. The factory uses the configuration data to determine the type of the provider to create.

Note:
If you use the Unity Integration approach to create instances of objects from the Cryptography Application Block, you must use the non-static façade named CryptographyManager. This class exposes the same API as the Cryptographer class static façade. For more information about using the Unity Application Block to create and inject instances of Enterprise Library objects, see Creating Objects Using the Unity Application Block.

The DpapiCryptographer class uses DPAPI to encrypt and decrypt data. DPAPI uses logon credentials to encrypt data. The logon credentials can either be a user's logon credentials or the local computer's logon credentials. If you use the local computer's logon credentials, DPAPI allows all applications that run under those credentials to decrypt that data. To counteract this, you can use an additional secret to protect the data. This additional secret is named entropy. The DpapiCryptographer class has overloads of the Encrypt and Decrypt methods that accept an entropy value.

Note:
Developers should be careful about how they store 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 SymmetricCryptographer class encapsulates provider implementations that derive from the abstract base class SymmetricAlgorithm, which is located in the .NET Framework's System.Security.Cryptography namespace. This means that you can use the SymmetricCryptographer class with any of the .NET Framework symmetric algorithms, such as the Rijndael symmetric encryption algorithm. The application block uses DPAPI to encrypt and decrypt the symmetric algorithm key.

Key Management Model
You use the configuration tools to select a cryptographic provider algorithm. If the algorithm requires a key, the configuration tools prompt you to select an existing key or to create a new key. When you create a new key, the configuration tools use the Cryptography Application Block to encrypt the key, and then store the encrypted key in its own text file. The application block uses DPAPI to encrypt the keys. When your application executes, the application block uses DPAPI to decrypt the key, and then it uses the key to encrypt or decrypt your data.

The Cryptography Application Block's design-time component includes the Cryptographic Key Wizard. You can use this wizard to either create a new key or to use an existing key. You use an existing key by selecting a file that contains a key encrypted with DPAPI. Typically, this is a key that you previously created with the configuration tools.

You can also use the configuration tools to export an existing key to a file. When you export a key, the configuration tools prompt you to supply a password to use to encrypt the key. The application block KeyManager class calls the KeyReaderWriter class to encrypt the key and create the file. The file contains a version number, salt value, and the encrypted key.

Finally, you can use the Cryptographic Key Wizard to import a previously-exported key. This means that if you must distribute the key to multiple computers, you can use the configuration tools to export your keys to an encrypted text file, transport the key file to the computers that require the key, and then use the configuration tools again to import the encrypted text file. When you import the encrypted key file, the configuration tools will prompt you for the password that you used to encrypt the file.

Introduction to the Cryptography Application Block

This topic includes a series of brief sections that provide information to help you decide if the Cryptography Application Block is suitable for your requirements. This topic includes the following sections:

Common Scenarios
Example Code
When to Use the Cryptography Application Block
Managing and Distributing Keys
Selecting an Algorithm
In addition to this introductory material, the documentation contains the following topics:

Developing Applications Using the Cryptography Application Block. This topic describes how to 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.
Key Scenarios. This topic then shows how to use the application block to perform most 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. It also contains information about configuration.
Cryptography QuickStart. This topic explains how to install and configure the QuickStart applications. It also contains a series of walkthroughs that demonstrate how to incorporate common cryptography operations into an application.
For details of the system requirements for the Cryptography Application Block, see System Requirements. For details of the dependencies for the Cryptography Application Block, see Application Block Dependencies.

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 the underlying providers through configuration 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 key to decrypt the message.

The Cryptography Application Block is designed to address most common tasks that developers face when they are writing applications that require cryptography functionality. These tasks have been arranged according to scenarios. Each scenario gives an example of a real-world situation, such as authenticating a user, discusses the cryptography functions that the situation requires, and shows the code that accomplishes the task.

The goal of arranging these tasks according to scenarios is to give the code some context. Instead of showing an isolated group of methods, with no sense of where they can best be used, scenarios provide a setting for the code, putting it in situations familiar to developers whose applications must use cryptography features.

The scenarios are the following:

Configuring cryptography
Encrypting data
Decrypting data
Getting a hash of data
Checking whether a hash matches some text