Skip to content

Use the MachineKey API to protect values in ASP.NET

June 21, 2012

It’s quite common to need to preserve state across requests in a web application. This is typically in the form of a cookie, query string or hidden form field. Commonly the state that needs to be sent back to the client is sensitive or we want to ensure it’s not been modified by the user. The typical approach to this should be encrypting (protect) and MACing (verify) the value. Writing this sort of crypto code yourself is possible but not ideal. Fortunately in ASP.NET the MachineKey API already provides this functionality. And yes, this is the same as the <machineKey> infrastructure already used to protect Forms authentication and ViewState.

The API is slightly different between 4.0 and 4.5. Here’s the 4.0 usage with some helpers:

string Protect(byte[] data)
{
    if (data == null || data.Length == 0) return null;
    return MachineKey.Encode(data, MachineKeyProtection.All);
}

byte[] Unprotect(string value)
{
    if (String.IsNullOrWhiteSpace(value)) return null;
    return MachineKey.Decode(value, MachineKeyProtection.All);
}

MachineKey.Encode accepts a byte[] to protect and returns a string. The second parameter is an enum that indicates if you want encryption, validation or both. I’d typically suggest both (MachineKeyProtection.All). The returned string can then be used to pass back to the client as a cookie value or a query string value without concern for viewing or tampering. MachineKey.Decode simply reverses the process.

And here’s the 4.5 usage (it supports a slightly more sophisticated usage):

const string MachineKeyPurpose = "MyApp:Username:{0}";
const string Anonymous = "<anonymous>";

string GetMachineKeyPurpose(IPrincipal user)
{
    return String.Format(MachineKeyPurpose,
        user.Identity.IsAuthenticated ? user.Identity.Name : Anonymous);
}

string Protect(byte[] data)
{
    if (data == null || data.Length == 0) return null;
    var purpose = GetMachineKeyPurpose(Thread.CurrentPrincipal);
    var value = MachineKey.Protect(data, purpose);
    return Convert.ToBase64String(value);
}

byte[] Unprotect(string value)
{
    if (String.IsNullOrWhiteSpace(value)) return null;
    var purpose = GetMachineKeyPurpose(Thread.CurrentPrincipal);
    var bytes = Convert.FromBase64String(value);
    return MachineKey.Unprotect(bytes, purpose);
}

In 4.5 the old APIs are deprecated in favor of these new Protect and Unprotect APIs. The new APIs no longer accept the level of protection (they always encrypt and MAC now [which is good]) and instead now accept a new parameter which is called “purpose”. This purpose parameter is intended to act somewhat as a validation mechanism. If we use a value that’s specific to the user (as we do above with the GetMachineKeyPurpose helper) we then are verifying that the value can only be unprotected by the same user. This is a nice addition in 4.5.

In my Cookie-based TempData provider I used this exact technique — I didn’t want to reinvent crypto or introduce new keys, so leveraging the ASP.NET machine key APIs made a lot of sense.

Oh and one caveat: this does not prevent an eavesdropper from intercepting the value and replaying it, so (as usual) SSL is imperative.

Update: Great follow-up reading about the internals of the MachineKey:

6 Comments leave one →
  1. meenu permalink
    June 28, 2012 2:39 am

    Can u help me to write this functions in vs2010 silverlight 4 application.This machine key retriving error in my vs2010 web project

    • June 28, 2012 10:27 am

      @meenu: These MachineKey functions are intended to be used from the server, not on the client.

  2. December 16, 2012 12:55 pm

    Hallo Brock! It seems that those new method have issues ecnrypting cookie values since converting the encoded byte flush to string creates a string not suitable for cookie value and thous generating exception on Unprotect of that string reconverted to byte()

    Any hint on how to use those methods for cookie protection? Or any other new class instead of the deprecated encode/decode methods?

Trackbacks

  1. Cryptographic Improvements in ASP.NET 4.5, pt. 3 - .NET Web Development and Tools Blog - Site Home - MSDN Blogs

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: