About the Cryptography Application Block
This page provides an overview of the Enterprise Library Cryptography Application Block. An application block is reusable and extensible source code-based guidance that simplifies development of common cryptographic functionality in .NET Framework applications.
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; it supports additional implementations of cryptography providers.
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 Application Code
The following code shows how to encrypt and decrypt data. This code shows how to use the overloads that accept a string.
[C#] string encryptedContentsBase64 = Cryptographer.EncryptSymmetric("symmProvider", "SensitiveData"); // Decrypt the base64 encoded string string readableString; readableString = Cryptographer.DecryptSymmetric("symmProvider", encryptedContentsBase64); [Visual Basic] Dim encryptedContentsBase64 As String encryptedContentsBase64 = Cryptographer.EncryptSymmetric("symmProvider", "SensitiveData") ' Decrypt the base64 encoded string Dim readableString As String readableString = Cryptographer.DecryptSymmetric("symmProvider", encryptedContentsBase64)
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.
- Make sure the application block is extensible.
- Make sure minimal or negligible performance impact compared to manually written cryptography code that accomplishes the same functionality.
- Provide a key protection model that can be customized to satisfy your organization's security requirements.
The following diagram 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. 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.
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.
The Cryptography Application Block has been developed as a result of analyzing common enterprise development challenges and successful solutions to these challenges. However, because each application is unique, you will not find this application block suitable for every application. To evaluate this application block and determine its applicability to your projects, Microsoft suggests you dedicate at least half of a day to explore the application block. The following is a suggested evaluation approach:
- Download Enterprise Library.
- Install Enterprise Library and compile all application blocks and tools.
- Read the "Introduction" and "Scenarios and Goals" sections of the documentation.
- Compile and run the QuickStart samples, and read through the related "QuickStart Walkthroughs" and "Key Scenarios" sections of the documentation.
- If the application block looks like a good fit for your application, try implementing a simple use case in your application or in a throw-away prototype application using the application block.
Enterprise Library, like many patterns & practices deliverables, is associated with a community site. On this community site, you can post questions, provide feedback, or connect with other users for sharing ideas. Community members can also help Microsoft plan and test future deliverables, and download additional content such as extensions and training material.
Questions? Comments? Suggestions? To provide feedback about this application block, or to get help with any problems, please visit the Enterprise Library Community site. The community site is the preferred feedback and support channel because it allows you to share your ideas, questions, and solutions with the entire community.
Enterprise Library is a guidance offering, designed to be reused, customized, and extended. It is not a Microsoft product. Code-based guidance is shipped "as is" and without warranties. Customers can obtain support through Microsoft Support Services for a fee, but the code is considered user-written by Microsoft support staff. For more information about our support policy, see the Enterprise Library home page.
- Improving Web Application Security: Threats and Countermeasures
- patterns & practices Security Guidance for Applications Index
- Enterprise Library