Design of the Cryptography Application Block

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.

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.