How and Why You Should Generate a Custom Machine Key
In ASP.NET, authentication cookies are encrypted using the machine key. Also if you use encrypted passwords, then the password encryption also uses the machine key as a factor in encrypting passwords. By default, the machine key is auto generated unless you specify it directly in Web.config. However if you just let the machine key be auto generated, what happens is, if you move your site to a different server, the machine key is different and therefore it cannot decrypt the passwords and all your accounts would be locked out. Also in a Web farm or cluster the machine key needs to be the same on each server in order to work correctly so that all servers encrypt cookies and passwords the same.
In mojoPortal content management system, we include a machine key specified in Web.config so that you won't get locked out if you move a site to a different server. But mojoPortal is an open source project so anyone can see the machine key we include in Web.config and therefore could potentially be able to forge a cookie with the same encryption and try to authenticate or elevate their roles such that they could have administrative access to your site.
To avoid this it is very important that you generate your own machine key and replace the one in your Web.config with one you generated yourself. Make sure you do this before changing the password format to encrypted, otherwise changing the machine key will prevent you from logging in since it can no longer decrypt the password.
If you have already set your site to use encrypted passwords, you should backup your site and database and then change to clear text passwords and then change your machine key and then change it back to encrypted.
If your passwords are set to clear text or hashed, no workarounds are needed when changing the machine key.
There are several methods you can use to generate a new machine key:
- If you are using mojoPortal 220.127.116.11 or later, there is a built-in machine key generator in the Security Advisor section of your site's Administration page. During initial setup for new installations if the web.config file is writable then the setup page will automatically generate a custom machinekey and update web.config.
- You can generate a machine key in IIS 7.x if you have administrative access to the server, see: http://blogs.msdn.com/b/vijaysk/archive/2009/05/13/iis-7-tip-10-you-can-generate-machine-keys-from-the-iis-manager.aspx
- This article on MSDN also has sample code for a console application that can generate a machine key.
- There are also several online tools that can generate a machine key for you, I recommend this one: http://aspnetresources.com/tools/machineKey
Once you have changed to a custom machine key, that means you must maintain that customization whenever you upgrade to new versions of mojoPortal, so you need to backup Web.config file so you can copy your machine key into the new Web.config file after upgrading.
When you do change the machine key, everyone using the site will be logged out because their authentication cookie will no longer be valid, so they will have to login again.
Additional Considerations When Changing the MachineKey
If you have enabled SMTP configuration from Site Settings by adding this in your user.config:
<add key="EnableSiteSettingsSmtpSettings" value="true" />
then the SMTP settings are stored in the database and the user and password are encrypted. So changing the machine key may cause an error in the Site Settings page because it will not be able to decrypt the values that were encrypted with the previous machine key. So ideally you should clear out the SMTP user and password from Site Settings before changing the machine key and then put those settings back after you change the machine key. Otherwise you may need to fix it as follows from the database:
- UPDATE mp_SiteSettingsEx SET KeyValue = '' WHERE KeyName = 'SMTPUser'
- UPDATE mp_SiteSettingsEx SET KeyValue = '' WHERE KeyName = 'SMTPPassword'
- The above will clear those values from the database but Site Settings are cahced so you will need to clear the cache by recycling the application pool ot touching the Web.config file.
- Go back into Site Settings and reset the SMTP settings so they get encrypted with the new machine key.
Last Updated 2011-10-23 by Joe Audette