This HTTP module allows cookies to be encrypted/decrypted without any change to the Web application making use of the cookies. It effectively bolts on cookie encryption to .NET applications that may not originally have included it.
Using the Code
The solution contains two projects:
CookieEncryptionModule - This is the HTTP module class library that does the actual work.
CookieEncryptionTestWeb - This is a Web project that has been "wired up" to use the HTTP module.
Using the module is as simple as dropping the CookieEncryptionModule.dll file into the Web application bin folder and adding a reference to the
httpModules section in the web.config file (see test project). There are various web.config settings (optional) that control how the module handles cookies:
CookieEncryptionModule_CookieList: This is a delimited list of cookie names.
CookieEncryptionModule_Separator: This is a single character that is used to delimit cookie names in
CookieEncryptionModule_HandleOrIgnoreCookieList: This determines whether
CookieEncryptionModule_CookieList is inclusive or exclusive.
Handle - Only cookies in the list will be encrypted
Ignore - Only cookies not in the list will be encrypted
CookieEncryptionModule_UnencryptedCookiePolicy: This specifies how to handle expiration of unencrypted persistent cookies that are now identified as requiring encryption. Since only the cookie name and value are sent in the request, the expiration date/time must be reset to encrypt it.
Ignore - The cookie will not be encrypted unless it is reset by the application.
Clear - The cookie will be deleted before the application sees it.
Note: This removes it from the request but not from the client.
Session - The cookie will be converted to a session cookie.
Never - Expiration set to
- yy,dd,hh,mm,ss - An expiration of yy years, dd days, hh hours, mm minutes and ss seconds will be set.
If these are not specified, then the application defaults to encrypting all cookies and removing unencrypted cookies from the request.
Using the Test Website
Since the encryption and decryption of cookies is transparent to the application, you need to look at the cookies directly either through the browser's "View Files" (Internet Explorer) or "Show Cookies" (Firefox) option or by using a tool such as Fiddler 2 Web proxy or the Internet Explorer Developer Toolbar. As an example, to see the way unencrypted cookies are handled:
- Open the solution, set
CookieEncryptionTestWeb as the startup project and CookieEncryptionTester.aspx as the start page.
TestCookie2 and the separator (
|) from the
CookieEncryptionModule_CookieList value in the web.config and save the change.
- Delete any previous
TestCookie values from your browser cache and run the project. The test Web page should show No Cookie for all 4 values as this is populated from cookies sent with the request.
- Check the cookies now stored on disk and you should see an unencrypted
TestCookie2 and an encrypted
TestCookie4. There should be no entry for
3 as these are session cookies.
- Reverse the change made to the web.config in step 2 so that
TestCookie2 is marked as a cookie that requires encryption. Press the Submit button on the test Web page.
- Check the cookies now stored on disk and you should see that
TestCookie2 is encrypted and has an expiry date 1 year in the future (as specified by the web.config value for
TestCookie2 and the separator (as step 2) and press the Submit button.
- The Web page should now show the encrypted value of
TestCookie2 as it is no longer marked as an encrypted cookie.
Points of Interest
I have attempted to ensure that the module defaults to its most secure settings (all cookies encrypted, unencrypted cookies removed from the request) if there are any problems or if the web.config doesn't contain valid settings.
I opted to use the built-in
FormsAuthenticationTicket to handle the encryption. This was on the basis that since it is used for forms authentication, it is already optimised for use in this process. However, there should be no problem with replacing this with a custom encryption handler.
There is a hard-coded list (
NeverProcessTheseCookies) of cookies that should never be touched. This contains the session cookie by default. If your application uses forms authentication and you want the web.config to specify cookies to be encrypted (rather than ignored), then add the authentication cookie name to this list. If, in the web.config, you are specifying cookies to be ignored then you can add the forms authentication cookie there.
Value property that is displayed appears to be generated by combining the key/value pairs in the
Values collection. If you set the
Value property directly, e.g.
MyCookie.Value="Test"; this creates a new
NameValueCollection with a pair (
Test") at position zero. The
HasKeys property is only set to
true if the
Values collection contains non-
- 9th December, 2007
- Added notes on using the test Web application
- Modified constructor to assign
ApplicationUnencryptedCookiePolicy only if everything is OK
- Modified constructor to use
string constant for
- 10th December, 2007
- Corrected change to
ApplicationUnencryptedCookiePolicy in constructor
- 4th July, 2009
- Modified cookie decryption to correctly handle multi-value cookies (thanks to Ryan Salt for the heads up)
- Modified the test application to demonstrate multi-value cookies