Introduction to 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. |
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
For more information about each of these scenarios, see Key Scenarios.
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 = Cryptographer.EncryptSymmetric("symmProvider", "SensitiveData")
' Decrypt the base64 encoded string
Dim readableString As String = Cryptographer.DecryptSymmetric("symmProvider", encryptedContentsBase64)
When to Use the Cryptography Application Block
You should use the Cryptography Application Block when you need hashing and/or symmetric encryption functionality. You can use these functions in conjunction with the cryptographic providers included with the application block or with your own custom cryptographic providers. If the data only needs to be encrypted, and it does not need to be decrypted (for example, a password), you can use hashing. If the data needs to be both encrypted and decrypted (for example, to transmit sensitive customer data), you can use symmetric encryption.
A prerequisite for symmetric encryption is that the application that sends the data and the application that receives the data trust one another. Typically, this is only true if the sender and the receiver are the same application. This restriction often precludes using the application block for encrypting data across the network. Two other points you should consider when you use the Cryptography Application Block are how you are going to manage symmetric encryption keys and which hashing algorithm or symmetric encryption algorithm you are going to use.
Managing and Distributing Keys
Symmetric encryption encrypts and decrypts data with the same key. Both the application that sends the data and the application that receives the data must possess this key. Any other application that can access this key can also decrypt the data that was encrypted with the key. This means that attackers can decrypt encrypted data if they can obtain the encryption key. Also, attackers can prevent you from reading your encrypted data by deleting or corrupting your key file. A key file is an encrypted text file that contains your keys. You must carefully manage your shared keys. Consider the following guidelines to help you protect your keys:
- Protect your keys with access control lists (ACL). Only grant the necessary permissions to the identities that require access to the key file.
- Do not configure your computer to allow remote debugging when that computer runs in a high-risk environment. An example of such a computer is a Web server that allows anonymous access.
The Cryptography Application Block stores each key in a separate file on the local computer. The <securityCryptographyConfiguration> section in the configuration source contains the absolute path to each key file. For example, when you use the default configuration source, the application configuration file contains the absolute path to the keys. To protect the key, the application block uses DPAPI to encrypt it before it writes it to the file. If you also use entropy, you must protect the storage location of the entropy value. (Entropy is a random value that makes deciphering the file more difficult.) For example, you can use ACLs to set permissions on a file that contains the entropy value. If your application requires you to use an alternative form of key management, such as specialized hardware or a key container, you must modify the application block source code to support your requirements. For information about modifying the application block, see Modifying the Cryptography Application Block.
The application block does not completely address the issue of how you can safely distribute your keys. It is relatively easy to safely distribute keys on your own secured computers. Other situations, such as sharing multiple keys between multiple parties, require careful planning. One approach is to use the Enterprise Library configuration tools to export your keys to a key file before you distribute them. The key file is encrypted with a password that you supply when you export the keys. You can transport the key file to the computer that requires the keys and then use the configuration tools to import the encrypted key file. When you import the encrypted key file, the configuration tools will prompt you for the password that you used when you encrypted the file.
Selecting an Algorithm
An encryption algorithm provides no security if the encryption algorithm is cracked or is vulnerable to brute force cracking. Custom algorithms are particularly vulnerable if they have not been tested. Instead, use published, well-known encryption algorithms that have withstood years of rigorous attacks and scrutiny.
Recommended key lengths change as computing power grows. Encryption key lengths that range from 128 bits to 256 bits are currently considered to be secure. Most modern algorithms use keys that are at least 128 bits long.
For hashing algorithms, the SHA256Managed algorithm is recommended. This algorithm uses a hash size of 256 bits. The hash size of SHA1Managed hashing algorithm is 160 bits. This algorithm is acceptable but not encouraged. The MD4 and MD5 algorithms are no longer recommended.
For symmetric algorithms, AES, also known as Rijndael, is recommended. This algorithm supports key lengths of 128, 192, 256 bits. The DES algorithm is not recommended.