.NET Security Blog : Cryptography

Authenticated Symmetric Encryption in .NET

shawnfa — Tue, 17 Mar 2009 23:48:20 GMT

Over the last week, we've made a couple of updates to our Codeplex projects to add authenticated symmetric encryption to the managed cryptography surface area for the first time. Since we've never supported authenticated symmetric algorithms in managed code before, I thought I'd run though some basics about what they are and how to use them.

For starters, in order to use the authenticated symmetric encryption classes, you'll need a few prerequisites:

Windows Vista SP 1, Windows Server 2008, or higher
.NET framework v3.5 SP 1 or higher
Security.Cryptography.dll 1.3 or higher (from http://codeplex.com/clrsecurity)

Authenticated symmetric cryptography differs from the symmetric cryptography that the .NET framework has traditionally supported in that it produces an authentication tag in addition to ciphertext when encrypting data. This authentication tag can be used to verify that the ciphertext has not been tampered with between when it was encrypted and decrypted.

For example, imagine you encrypted a message using the AES class:

using (Aes aes = new AesCng())
{
    aes.Key = key;
    aes.IV = iv;
 
    using (MemoryStream ms = new MemoryStream())
    using (CryptoStream cs = new CryptoStream(ms, aes.CreateEncryptor(), CryptoStreamMode.Write))
    {
        byte[] plaintext = Encoding.UTF8.GetBytes("Secret data to be encrypted.");
        cs.Write(plaintext, 0, plaintext.Length);
        cs.FlushFinalBlock();
 
        return ms.ToArray();
    }
}

While an attacker cannot read the data encrypted by this operation without knowing the encryption key, they can modify the ciphertext bytes themselves which will result in corruption of the decrypted message on the receiving end:

// The ciphertext is protected from being decrypted without knowledge of the key, however it
// is not protected from being tampered with:
ciphertext[5] = 0x21;
 
using (Aes aes = new AesCng())
{
    aes.Key = key;
    aes.IV = iv;
 
    using (MemoryStream ms = new MemoryStream())
    using (CryptoStream cs = new CryptoStream(ms, aes.CreateDecryptor(), CryptoStreamMode.Write))
    {
        cs.Write(ciphertext, 0, ciphertext.Length);
        cs.FlushFinalBlock();
 
        byte[] decrypted = ms.ToArray();
        string message = Encoding.UTF8.GetString(decrypted);
        Console.WriteLine(message);
    }
}

Which produces output such as:

? ]\??e enc?ypted.

This can be solved by signing the ciphertext, and having the receiving party verify the signature before decrypting the secret message.

Authenticated symmetric algorithms solve this problem by creating an authentication tag which can be used to verify that the ciphertext has not been tampered with since it was generated.

In addition to verifying that the ciphertext has not been modified, the authenticated symmetric algorithms that we have in managed code also take additional authenticated data as an input. This data is not included in the ciphertext itself - so when decrypting a message that was created with additional authenticated data, the output will not contain the authenticated data. Instead, the authenticated data is only used in generating the authentication tag. This means that much like the key and IV, both the encrypting and decrypting parties need to know what the additional authenticated data is otherwise the authentication tag will not verify.

Authenticated Symmetric Algorithm Type Hierarchy

This functionality is exposed in managed code via the AuthenticatedSymmetricAlgorithm base class. Much like the SymmetricAlgorithm base class, AuthenticatedSymmetricAlgorithm is an abstract class for actual authenticated symmetric algorithms to derive from.

Currently, the only authenticated symmetric algorithm is an authenticated version of AES, which is represented by the AuthenticatedAes abstract base class. Again, mirroring the symmetric algorithm type hierarchy, AuthenticatedAes is an abstract base class that concrete authenticated AES implementations derive from. (Much like Aes serves as the base class for AesManaged, AesCryptoServiceProvider and AesCng).

The concrete implementation of AuthenticatedAesCng which is in Security.Cryptography.dll 1.3 is built on top of CNG, and follows our traditional naming scheme: AuthenticatedAesCng.

Setting up an Authenticated AES Encryptor

The authentication tag is generated by an authenticated chaining algorithm, which is used in place of the standard chaining modes that AES can use (such as CBC or ECB). Currently CNG supports two algorithms for generating an authentication tag with AES:

Galois/Counter Mode - this is the default, and is represented by CngChainingMode.Gcm. (http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf)
Coutner with CBC-MAC - this is selected by using CngChainingMode.Ccm. (http://www.ietf.org/rfc/rfc3610.txt)

Since neither of these chaining modes are supported by the standard CipherMode enumeration, AuthenticatedAesCng adds a new property called CngMode which allows you to specify a CngChainingMode rather than a standard CipherMode. Trying to use the traditional Mode property when the CngChainingMode is set to one of these new values will result in an exception.

The IV property is used to setup what the two algorithm specifications above refer to as a nonce. Unlike traditional AES, the IV size does not match the block size, but is instead specified by the chaining mode. For instance, both GCM and CCM can work with an IV of 12 bytes.

AuthenticatedSymmetricAlgorithms also have an AuthenticatedData byte array property which is used to setup the additional authentication data being used in the tag generation. This property is optional - leaving the value null means that the authentication tag is generated only from the plaintext.

The last interesting property on the encryption side is the TagSize property. This property specifies the size (in bits) of the authentication tag to generate. The LegalTagSizes property contains information about which sizes are valid for the current chaining mode (and the ValidTagSize method allows you to quickly test to see if a tag size is valid).

Once the AuthenticatedAesCng object is setup, we'll need to create an encryptor to do the actual encryption operation. This can be done by calling the CreateAuthenticatedEncryptor method. CreateAuthenticatedEncryptor returns an IAuthenticatdCryptoTransform rather than an ICryptoTransform since IAuthenticatedCryptoTransform allows us access to the authentication tag after the encryption is done. The CreateEncryptor overloads also return IAuthenticatedCryptoTransforms, however they are typed as ICryptoTransform because they're defined on the SymmetricAlgorithm base type. If you call one of the these methods, then you'll have to manually cast to IAuthenticatedCryptoTransform.

Putting this all together, code to encrypt and generate an authentication tag using AuthenticatedAesCng would look something like this:

using (AuthenticatedAesCng aes = new AuthenticatedAesCng())
{
    // Setup an authenticated chaining mode - The two current CNG options are
    // CngChainingMode.Gcm and CngChainingMode.Ccm.  This should be done before setting up
    // the other properties, since changing the chaining mode can update things such as the
    // valid and current tag sizes.
    aes.CngMode = CngChainingMode.Ccm;
 
    // Keys work the same as standard AES
    aes.Key = key;
 
    // The IV (called the nonce in many of the authenticated algorithm specs) is not sized for
    // the input block size. Instead its size depends upon the algorithm.  12 bytes works
    // for both GCM and CCM. Generate a random 12 byte nonce here.
    nonce = new byte[12];
    rng.GetBytes(nonce);
    aes.IV = nonce;
 
    // Authenticated data becomes part of the authentication tag that is generated during
    // encryption, however it is not part of the ciphertext.  That is, when decrypting the
    // ciphertext the authenticated data will not be produced.  However, if the
    // authenticated data does not match at encryption and decryption time, the
    // authentication tag will not validate.
    aes.AuthenticatedData = Encoding.UTF8.GetBytes("Additional authenticated data");
 
    // Perform the encryption - this works nearly the same as standard symmetric encryption,
    // however instead of using an ICryptoTransform we use an IAuthenticatedCryptoTrasform
    // which provides access to the authentication tag.
    using (MemoryStream ms = new MemoryStream())
    using (IAuthenticatedCryptoTransform encryptor = aes.CreateAuthenticatedEncryptor())
    using (CryptoStream cs = new CryptoStream(ms, encryptor, CryptoStreamMode.Write))
    {
        // Encrypt the secret message
        byte[] plaintext = Encoding.UTF8.GetBytes("Secret data to be encrypted and authenticated.");
        cs.Write(plaintext, 0, plaintext.Length);
 
        // Finish the encryption and get the output authentication tag and ciphertext
        cs.FlushFinalBlock();
        tag = encryptor.GetTag();
        ciphertext = ms.ToArray();
    }
}

Notice how the tag is accessed by calling GetTag on the IAuthenticatedCryptoTransform after we've completed all encryption and flushed the final block. If GetTag is called before this, it will throw an InvalidOperaitonException as AuthenticatedAesCng does not support generating partial tags for partially encrypted data. Also, encryption will notably not set the Tag property of the AuthenticatedAesCng object which was used to create the encryptor. (The tag is an output, not an input, and therefore does not get propagated back to the AuthenticatedAesCng object which acts like a crypto transform factory).

Setting up an Authenticated AES Decryptor

Setting up an authenticated AES object to do decryption is very similar to setting one up to do encryption. The Key, IV, AuthenticationData, and CngMode all need to be setup to match the parameters in place when the ciphertext being decrypted was encrypted. The only additional property that needs to be set is the Tag property. Unsurprisingly, this should be set to be the output of the GetTag call on the encryptor.

We'll end up with decryption code along the lines of:

// To decrypt, we need to know the nonce, key, additional authenticated data, and
// authentication tag.
using (AuthenticatedAesCng aes = new AuthenticatedAesCng())
{
    // Chaining modes, keys, and IVs must match between encryption and decryption
    aes.CngMode = CngChainingMode.Ccm;
    aes.Key = key;
    aes.IV = nonce;
 
    // If the authenticated data does not match between encryption and decryption, then the
    // authentication tag will not match either, and the decryption operation will fail.
    aes.AuthenticatedData = Encoding.UTF8.GetBytes("Additional authenticated data");
 
    // The tag that was generated during encryption gets set here as input to the decryption
    // operation.  This is in contrast to the encryption code path which does not use the
    // Tag property (since it is an output from encryption).
    aes.Tag = tag;
 
    // Decryption works the same as standard symmetric encryption
    using (MemoryStream ms = new MemoryStream())
    using (CryptoStream cs = new CryptoStream(ms, aes.CreateDecryptor(), CryptoStreamMode.Write))
    {
        cs.Write(ciphertext, 0, ciphertext.Length);
 
        // If the authentication tag does not match, we'll fail here with a
        // CryptographicException, and the ciphertext will not be decrypted.
        cs.FlushFinalBlock();
 
        byte[] plaintext = ms.ToArray();
        Console.WriteLine("Decrypted and authenticated message: {0}", Encoding.UTF8.GetString(plaintext));
    }
}

If the authentication tag generated while decrypting the ciphertext (taking into account any optional authenticated data provided), then an exception will be thrown when decryption is completed. The decryptor will also not produce any plaintext until the authentication tag is verified - this way partial plaintext cannoot be used if the authentication tag does not match.

Now that we're using AuthenticatedAesCng to do our encryption, the scenario where someone tampers the ciphertext no longer works. While we won't be able to access the corrupted plaintext anymore, we also will be unable to mistake it for valid plaintext. If the authentication tag does not match while decrypting (most commonly because the ciphertext was tampered with or the authenticated data was not correct), the following exception is thrown:

Unhandled Exception: System.Security.Cryptography.CryptographicException: The computed authentication tag did not match the input authentication tag.

   at Security.Cryptography.BCryptNative.SymmetricDecrypt(SafeBCryptKeyHandle key, Byte[] input, Byte[] chainData, BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO& authenticationInfo)
   at Security.Cryptography.BCryptAuthenticatedSymmetricCryptoTransform.CngTransform(Byte[] input, Int32 inputOffset, Int32 inputCount)
   at Security.Cryptography.BCryptAuthenticatedSymmetricCryptoTransform.TransformFinalBlock(Byte[] inputBuffer, Int32 inputOffset, Int32 inputCount)
   at System.Security.Cryptography.CryptoStream.FlushFinalBlock()

Security.Cryptography.Debug Support

The Security.Cryptography.Debug library has also been updated on the Codeplex in order to support the same type of debugging of AuthenicatedSymmetricAlgorithm objects that was already supported for SymmetricAlgorithm objects. This support is enabled in the v1.1 release and higher of Security.Cryptography.Debug.dll - but since it requires a dependency on the Security.Cryptography.dll library, it is not enabled in the FxOnly builds. Instead, you'll need to download the full binary package or build the sources manually to get the AuthenticatedSymmetricAlgorithm debugging support.

MD5 on Silverlight

shawnfa — Wed, 10 Dec 2008 04:39:03 GMT

Reid Borsuk, an SDE/T on the CLR security team, has released a fully transparent implementation of the MD5 hash algorithm to the MSDN Code Gallery. Since the code is entirely transparent, it can be used as part of a Silverlight application that needs to compute MD5 hashes in order to interop with existing code or file formats that requires MD5.

He's also released an MD5Managed type to wrap around his implementation, in case you want to plug the algorithm into the standard .NET hash object model.

CryptoConfig

shawnfa — Wed, 03 Dec 2008 01:26:23 GMT

The crypto config schema has been a bit of a hot topic around here lately, specifically around how to modify the CLR's machine.config to get custom crypto types registered with CryptoConfig.

Let's take a quick look at what CryptoConfig is first, and then we'll see how to customize its behavior. CryptoConfig is a type in mscorlib which allows cryptography classes to be created from a string rather than using a hard coded type. For instance, you can say:

HashAlgorithm hashAlgorithm = CryptoConfig.CreateFromName("SHA256Managed") as HashAlgorithm;

to create instances of crypto types. This means that rather than having to hard code algorithms and implementations into your assembly itself, you can accept the name of the algorithm as a configuration parameter to achieve some measure of crypto agility. CryptoConfig is also the underlying mechanism that allows the algorithm factory methods to work. For instance, the above snippet is more commonly written as:

HashAlgorithm hashAlgorithm = HashAlgorithm.Create("SHA256Managed");

CryptoConfig comes built in with names of algorithms that ship with the .NET Framework (with the exception of the new algorithms introduced in .NET 3.5 due to red bits / green bits restrictions). You can also extend the names that CryptoConfig understands if you have your own algorithms that you would like to be createable by name. In fact, you can even do this to get the .NET 3.5 algorithms registered.

The customizable algorithm name mappings are setup in the machine.config file in the config subdirectory of the CLR installation directory. For instance, for the 32 bit .NET 2.0, 3.0, and 3.5 releases you would register your types in the %WINDIR%\Microsoft.NET\Framework\v2.0.50727\config\machine.config file. (For the 64 bit versions, you would also need to modify the equivalent file in Framework64).

CryptoConfig looks for information in the configuration/mscorlib/cryptographySettings element of machine.config. If there are multiple mscorlib sections, then crypto config prefers one with a version attribute that matches the current runtime -- however, in general there is only one mscorlib element.

<configuration>
    <mscorlib>
        <cryptographySettings>
            <cryptoNameMapping>                
                <!-- name mappings -->
            </cryptoNameMapping>
            <oidMap>
                <!-- OID mappings -->
            </oidMap>
        </cryptographySettings>
    </mscorlib>
</configuration>

Name mappings are created in a nameMappings element under cryptographySettings. In order to setup a name mapping, two steps are required:

Map the implementation type to an alias by registering it as a crypto class
Map the alias to the name that you wish to use in CryptoConfig to create an instance of the class.

For example, imagine that you want to register the SHA256CryptoServiceProvider type that shipped in .NET 3.5 to be able to be created with the strings "SHA256", "SHA256CryptoServiceProvider", and "System.Security.Cryptography.SHA256ServiceProvider". The first step is to register SHA256CryptoServiceProvider as a crypto class. We can do this by creating a cryptoClasses node within the cryptoNameMapping element:

<cryptoClasses>
    <cryptoClass
        SHA256CSP="System.Security.Cryptography.SHA256CryptoServiceProvider, System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
</cryptoClasses>

This creates an alias of SHA256CSP that refers to the SHA256CryptoServiceProvier type in System.Core.dll. Note that the assemblies used in CryptoConfig must reside in the GAC; in this case System.Core.dll is in the GAC so registering SHA256CryptoServiceProvider is valid.

Now that we have created an alias we need to setup some names to create it with at runtime. These names are created using nameEntry elements in the cryptoNameMapping element:

<nameEntry
    name="SHA256"
    class="SHA256CSP" />
<nameEntry
    name="SHA256CryptoServiceProvider"
    class="SHA256CSP" />
<nameEntry
    name="System.Security.Cryptography.SHA256CryptoServiceProvider"
    class="SHA256CSP" />

Each nameEntry element maps a string which CryptoConfig will accept to the alias for the type that it will create. Here, we've setup entries that allow CryptoConfig to create a SHA256CryptoServiceProvier object via the names "SHA256", "SHA256CryptoServiceProvider", and "System.Security.Cryptography.SHA256CryptoServiceProvider".

If you're paying close attention, you'll notice that I mapped SHA256 to the .NET 3.5 SHA256CryptoServiceProvider class, even though the CLR already has a built in mapping for SHA256 to the SHA256Managed class. In the case of a collision like this, machine.config entries take precedence over the built in mappings so these entries have the effect of changing the result of HashAlgorithm.Create("SHA256") from being a SHA256Managed object to being a SHA256CryptoServiceProvider object.

The final XML we ended up with for this example looks like this:

<configuration>
    <!-- ... other configuration data ... -->
    <mscorlib>
        <!-- ... other configuration data ... -->
        <cryptographySettings>
            <cryptoNameMapping>
                <cryptoClasses>
                    <cryptoClass
                        SHA256CSP="System.Security.Cryptography.SHA256CryptoServiceProvider, System.Core, Version=3.5.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
                </cryptoClasses>
                    <nameEntry
                        name="SHA256"
                        class="SHA256CSP" />
                    <nameEntry
                        name="SHA256CryptoServiceProvider"
                        class="SHA256CSP" />
                    <nameEntry
                        name="System.Security.Cryptography.SHA256CryptoServiceProvider"
                        class="SHA256CSP" />
            </cryptoNameMapping>
        </cryptographySettings>
    </mscorlib>
</configuration>

A couple of other small crypto config notes:

Above I mentioned that there is the ability to setup OID mappings - this allows you to add entries to the results returned from the CryptoConfig.MapNameToOid API. These entries go in the oidMap element and are simple name -> OID pairs. Like name map entries above, machine.config values take precedence over built-in values:

<oidMap>
    <oidEntry
        OID="2.16.840.1.101.3.4.2.1"
        name="SHA256" />
</oidMap>

Generally this is much less useful than the name mappings, since it really only allows you to access your custom OIDs via MapNameToOid -- however it's there if you do want to add custom name->OID pairs.

A final note is that although CryptoConfig itself doesn't have an API to modify the mappings at runtime, it is sometimes a lot more convenient to programmatically add crypto name mappings for your application at runtime than to worry about getting all the machine.config XML correctly added at installation time. This can be done with the CryptoConfig2 class from the Security.Cryptography library on CodePlex.

CryptoConfig2 already has mappings for the .NET 3.5 types, but for the sake of an example the registration from the XML above could be done via code such as:

CryptoConfig2.AddAlgorithm(typeof(SHA256CryptoServiceProvider),
                           "SHA256",
                           "SHA256CryptoServiceProvider",
                           "System.Security.Cryptography.SHA256CryptoServiceProvider");

Since CryptoConfig2 does not modify the built-in CryptoConfig mappings, these aliases would be used like this:

HashAlgorithm hashAlgorithm = CryptoConfig2.CreateFromName("SHA256") as HashAlgorithm;

instead of going through the built in CryptoConfig or Create methods.

Using RSACryptoServiceProvider for RSA-SHA256 signatures

shawnfa — Mon, 25 Aug 2008 21:09:59 GMT

Earlier this month, we released .NET 3.5 SP 1. One of the new features available in this update is that RSACryptoServiceProvider has gained the ability to create and verify RSA-SHA256 signatures.

Since RSACryptoServiceProvider relies on the underlying CAPI APIs to do its work, this feature will only be enabled on versions of Windows which support SHA-256 algorithms in CAPI. At this point, that translates to Windows Server 2003 and higher.

The code to create and verify a signature is basically the same as it was for doing RSA-SHA1:

byte[] data = new byte[] { 0, 1, 2, 3, 4, 5 };
using (RSACryptoServiceProvider rsa = new RSACryptoServiceProvider())
{
    byte[] signature = rsa.SignData(data, "SHA256");
 
    if (rsa.VerifyData(data, "SHA256", signature))
    {
        Console.WriteLine("RSA-SHA256 signature verified");
    }
    else
    {
        Console.WriteLine("RSA-SHA256 signature failed to verify");
    }
}

The second parameter should be either the string "SHA256", the type of the SHA256Managed object, or an instance of a SHA256Managed object.

Note that this means, somewhat counter-intuitively, that passing either the type of or an instance of the SHA256CryptoServiceProvider object will not work. If you do use the SHA256CryptoServiceProvider type, you'll end up with an error like this:

Unhandled Exception: System.ArgumentException: Value was invalid.
   at System.Security.Cryptography.Utils.ObjToOidValue(Object hashAlg)
   at System.Security.Cryptography.RSACryptoServiceProvider.SignData(Byte[] buffer, Object halg)

The reason for this is the same reason that CryptoConfig does not understand SHA256CryptoServiceProvider - it was added as part of the green bits in .NET 3.5, and due to layering restrictions the red bits (such as mscorlib.dll where RSACryptoServiceProvider lives) does not know about its existence.

Also note that this functionality was added only to the RSACryptoServiceProvider type, so upstack functionality such as XML digital signatures are not yet enabled for RSA-SHA256 digital signatures. However, this does provide the base building block for those upstack crypto technologies, so that they can begin adding support in the future.

CLR Security Team CodePlex Site

shawnfa — Thu, 10 Jul 2008 22:20:59 GMT

The CLR Security Team just launched our CodePlex site: http://www.codeplex.com/clrsecurity. Currently, it contains two assemblies that provide additional functionality to the security APIs shipped in v3.5 of the .NET Framework.

We'd love your feedback on the currently offered libraries, and also welcome ideas for other libraries you'd like to see on our CodePlex site.

From the description page on the site, the two current libraries are:

Security.Cryptography.dll

Security.Cryptography.dll provides a new set of algorithm implementations to augment the built in .NET framework supported algorithms. It also provides some APIs to extend the existing framework cryptography APIs. Within this project you will find:

A CNG implementation of the AES, RSA, and TripleDES encryption algorithms
A CNG implementation of a random number generator
A class that allows dynamically creating algorithms both from this library as well as all of the algorithms that ship with .NET 3.5
An enumerator over all of the installed CNG providers on the current machine
Extension methods that allow access to all of the keys installed in a CNG provider, as well as all of the algorithms the provider supports

Security.Cryptography.Debug.dll

Have you ever run into an indecipherable cryptographic exception complaining about "Padding is invalid and cannot be removed" when using the .NET Framework's symmetric algorithms? Since nearly all bugs relating to symmetric algorithms tend to result in this same exception, it can be incredibly difficult to track down exactly what went wrong to cause the exception. Security.Cryptography.Debug.dll is a tool that can be used in these circumstances in order to help you figure out the root cause of your cryptographic exception.

Disabling the FIPS Algorithm Check

shawnfa — Fri, 14 Mar 2008 17:00:23 GMT

.NET 2.0 introduced a check for FIPS certified algorithms if your local security policy was configured to require them. This resulted in algorithms which are not FIPS compliant (or implementations which were not FIPS certified) throwing an InvalidOperationException from their constructors.

In some cases this isn't a desirable behavior. For instance, some applications need to use the MD5 hashing algorithm for compatibility with an older communication protocol or file format. Prior to .NET 3.5, the AES algorithm was only available in an implementation which was not FIPS certified, and if you needed to use that algorithm the FIPS check could also block you.

To help these cases, we added a configuration file switch to .NET 2.0 SP 1 (and therefore .NET 3.5) which allows an application to say "I know what I'm doing, please don't enforce FIPS for me". For these applications, they can setup a configuration file similar to:

<configuration>

    <runtime>

        <enforceFIPSPolicy enabled="false"/>

    </runtime>

</configuration>

Which will prevent the CLR from throwing InvalidOperationExceptions from the constructor of uncertified algorithms and implementations.

CLR Inside Out: Digging into IDisposable

shawnfa — Wed, 20 Jun 2007 19:10:09 GMT

My third MSDN magazine article, Digging into IDisposable, appeared in this month's issue in the CLR Inside Out Column. It's a bit of a departure from my usual security fare; this time looking at how to best handle writing class libraries that must manage resources.

Also in this month's issue, Kenny Kerr provides a good introduction to the new CNG APIs available on Vista. Especially interesting is the code snippets he provides translating from CNG RSA keys to RSAParameters for use with RSACryptoServiceProvider. (And for a quick rundown of the managed CNG classes Kenny mentions in the v3.5 framework, you can see the posts in my CNG category).

Please do not use the .NET 2.0 HMACSHA512 and HMACSHA384 Classes

shawnfa — Wed, 31 Jan 2007 21:00:00 GMT

We’ve recently discovered a bug in the HMACSHA512 and HMACSHA384 classes which shipped in the .NET Framework 2.0. This bug will cause these algorithms to produce incorrect results which are not consistent with other implementations of HMAC-SHA-512 and HMAC-SHA-384. Unfortunately, we did not discover this bug until recently, and the shipping .NET Framework 2.0 on all platforms is affected by it. The only two affected algorithms are the HMAC-SHA-512 and HMAC-SHA-384; other HMAC algorithms do produce correct values.

The next service pack to the .NET Framework will contain a fix for this bug, which will cause the HMACSHA384 and HMACSHA512 classes to produce correct HMAC values. However, this will cause their output to be inconsistent with the output of the unserviced .NET Framework 2.0 classes. In order to allow applications running on serviced framework to interact with applications running on the unserviced version, we will introduce two compatibility switches in the service pack.

First, both the HMACSHA512 and HMACSHA384 classes will have a new Boolean property, ProduceLegacyHmacValues. By setting this property to true, the object will produce values which match what the unserviced .NET Framework would have produced. You should set this property only once after you’ve created your HMAC object, and you will need to reset your key afterwards:

    public static void Test()
    {
        HMACSHA512 hmac = new HMACSHA512();
        hmac.ProduceLegacyHmacValues = true;
        hmac.Key = // ... get the hmac key
 
        // ...
        // use the hmac algorithm
        // ...
    }

In order to help applications where it is expensive or impossible to change the code, we’ve added a new configuration switch for the application’s .exe.config file which will cause all HMAC objects created within the application to use the unserviced calculation.

<configuration>
    <runtime>
        <legacyHMACMode enabled="1" />
    </runtime>
</configuration>

Finally, in order to help debug any issues that arise when upgrading to the service pack, the first time an instance of either class is created, we will log a warning message to the event log and to any attached debugger. The message text (which will hopefully help to point search engine results here as well) will be:

"This application is using the HMAC-SHA-384 or HMAC-SHA-512 keyed hash algorithm. The implementation of these algorithms were updated in service pack 1 of .NET Framework 2.0 and by default do not produce results consistent with the unserviced versions of the classes. For more information about the changes to the algorithms and how to disable this warning message please see the release notes for service pack 1."

This warning will only be produced the first time an instance of either object is created in a process. If the configuration switch to enable process-wide legacy mode is set, then we will suppress the message. We’ve also provided a second configuration switch which will let you manually suppress the warning message for your application.

<configuration>
    <runtime>
        <legacyHMACWarning enabled="0" />
    </runtime>
</configuration>

If you need a replacement class for HMACSHA512 before the next service pack ships, then you can roll your own relatively easily. Some code to do this would look like this:

internal sealed class MyHmacSha512 : System.Security.Cryptography.HMAC
{
    public MyHmacSha512(byte[] key)
    {
        if (key == null)
            throw new ArgumentNullException("key");
 
        HashName = "SHA512";
        HashSizeValue = 512;
        BlockSizeValue = 128;
        Key = key;
    }
}

Similarly, a substitute class can be derived for HMACSHA384:

internal sealed class MyHmacSha384 : System.Security.Cryptography.HMAC
{
    public MyHmacSha384(byte[] key)
    {
        if (key == null)
            throw new ArgumentNullException("key");
 
        HashName = "SHA384";
        HashSizeValue = 384;
        BlockSizeValue = 128;
        Key = key;
    }
}

This change will start to appear in future CTPs. Again, I personally, and the CLR security team in general, are very sorry for any problems this may have caused in your applications. Please feel free to ask any questions in the comments for this post, and I’ll make sure that they get answered as soon as possible.

Elliptic Curve Diffie-Hellman

shawnfa — Tue, 23 Jan 2007 00:58:40 GMT

The second elliptic curve algorithm added to Orcas is elliptic curve Diffie-Hellman, as the ECDiffieHellmanCng class.

This is the first time Diffie-Hellman is available as part of the .NET Framework, so lets take a quick look at what it is and what it does. Diffie-Hellman is one of the oldest asymmetric algorithms, however unlike the other asymmetric algorithms in the framework today, it does not perform encryption or digital signatures. Instead it allows two parties to exchange private key material even if they only can communicate through a completely public channel. (In Network Security: Private Communication in a Public World, an amusing example is given where Diffie-Hellman is performed by two parties taking out ads in the local newspaper).

Key exchange is somewhat of a misleading term, since it implies that one party to the communication generates a key and via the communication protocol lets the other party know what that key is. Instead what really happens is that Diffie-Hellman allows both parties to calculate the same secret value, which is referred to as the secret agreement in the managed Diffie-Hellman classes. This secret agreement can then be used for any number of purposes, including being used as a symmetric key.

Instead of exposing the secret agreement directly however, the ECDiffieHellmanCng class does some post-processing on the agreement before letting the value out. We refer to this post processing as the key derivation function; you can select which KDF you want to use and set its parameters via a set of properties on the instance of the Diffie-Hellman object:

Key Derivation Function	Properties	Meaning
Hash	HashAlgorithm	Hash algorithm to process the secret agreement with
	SecretPrepend	Optional byte array to prepend to the secret agreement before hashing it
	SecretAppend	Optional byte array to append to the secret agreement before hashing it
Hmac	HashAlgortihm	Hash algorithm to process the secret agreement with (using the HMAC version of the algorithm).
	HmacKey	Key used for the HMAC operation
	SecretPrepend	Optional byte array to prepend to the secret agreement before hashing it
	SecretAppend	Optional byte array to append to the secret agreement before hashing it
Tls	Label	TLS PRF Label
Tls	Seed	TLS PRF Seed

The result of passing the secret agreement through the key derivation function is a byte array that may be used as key material for your application. The number of bytes of key material generated is dependent on the key derivation function, for instance SHA-256 will generate 256 bits of key material, while SHA-512 will generate 512 bits of key material.

The basic flow of an elliptic curve Diffie-Hellman key exchange is:

Alice and Bob create a key pair to use for the Diffie-Hellman key exchange operation
Alice and Bob configure the KDF using agreed upon parameters
Alice sends Bob her public key
Bob sends Alice his public key
Using each other's public keys, the secret agreement is generated, and the KDF is applied to the secret agreement generating key material.

In code, this looks basically as you would expect:

ECDiffieHellmanCng alice = new ECDiffieHellmanCng();
alice.KeyDerivationFunction = ECDiffieHellmanKeyDerivationFunction.Hash;
alice.HashAlgorithm = CngAlgorithm.Sha256;
 
ECDiffieHellmanCng bob = new ECDiffieHellmanCng();
bob.KeyDerivationFunction = ECDiffieHellmanKeyDerivationFunction.Hash;
bob.HashAlgorithm = CngAlgorithm.Sha256;
 
byte[] bobKey = bob.DeriveKeyMaterial(alice.PublicKey);
byte[] aliceKey = alice.DeriveKeyMaterial(bob.PublicKey);

After running this code, aliceKey and bobKey are both 32 bytes long and match each other. Now, Alice could use this as a symmetric key:

AesCryptoServiceProvider aes = new AesCryptoServiceProvider();
aes.Key = aliceKey;

Obviously, this example is simplified as both Alice and Bob are unlikely to be running in the same process. ECDiffieHellmanPublicKey, which is the class returned by the PublicKey property is Serializable, so that it may be sent across any remoting channel. It also can be manually converted to and from a byte array and XML, allowing for manual serialization in advanced use cases.

One thing to note about Diffie-Hellman is that it only guarantees that both parties are generating a secret that nobody else knows about. It does not let either party know the identity of the other. For instance, in the above code, Alice cannot be sure that the other person in the conversation is Bob; there could potentially be a man-in-the-middle attack here.

In order to solve that, Alice or Bob could use a well-known public key that is distributed by PKI (you can pass a CngKey to the DeriveKeyMaterial API in this case). You could also use HMAC as the KDF and a key that you know only Alice and Bob share to solve this problem.

Elliptic Curve DSA

shawnfa — Thu, 18 Jan 2007 23:05:00 GMT

Yesterday I gave a quick rundown of all the new cryptographic algorithms available in the Orcas January CTP. Today, let's dive in a little deeper to the first of the elliptic curve algorithms, ECDSA. (ECDSA, along with the rest of the CNG classes in the .NET Framework, is only available on Windows Vista).

ECDSA is an implementation of the digital signature standard using elliptic curves, which makes the ECDsaCng class a sort of cousin of the DSACryptoServiceProvider class. Because DSA and ECDSA are cousins rather than just different implementations of the same algorithm, there is a new base class ECDsa that elliptic curve DSA implementations derive from. You also cannot sign some data with DSACryptoServiceProvider and then verify that signature with ECDsaCng.

Let's take a look at a basic example of using ECDSA:

ECDsaCng dsa = new ECDsaCng();
dsa.HashAlgorithm = CngAlgorithm.Sha256;
 
byte[] data = new byte[] { 21, 5, 8, 12, 2007 };
byte[] signature = dsa.SignData(data);
 
if (dsa.VerifyData(data, signature))
    Console.WriteLine("Verified");
else
    Console.WriteLine("Not verified");

First we create a new ECDsaCng object, which will generate a random key for us to use. Next, we setup the hash algorithm to use on the input data when creating the signature. Finally, we can call SignData to create a signature over a blob of data, and VerifyData to verify that the signature is correct.

There are also SignHash/VerifyHash APIs available -- SignData will essentially just hash the data with the hash algorithm specified on the ECDsaCng object (defaulting to SHA-256) and then do a SignHash on the resulting hash value.

Sidebar: CNG Pseudo-Enums

I showed the HashAlgorithm property in the example, even though I was setting it back to the default value, because it uses the CngAlgorithm class which is the first of several pseudo-enums that will show up when you play with the CNG classes. CNG itself is very configurable, and it takes most of its configuration options as strings. With our managed APIs, we didn't want to limit the set of parameters you can pass to CNG to the set that we had predefined a mapping from a traditional enum to a CNG string for. We also wanted to preserve type safety (having everything be a string makes it unclear which strings can go where), and provide pre-defined values for the common cases.

The result is a set of pseudo-enumerations like CngAlgorithm. CngAlgorithm isn't an enum, it's a class. We've provided a set of CngAlgorithms representing the common algorithm names as static properties, which allow you to use it with enum-like syntax. There's also a CngAlgorithm constructor which takes a string, which means that if you need to use a CNG algorithm that isn't in the list you can construct a CngAlgorithm to reference that algorithm.

Each of the pseudo enums also behave just as you would expect when dealing with them directly. You can compare them with your language of choice's equality comparison operators, get their hash code, and convert them to their underlying strings. In addition to CngAlgorithm other pseudo-enums you'll find are CngAlgorithmGroup, CngKeyFormat, and CngProvider.

The default constructor generates a random key for use with the P-521 curve, described in appendix 6 of FIPS 186-2. There is also a constructor which accepts the curve you wish to work with; currently ECDsaCng supports P-192, P-256 and P-521. Or, if you don't want to generate a random key you can pass in an existing key to the constructor and it will work with that.

Incidentally, the CngKey class is your one stop shop for anything to do with CNG keys (stored by NCrypt). You can use this class to create a new random key, open or delete an existing key, get the properties of a key, import / export the key, etc. We also expose a SafeNCryptKeyHandle which represents the underlying NCRYPT_KEY_HANDLE, allowing you to easily P/Invoke for any other functionality not exposed in the CngKey class itself.

In addition to exporting the ECDSA key via the CngKey property of the ECDsaCng object, you can also export the key into XML. However, since there is currently no standard format for elliptic curve XML, you need to specify which format you want the XML to appear in (not specifying a format will cause an exception). Currently, we only support one option which is the format described in RFC 4050.

So that concludes our whirlwind tour of the ECDsaCng class. Next time we'll take a look at the elliptic curve Diffie-Hellman support in Orcas.

New Crypto Algorithms in Orcas

shawnfa — Wed, 17 Jan 2007 21:21:00 GMT

The January CTP of Orcas is now available, and with it comes a total of 12 new cryptography algorithm implementation classes, which include 2.5 new algorithms. (I'll count AES as 0.5 since we did already have Rijndael :-) ). These classes also are the first set of managed wrappers around the new CNG APIs in Windows Vista, which will use the Cng suffix on the implementation classes.

Dividing the new algorithms up into their types (all in the System.Security.Cryptography namespace in System.Core.dll), this CTP has:

Hash Algorithms

Algorithm	Class	OS Required
MD5	MD5Cng	Windows Vista
SHA-1	SHA1Cng	Windows Vista
SHA-256	SHA256CryptoServiceProvider	Windows 2003
SHA-256	SHA256Cng	Windows Vista
SHA-384	SHA384CryptoServiceProvider	Windows 2003
SHA-384	SHA384Cng	Windows Vista
SHA-512	SHA512CryptoServiceProvider	Windows 2003
SHA-512	SHA512Cng	Windows Vista

The hash algorithms work just as you would expect, and should function as simple drop-in replacements for corresponding algorithms that have already shipped in v2.0 of the .NET Framework. The big advantage here is that these hash algorithms are just wrappers around the Windows implementations of the algorithms, and therefore are FIPS compliant versions of the SHA-2 algorithms which had only managed versions in v2.0. For applications targeting Vista which must use CNG, this set of algorithms also provides CNG wrappers for all of our hashing algorithms.

Symmetric Algorithms

Algorithm	Class	OS Required
AES	AesCryptoServiceProvider	Windows XP SP2
AES	AesManaged	All Supported Platforms

We've provided a new Aes base class for implementations of AES (rather than Rijndael which allows some parameters to be set differently than AES). Two implementations of this base class are shipping with the Orcas January CTP, once which wraps the CAPI implementation of AES and a managed implementation of the algorithm which should run on any platform the CLR supports.

AesManaged is actually just a wrapper around RinjdaelManaged with some code added to make sure that you do not setup the algorithm to operate in a non-AES compatible way. For instance, AesManaged does not allow you to change the block size. (It will also disallow the use of CFB and OFB mode because of the way that RijndaelManaged works with those modes).

Asymmetric Algorithms

Algorithm	Class	OS Required
Elliptic Curve DSA	ECDSACng	Windows Vista
Elliptic Curve Diffie-Hellman	ECDiffieHellmanCng	Windows Vista

These are the really interesting additions to the cryptography libraries in this CTP, the first appearance of elliptic curve cryptography in the .NET Framework. Since these will take more than just a paragraph to cover, the next couple of blog posts will focus on these classes (as well as the other supporting classes to help work with CNG). Up next, Elliptic Curve DSA.

XML Digital Signature Verification with Unknown URI Schemes

shawnfa — Thu, 12 Oct 2006 19:07:00 GMT

A few years back, there was a discussion thread on one of my XML digital signature posts about verifying an XML digital signature which had references to a URI prefixed with cid:. Recently Mattias Lindberg ran into this problem as well, and devised a clever solution to it.

Mattias realized that SignedXml uses WebRequest.Create to help resolve what the reference points to. And since WebRequest is extensible, he registered a custom class to handle cid URLs. Although his specific example is for cid, this technique will work for any other protocol that the .NET Framework does not know how to handle out of the box.

The Differences Between Rijndael and AES

shawnfa — Mon, 09 Oct 2006 19:20:00 GMT

When you need to write managed code that encrypts or decrypts data according to the AES standard, most people just plug the RijndaelManaged class in and go on their way. After all, Rijndael was the winner of the NIST competition to select the algorithm that would become AES. However, there are some differences between Rijndael and the official FIPS-197 specification for AES.

Namely, Rijndael allows for both key and block sizes to be chosen independently from the set of { 128, 160, 192, 224, 256 } bits. (And the key size does not in fact have to match the block size). However, FIPS-197 specifies that the block size must always be 128 bits in AES, and that the key size may be either 128, 192, or 256 bits. Therefore AES-128, AES-192, and AES-256 are actually:

	Key Size (bits)	Block Size (bits)
AES-128	128	128
AES-192	192	128
AES-256	256	128

Since RijndaelManaged is an implementation of Rijndael, it will allow you to select different block sizes (although both block and key sizes must be either 128, 192, or 256 bits. 160 and 224 bit are not supported). By selecting a block size which is not 128 bits however, RijndaelManaged will not be able to interoperate with an AES implementation ... since the block sizes will not match on either end of the communication.

One other interesting quirk of the RijndaelManaged implementation is that it will adjust block size to match the feedback size in CFB mode. This means that if you use CFB and a block size of 128 bits, but a feedback size which is not 128 bits you again will not be compatible with AES. Generally this does not affect many people, since the most common cipher mode to use is CBC.

Essentially, if you want to use RijndaelManaged as AES you need to make sure that:

The block size is set to 128 bits
You are not using CFB mode, or if you are the feedback size is also 128 bits

RSACryptoServiceProvider, Impersonation, and Ephemeral Keys

shawnfa — Thu, 21 Sep 2006 20:49:26 GMT

If you construct an RSACryptoServiceProvider class without specifying a name for the key, the CLR will create a random ephemeral key for you. However, ephemeral keys are not supported by the underlying CAPI APIs on all of the platforms that the CLR was built to support, so the RSACryptoServiceProvider will attempt to fake this behavior.

It does this by generating a random name for a key, saving the key in that named container, and then when the RSACryptoServiceProvider instance is disposed, deleting the key. Generally this works well, but when impersonation gets thrown into the mix, things can go awry.

Imagine this scenario:

Create a new, random RSA key
Impersonate another user
Use the key
Dispose the key

In this case, the key was created in the profile of one user, and when it is disposed we're running in the context of a different user. When the dispose is attempts to delete the key, we run into an issue. Namely, the new user probably doesn't have permission to delete keys in the old user's profile.

The solution here is to make sure that you create and dispose of ephemeral keys while running in the same user context. Another solution is to name the key yourself, instead of letting the CLR generate a random name. If you've given the key a name the CLR will not attempt to delete the key when the RSACryptoServiceProvider class is disposed -- you can then take care of deleting the key yourself at a later time.

That scenario is pretty straight forward, but you can get bit by this issue in another, more subtle way. Lets say that you fix the above pattern in your code and now you impersonate before creating the RSA key. However, your code does not dispose the RSACryptoServiceProvider object, and instead waits for the GC to collect it for cleanup to occur.

When the GC is ready to collect the object, it will notice that it needs to be finalized, and run the finalizer -- on a separate thread from where you created the object. This thread will not be impersonating, and you run into the same problem. This is very similar to problems that Nicole Calinoiu mentioned in her blog post about impersonation and finalization earlier this year.

In order to avoid these problems all together, the safest pattern to use when combining ephemeral keys with impersonation is:

Impersonate
Create the key
Use the key
Dispose of the key
Undo the impersonation

Getting Information about an X509Certificate's Key Container

shawnfa — Thu, 30 Mar 2006 20:14:00 GMT

One of the more common things a lot of people want to do with their X509Certificate2 is figure out what key container its keys are stored in. You can access this information relatively trivially via the PublicKey property of the X509Certificate2 object:

/// <summary>
/// Get information about the key container a certificate is stored in
/// </summary>
public static CspKeyContainerInfo GetKeyConatinerInformation(X509Certificate2 certificate)
{
    if (certificate == null)
        throw new ArgumentNullException("certificate");

    ICspAsymmetricAlgorithm key = certificate.PublicKey.Key as ICspAsymmetricAlgorithm;
    if (key == null)
        throw new InvalidOperationException("Unknown key type");

    return key.CspKeyContainerInfo;
} 

Here we get the ICspAsymmetricAlgorithm representing the key from the public key, which should work for both RSA and DSS certificates. From there we can simply pull the CspKeyContainerInfo object and get basically anything we want to know about the key container. Specifically, the KeyContainerName, KeyNumber, ProviderName, ProviderType, HardwareDevice, and Exportable properties tend to be the most interesting.

Note that this trick will not work with the PrivateKey property of the X509Certificate2, since the private key returned is actually a copy of the key associated with the certificate.