Administering Cryptography Settings

for RuBoard

The .NET Framework ships with a rich, fully extensible library of cryptography algorithm implementations . The .NET Framework ships with

  • Hash algorithms Included are the standard implementations of hash algorithms, such as SHA1, MD5, but also SHA256 and SHA512, in the System.Security.Cryptography namespace.

  • Symmetric algorithms The .NET Framework contains the standard implementations of DES and Triple DES, among other symmetric ciphers in the System.Security.Cryptography namespace.

  • Asymmetric algorithms The .NET Framework ships with the standard implementations of RSA and DSA, also in the System.Security.Cryptography namespace.

  • Class collection for doing XML digital signatures in the System.Security.Cryptography.XML namespace.

  • Finally, included in the .NET Framework are also a few classes to do rudimentary processing and work with x.509v3 publisher certificates, contained in the System.Security.Cryptography.X509Certificates namespace.

NOTE

To find out more about each of the cryptographical resources appearing in the previous bulleted list, please refer to Chapter 30, "Using Cryptography with the .NET Framework: The Basics," Chapter 31, "Using Cryptography with the .NET Framework: Advanced Topics," and Chapter 32, "Using Cryptography with the .NET Framework: Creating and Verifying XML Digital Signatures."


All of the cryptographic algorithms in System.Security.Cryptography are organized into a strict class hierarchy. For example, all hash algorithms derive from the abstract base class HashAlgorithm . All implementations of the SHA1 algorithm have to derive from the abstract base class SHA1 , which in turn derives from HashAlgorithm . This strict ordering from most generic cryptographic algorithm category to specific implementation is done for all symmetric and asymmetric algorithms as well. This class structure provides an easy and well-defined way to extend the cryptography library with other cryptographic algorithm implementations, but it also provides the backdrop for the cryptography configuration system.

The cryptography configuration system provides the following main features:

  • Every abstract base class for hash algorithms and symmetric and asymmetric algorithms can be queried for a default implementation instance.

  • You can query the cryptography configuration system directly to return a cryptography algorithm instance to you simply by supplying a friendly name .

Let us look at a few examples of these features. It is possible to ask the SHA1 base class to return a default instance of a SHA1 implementation. Unless cryptography configuration has been changed, this call will return an instance of the SHA1CryptoServiceProvider class, which in the default cryptography configuration settings has been deemed the standard SHA1 implementation. The following line of code shows how the default SHA1 implementation is created:

 SHA1 sha1alginstance = SHA1.Create(); 

A developer will not need to know exactly which SHA1 algorithm instance is returned (all SHA1 implementations have to implement a set of members defined by the SHA1 base class as well as the HashAlgorithm superclass). Nor will the developer need to know the syntax of how to instantiate that class. He or she asked the SHA1 base class for a SHA1 instance and got it.

The second feature is quite similar, although here the developer needs to supply the friendly name of an algorithm for which he or she wants to have an instance. The following line of code shows how you can get your hands on the default Triple DES implementation without having to explicitly know which algorithm in the cryptography library of the .NET Framework to instantiate:

 SymmetricAlgorithm 3des = CryptoConfig.CreateFromName("TripleDES"); 

Both features allow for the notion of a default implementation for cryptography algorithms. This provides developers with a way to work at a level that is abstracted away from a particular algorithm implementation. You may wonder why this is useful. The answer is that this allows you to seamlessly shift to a new library of cryptography algorithm implementations or the managed wrappers accessing newly purchased dedicated cryptography hardware without breaking any code. In either case, only a change to the default mappings of the respective cryptography algorithms is necessary.

Overview of the Cryptography Configuration Settings

The cryptography configuration system provides two types of mappings:

  • From friendly names to classnames that can be instantiated (this mapping is used by both features mentioned in the previous section)

  • From friendly names to the respective algorithm's assigned ASN.1 Object Identifier (OID) number

NOTE

ASN.1 is a binary serialization format that is used by some cryptographic object standards, such as X.509v3 certificates. In ASN.1, each cryptographic algorithm is associated with one or more Object Identifiers (OIDs). An OID is a dotted sequence of numbers ; for example, the OID that represents the SHA1 algorithm is "1.3.14.3.2.26." The configuration system provides name-to-OID mappings as part of the support for certain signature and key exchange formatting algorithms, such as RSAPKCS1. The only time you should have to change the OID mapping rules is when you add new cryptographic algorithms to the .NET Framework and want to use those algorithms with an existing ASN.1-based formatter.


The CryptoConfig class provides static methods for both of the previously discussed mapping forms. For example

 AsymmetricAlgorithm rsainstance = CryptoConfig.  CreateFromName  ("RSA"); 

The CreateFromName method looks up the friendly name in the "name to classname" table of the cryptography configuration system. The corresponding classname is used to load and instantiate that class by calling the default constructor of that class. The resulting instance is then returned by the configuration system.

Similarly, the following example illustrates how to obtain an OID string corresponding to a friendly name by calling the static MapNameToOID method on the CryptoConfig class:

 String oidstring = CryptoConfig.  MapNameToOID  ("SHA1"); 

Corresponding to these two mappings of friendly algorithm names (such as RSA ) are two cryptography configuration tables that are part of the configuration system that hold these mappings.

One table simply has columns for friendly names and corresponding fully qualified classnames. The other table has columns for friendly names and the corresponding OID numbers. The cryptography system ships with reasonable default values for both of these tables (see the "Default Mappings" section later in this chapter), but you can change the table to fit your or your organization's needs (such as changing the friendly name to classname mapping on installation of a dedicated cryptography device doing RSA encryption/descryption).

Default Mappings

Table 22.1 shows the default mappings between friendly algorithm names and classes in the .NET Framework. As will be shown in the "Modifying Cryptography Configuration" section later in this chapter, you can modify these mappings to set the default implementations of cryptography algorithms to other implementations in the .NET Framework cryptography library or to external implementations.

Table 22.1. Default Mappings Between Friendly Cryptography Algorithm Names and Classnames
Friendly Name Class Name
System.Security.Cryptography . System.Security.Cryptography .
HashAlgorithm SHA1CryptoServiceProvider
SHA System.Security.Cryptography. SHA1CryptoServiceProvider
SHA1 System.Security.Cryptography. SHA1CryptoServiceProvider
System.Security.Cryptography.SHA1 System.Security.Cryptography. SHA1CryptoServiceProvider
MD5 System.Security.Cryptography. MD5CryptoServiceProvider
System.Security.Cryptography.MD5 System.Security.Cryptography. MD5CryptoServiceProvider
SHA256 System.Security.Cryptography.SHA256Managed
SHA-256 System.Security.Cryptography.SHA256Managed
System.Security.Cryptography.SHA256 System.Security.Cryptography.SHA256Managed
SHA384 System.Security.Cryptography.SHA384Managed
SHA-384 System.Security.Cryptography.SHA384Managed
System.Security.Cryptography.SHA384 System.Security.Cryptography.SHA384Managed
SHA512 System.Security.Cryptography.SHA512Managed
SHA-512 System.Security.Cryptography.SHA512Managed
System.Security.Cryptography.SHA512 System.Security.Cryptography.SHA512Managed
RSA System.Security.Cryptography. RSACryptoServiceProvider
System.Security.Cryptography.RSA System.Security.Cryptography. RSACryptoServiceProvider
System.Security.Cryptography . System.Security.Cryptography .
AsymmetricAlgorithm RSACryptoServiceProvider
DSA System.Security.Cryptography. DSACryptoServiceProvider
System.Security.Cryptography.DSA System.Security.Cryptography. DSACryptoServiceProvider
DES System.Security.Cryptography. DESCryptoServiceProvider
System.Security.Cryptography.DES System.Security.Cryptography. DESCryptoServiceProvider
3DES System.Security.Cryptography. TripleDESCryptoServiceProvider
TripleDES System.Security.Cryptography. TripleDESCryptoServiceProvider
Triple DES System.Security.Cryptography. TripleDESCryptoServiceProvider
System.Security.Cryptography.TripleDES System.Security.Cryptography. TripleDESCryptoServiceProvider
System.Security.Cryptography . System.Security.Cryptography .
SymmetricAlgorithm TripleDESCryptoServiceProvider
RC2 System.Security.Cryptography. RC2CryptoServiceProvider
System.Security.Cryptography.RC2 System.Security.Cryptography. RC2CryptoServiceProvider
Rijndael System.Security.Cryptography. RijndaelManaged
System.Security.Cryptography.Rijndael System.Security.Cryptography. RijndaelManaged

As you can see in Table 22.1, there is often a many-to-one mapping between friendly names and classnames representing the default implementation of the respective algorithm. One example is the TripleDes algorithm; supplying either 3DES or Triple DES to the CreateFromName method on the CryptoConfig class will yield an instance of the TripleDESCryptoServiceProvider class. Table 22.1 also makes clear how various abstract base classes map to default implementations. The classname of the abstract base class is simply used as the friendly name in Table 22.1, the right column corresponding to the default implementation for that base class. For example, calling the Create() method on the HashAlgorithm class will return an instance of the SHA1CryptoServiceProvider class, as can be seen in the first line of the table. The base class simply calls the cryptography configuration system with its own classname as friendly name and sees if it can receive back a default implementation mapping. Thus, if you want to change the default implementation for hash algorithms, you only need to change the mapping for the friendly name System.Security.Cryptography.HashAlgorithm to a different classname from what is defined in the default mappings.

NOTE

A typical consumer of the cryptography configuration is, in fact, Caspol, the administration tool introduced in Chapter 19, "Administering .NET Framework Security Policy Using Scripts and Security APIs." When you use the hash algorithmname membership option, Caspol just calls the crypto configuration system with algorithmname to get back an algorithm instance mapping to the friendly hash algorithm you supplied.


Table 22.2 presents the default mapping for OIDs and friendly names.

Table 22.2. Default Mappings Between Friendly Cryptography Algorithm Names and OIDs
Friendly Name OID
SHA1 1.3.14.3.2.26
System.Security.Cryptography.SHA1 1.3.14.3.2.26
System.Security.Cryptography.SHA1CryptoServiceProvider 1.3.14.3.2.26
System.Security.Cryptography.SHA1Managed 1.3.14.3.2.26
SHA256 2.16.840.1.101.3.4.1
System.Security.Cryptography.SHA256 2.16.840.1.101.3.4.1
System.Security.Cryptography.SHA256Managed 2.16.840.1.101.3.4.1
SHA384 2.16.840.1.101.3.4.2
System.Security.Cryptography.SHA384 2.16.840.1.101.3.4.2
System.Security.Cryptography.SHA384Managed 2.16.840.1.101.3.4.2
SHA512 2.16.840.1.101.3.4.3
System.Security.Cryptography.SHA512 2.16.840.1.101.3.4.3
MD5 1.2.840.113549.2.5
System.Security.Cryptography.MD5 1.2.840.113549.2.5
System.Security.Cryptography.MD5CryptoServiceProvider 1.2.840.113549.2.5
System.Security.Cryptography.MD5Managed 1.2.840.113549.2.5
TripleDESKeyWrap 1.2.840.113549.1.9.16.3.6

Supplying any of the names in Table 22.2 to the static MapNameToOID function on the CryptoConfig class will return a string containing the respective OID number shown in the table.

Modifying Cryptography Configuration

The default settings introduced in the previous section should suffice for most use cases of the cryptography library of the .NET Framework. Typical scenarios in which you may want to change these settings include:

  • You have purchased a dedicated cryptography device for which you have a managed class wrapper from which to access the device.

  • You have written or obtained cryptography algorithm implementations other than the ones in the .NET Framework class.

  • You have good reason to change the default implementation for a base class to another class in the .NET Framework (for example, you may want to make SHA256Managed instead of SHA1CryptoServiceProvider the default hash algorithm).

When custom cryptography configuration settings are introduced into machine.config , the cryptography configuration system will first try to locate any mapping request in those user -supplied settings. However, if no match is found, the cryptography configuration system will try to find a match in the default mappings (see the "Default Mappings" section earlier in this chapter). Thus, the default mappings will always be available as fallback, and you only need to introduce mappings that either override default mappings or are not contained in the default mappings table.

To modify the mappings, perform the following steps:

  1. Find or create the machine.config file.

  2. Add your configuration mappings into the machine.config file.

  3. Save the machine.config file.

  4. Test your changes.

These steps will now be explained in more detail.

Finding machine.config

Cryptography configuration settings are part of the machine-wide configuration state that can be defined for the .NET Framework in the machine.config file. The file can be found at %WINDIR% \Micrsosoft.NET\Framework\v[. NETversion ]\Config\machine.config.

Depending on which operating system you are running, %WINDIR% will be the directory where the operating system had been installed, most commonly c:\Windows or c:\WINNT .

NOTE

The fastest way to find this file is by using the Search option under the Start menu, and typing in the filename machine.config .


Because machine.config is located under the Windows operating system directory, it receives the same ACL protections that other system resources have on a specific machine. By default, only machine administrators and power users will be able to change files under this directory, so machine.config is typically not modifiable by users without machine administrator rights.

This file is an XML file that is read by various core technologies of the .NET Framework. You can insert the cryptography configuration section into this file, which must adhere to a cryptography configuration XML schema (see the "Schema for Adding XML Configuration Settings" section later in this chapter). The default mappings (see the "Default Mappings" section earlier in this chapter) are not explicitly written into this file, but are implicit in the cryptography configuration system implementation. Consequently, you should not be surprised to find no cryptography configuration settings in this file when you edit it the first time. When reading the machine.config file, the cryptography configuration system goes through the following sequence of steps to determine what mappings should apply:

  1. Locate machine.config ; if not located, go to step 4.

  2. Find the <cryptographysettings> element in the machine.config file under the explicitly versioned <mscorlib> element matching the version of the .NET Framework CLR currently running. If successful, apply those settings; otherwise , go to step 3.

  3. Find the <cryptographysettings> element in the machine.config file under the <mscorlib> that has not been explicitly versioned. If found, apply those mappings. If no mapping match is found, proceed to step 4; otherwise, return the requested mapping.

  4. Apply the default mappings, as implemented in the cryptography configuration system itself.

These steps basically mean that you can configure cryptography mappings for different versions of the .NET Framework. If no cryptography configuration settings can be found in the machine.config file or the machine.config file does not exist, the cryptography configuration system will apply the default mappings as described earlier. For the v1.0 release of the .NET Framework, you will not have to worry about versioning your cryptography settings and should just include your cryptography configuration settings under the general <mscorlib> element as determined by the schema in the following section.

Adding Cryptography Settings

You will need to hand edit the machine.config file to change cryptography configuration mappings and then save the changed file. There is currently no tool support to help you change the cryptography default mappings. Listing 22.3 shows the general schema for adding cryptography settings to the machine.config file. All italicized items are explained after the schema definition. All items in bold belong to the metalanguage , defining properties of the schema and not being a literal part of the XML file. This means that the following symbols are just used to group and describe the schema in question; they will never appear in the actual XML files. The ( and ) symbols group schema expressions. The + symbol states that an expression can occur one or more times. // denotes a comment. All these symbols are used to talk about the specific symbols occurring in the cryptography configuration XML. They are used to define the grammar of all possible XML representations for cryptography configuration XML.

Listing 22.3 The Cryptography Configuration XML Schema
 <configuration>  //other configuration settings, ignore, do not modify!  <mscorlib>       <cryptographySettings>          <cryptoNameMapping>             <cryptoClasses>  (  <cryptoClass  classreferencename  ="  classnameinassembly,   assemblyname  Culture=  culturevalue,  PublicKeyToken=  strongnamepublickeytoken,  Version=  assemblyversion  "/>  )+  </cryptoClasses>  (  <nameEntry name="  friendlyname  " class="  classreferencename  "/>  )+  </cryptoNameMapping>  (  <oidMap>             <oidEntry OID="  OIDvalue  "  name="  friendlyname  "/> </oidMap>  )+  </cryptographySettings>    </mscorlib>  //other settings, ignore!  </configuration> 

The cryptography settings need to be inserted under the <mscorlib> element in the machine.config file. If no <mscorlib> element is in the machine.config file, you need to add that element yourself somewhere as a child element under the <configuration> element. All cryptography configuration information must be enclosed by the <cryptographySettings> element that is directly enclosed by the <mscorlib> element. The schema contains sections both for the friendly name to class mapping, delineated by the <cryptoNameMapping> and <oidMap> elements, respectively. The <cryptoNameMapping> section contains the <cryptoClasses> section. This section defines the class references for instantiating default implementations. An indefinite number of classes can be included in that section. Each class reference is expressed by a <cryptoClass> element, whose attributes determine the class reference. That reference is named by classreferencename , which is used as a shortcut within the configuration file. You should not confuse classreferencename with the friendly name ( friendlyname ). Each class reference is just the fully qualified type name of the class (please see the .NET Framework SDK for more help on this topic).

After the classes have been defined in the <cryptoClasses> section, an indefinite number of mappings between friendly names and classes occurs. Each mapping is represented by a <nameEntry> element, whose name attribute holds the friendly name ( friendlyname ), while the class attribute holds the name of the class reference ( classreferencename ) defined in the <cryptoClasses> section. Following the name mapping section ( <cryptoNameMapping> element scope) is the OID mapping, as represented by the <oidMap> element. Each OID mapping is denoted by an <oidEntry> element, whose OID attribute contains the OID string and whose name element contains the friendly name ( friendlyname reference). There can be an indefinite number of defined OID mappings.

All this may sound terribly complicated, but it is actually quite straightforward. The abbreviated example in Listing 22.4 will cause any requests to the default implementation of RSA or AsymmetricAlgorithm to be satisfied with an instance of a new RSA class implemented in the RSAAssembly . An OID mapping is also defined for this implementation.

NOTE

It is very important to note that the settings in Listing 22.4 will only override the RSA , System.Security.Cryptography.RSA , and System.Security.Cryptography.AssymetricAlgorithm entries of the default mappings defined in the configuration system. All other default mappings will still apply.

The fully qualified type names of classes shipping in the .NET Framework can be found in the .NET Framework SDKs class reference documentation for the respective class.


Listing 22.4 Example of Cryptography Configuration Settings in machine.config
 <configuration>  //various other config settings in machine.config  <mscorlib>       <cryptographySettings>          <cryptoNameMapping>             <cryptoClasses>                <cryptoClass NewRSA="RSADeviceClass, RSAAssembly                   Culture='en', PublicKeyToken=a2b42345f64568d,                   Version=1.0.0"/>             </cryptoClasses>             <nameEntry name="DeviceRSA" class="NewRSA"/>             <nameEntry name="RSA" class="NewRSA"/>         <nameEntry name="System.Security.Cryptography.RSA" class="NewRSA"/>         <nameEntry              name="System.Security.Cryptography.AsymmetricAlgorithm" class="NewRSA"/>          </cryptoNameMapping>          <oidMap>             <oidEntry OID="1.1.11.1.41.1"  name="NewRSA"/>          </oidMap>       </cryptographySettings>    </mscorlib> </configuration> 
Testing Cryptography Configuration Changes

After you have made your cryptography configuration changes, you should quickly test whether your settings map as expected. Because you have to hand edit XML to set state for the cryptography configuration system, it is easy to introduce an error. To test successful name mappings, simply use the CreateFromName method on the CryptoConfig object with the friendly names corresponding to name mappings you have changed or altered . Or to find out whether OID mapping changes were successful, simply use the MapNameToOID method on the CryptoConfig class. Listing 22.5 shows an example of testing whether the cryptography configuration changes introduced in Listing 22.4 were successful.

Listing 22.5 Testing Whether Cryptography Configuration Changes Were Successful cryptcfgtest.cs
 using System;  using System.IO;  using System.Security.Cryptography;  public class TestCryptoMapping  {      public static int Main()      {         //try and find a mapping for name "DeviceRSA" in crypto config         RSA rsadev = (RSA)CryptoConfig.CreateFromName("DeviceRSA");         //if not found print out error message          if(rsadev==null)              Console.WriteLine("DeviceRSA not found in Crypto config!");         //if found print out type name                 //of the class returned by crypto config             else              Console.WriteLine((rsadev.GetType()).AssemblyQualifiedName);         //try and find an Oid mapping in the crypto config settings         string Oid = CryptoConfig.MapNameToOID("NewRSA");         //if not found print error message          if (Oid==null)              Console.WriteLine(" NewRSA not found in Crypto config!");         //else print out return val from crypto config settings          else              Console.WriteLine("Crypt Config returned:"+Oid);         Console.WriteLine("Press ENTER to continue...");          string dummy = Console.ReadLine();          return 0;      } } 

The preceding sample code tests both whether the DeviceRSA name mapping works and, if so, what class gets returned from the cryptography configuration system. It also checks whether a mapping to an OID number for the NewRSA name exists.

for RuBoard


. NET Framework Security
.NET Framework Security
ISBN: 067232184X
EAN: 2147483647
Year: 2000
Pages: 235

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net