Design of the Cryptography Application Block

This topic describes the design goals, design highlights, and the implementation of the Cryptography Application Block.

Design Goals

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

• Provide a simple and intuitive interface to the commonly required functionality. See Designing for Simplified Cryptography 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. See Designing for Algorithm Abstraction.
• Make sure the 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

The following schematic illustrates the 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 block is designed so you change the behavior of a cryptography provider without changing the application code.

The CryptographyManager class is a facade that mediates between the client code and the Cryptography Application Block's cryptographic functions. The client code calls methods on the CryptographyManager class to create hashes, compare hashes, encrypt data, and decrypt data. The CryptographyManager class uses the configuration data to determine the type of the provider to create.

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 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 block uses DPAPI to encrypt the keys. When your application executes, the 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.

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.