Rolling Key Encryption for Authentication Tickets

Use the rolling key encryption feature to change the encryption key, which is used to encrypt and decrypt authentication tickets for a site. You may want to change the encryption key for your site when an administrative level employee leaves, an external security compromise is detected, or periodically as a security policy.

Note

• Before you update an existing encryption key, it is recommended that you store the existing encryption keys where they can be retrieved by your application. Commerce Server does not create a backup for you. It is recommended that you back up the key to a secure location, preferably to a location that cannot be accessed by users.

Your application can use these old encryption keys at a later time to decrypt tickets that were encrypted with the old key. The manner in which this is done is determined by the application. However, only the user ID can be obtained from an old ticket, all custom properties are lost.

When an encryption key for a site is changed, IIS must be restarted to allow AuthFilter to reinitialize itself with the new encryption key. For information about changing your encryption key, see Generating a New Cookie Encryption Key.

If you do not have a Web farm scenario, then no further steps are required. However, if you are changing the encryption key in a Web farm, follow the additional steps specified below.

Rolling Key Encryption in a Web Farm Scenario

When you change the encryption key in a Web farm scenario, you must restart IIS on each Web server. AuthFilter then reinitializes itself on each Web server with the new encryption key. However, while the servers are being reset, there is a possibility that a request containing a ticket that was encrypted using the old encryption key may be redirected to a server that has already reset, and is using the new encryption key. Hence, when a redirected request arrives at this server, AuthFilter, which is initialized with the new encryption key, is not able to decrypt the ticket in the request. The ticket in the redirected request was encrypted using the old encryption key. Because AuthFilter cannot decrypt the ticket in the request, AuthFilter redirects this request to the login page.

To avoid redirecting validated users to the login page, after the encryption key is changed, new code must be added to the Login.asp page that allows for the retrieval of the userid from the incoming ticket, encrypted using the old encryption key. The new code must then issue a new ticket to the user, which is encrypted with the new key.

You can use the GetUserIDFromCookieAndKey method of the AuthManager API, to add the necessary new code to your login page to support rolling key encryption in a Web farm scenario. The following is a snippet of the Login.asp page, which has been customized to support this scenario:

Dim sUserID

On Error Resume Next

sUserid = auth.GetUserid(enumMSCS_ProfileTicketType)

if (err.number = ...)  get the error codes for NTE_BAD_DATA ,  NTE_BAD_KEY  , NTE_BAD_HASH
{
Dim sCookie, sOldEncryptionKey
sOldEncryptionKey = ** retrieve this from whereever you save old encryption keys
sCookie = Request.Cookies("MSCSAuth")
sUserid = auth.GetUseridFromCookieAndKey(sCookie, sOldEncryptionKey)

if Not ((err.number = ...)  get the error codes for NTE_BAD_DATA ,  NTE_BAD_KEY  , NTE_BAD_HASH)
{
auth.SetAuthTicket(sUserID, bCookieSupport, nTimeWindow)
}
else
{
*** rediret to reforce a login.
}

*** note you can try more than one old key if you have saved more than one old encryption key
}

On Error Goto 0

Finally, before you change the encryption key, you must use the Web server log import DTS task to import your IIS logs into the Data Warehouse. If you do not import the data before changing the encryption key, then the Web server log import task will not be able to decrypt the tickets contained in the logs. This is because the Web server log import task attempts to decode the tickets in the log file using the current encryption key stored in the admin database.

Note

• In conjunction with the sample code provided, the old encryption keys must be stored where they can be retrieved by your application. These old encryption keys can be used at a later time to decrypt tickets that were encrypted with the old key. The manner in which this is done is left up to the application. However, only the user ID can be obtained from an old ticket, all custom properties are lost.

See Also

Restarting IIS and Commerce Server Services

Copyright © 2005 Microsoft Corporation.
All rights reserved.