Mapping Algorithm Names to Cryptography Classes

There are four ways a developer can create a cryptography object using the Windows Software Development Kit (SDK):

• Create an object by using the new operator.

• Create an object that implements a particular cryptography algorithm by calling the Create method on the abstract class for that algorithm.

• Create an object that implements a particular cryptography algorithm by calling the System.Security.Cryptography.CryptoConfig.CreateFromName method.

• Create an object that implements a class of cryptographic algorithms (such as a symmetric block cipher) by calling the Create method on the abstract class for that type of algorithm (such as SymmetricAlgorithm).

For example, suppose a developer wants to compute the SHA1 hash of a set of bytes. The System.Security.Cryptography namespace contains two implementations of the SHA1 algorithm, one purely managed implementation and one that wraps CryptoAPI. The developer can choose to instantiate a particular SHA1 implementation (such as the SHA1Managed class) by calling the new operator. However, if it does not matter which class the common language runtime loads as long as the class implements the SHA1 hash algorithm, the developer can create an object by calling the System.Security.Cryptography.SHA1.Create method. This method calls System.Security.Cryptography.CryptoConfig.CreateFromName("System.Security.Cryptography.SHA1"), which must return an implementation of the SHA1 hash algorithm.

The developer can also call System.Security.Cryptography.CryptoConfig.CreateFromName("SHA1") because, by default, cryptography configuration includes short names for the algorithms shipped in the .NET Framework.

If it does not matter which hash algorithm is used, the developer can call the System.Security.Cryptography.HashAlgorithm.Create method, which returns an object that implements a hashing transformation.

Mapping Algorithm Names in Configuration Files

By default, the runtime returns a System.Security.Cryptography.SHA1CryptoServiceProvider class object for all four scenarios. However, a machine administrator can change the type of object that the methods in the last two scenarios return. To do this, you must map a friendly algorithm name to the class you want to use in the machine configuration file (Machine.config).

The following example shows how to configure the runtime so that System.Security.Cryptography.SHA1.Create, System.Security.CryptoConfig.CreateFromName("SHA1"), and System.Security.Cryptography.HashAlgorithm.Create return a MySHA1HashClass object.

<configuration>
   <!-- Other configuration settings. -->
   <mscorlib>
      <cryptographySettings>
         <cryptoNameMapping>
            <cryptoClasses>
               <cryptoClass MySHA1Hash="MySHA1HashClass, MyAssembly
                  Culture='en', PublicKeyToken=a5d015c7d5a0b012,
                  Version=1.0.0.0"/>
            </cryptoClasses>
            <nameEntry name="SHA1" class="MySHA1Hash"/>
            <nameEntry name="System.Security.Cryptography.SHA1"
                       class="MySHA1Hash"/>
            <nameEntry name="System.Security.Cryptography.HashAlgorithm"
                       class="MySHA1Hash"/>
         </cryptoNameMapping>
      </cryptographySettings>
   </mscorlib>
</configuration>

You can specify the name of the attribute in the <cryptoClass> element (the previous example names the attribute MySHA1Hash). The value of the attribute in the <cryptoClass> element is a string that the common language runtime uses to find the class. You can use any string that meets the requirements specified in Specifying Fully Qualified Type Names.

Many algorithm names can map to the same class. The <nameEntry> element maps a class to one friendly algorithm name. The name attribute can be either a string that is used when calling the System.Security.Cryptography.CryptoConfig.CreateFromName method or the name of an abstract cryptography class in the System.Security.Cryptography namespace. The value of the class attribute is the name of the attribute in the <cryptoClass> element.

Note
You can get an SHA1 algorithm by calling the System.Security.Cryptography.SHA1.Create or the Security.CryptoConfig.CreateFromName("SHA1") method. Each method guarantees only that it returns an object that implements the SHA1 algorithm. You do not have to map each friendly name of an algorithm to the same class in the configuration file.

For a list of default names and the classes they map to, see CryptoConfig Class.

See Also

Other Resources

Cryptographic Services

Configuring Cryptography Classes