Note: You are currently viewing documentation for Moodle 2.2. Up-to-date documentation for the latest stable version is available here: Password salting.

Password salting

From MoodleDocs
Revision as of 23:08, 17 November 2009 by Iñaki Arenaza (talk | contribs) (You need to retain 'all' of your previous salts, not just the last one)

What is password salting?

Passwords are stored in Moodle in an encrypted form, called an 'md5 hash'.

Password salting is a way of making passwords more secure by adding a random string of characters to passwords before their md5 hash is calculated, which makes them harder to reverse (the longer the random string, the harder you make it).

Enabling password salting

To enable password salting in Moodle, add the following line to your config.php file:

$CFG->passwordsaltmain = 'some long random string here with lots of characters';

The Moodle Salt Generator may be used to obtain a suitable long random string.

Note: For security reasons the only way to enable password salting is by editing config.php - there is no way to do so in the Moodle interface.

Changing the salt

If for any reason you wish to change the salt, the old salt must be retained in config.php in addition to the new salt.

passwordsaltmain should be changed to passwordsaltalt1 (note that the exact expressions must be used) for the old salt as follows:

$CFG->passwordsaltalt1 = 'old long random string';
$CFG->passwordsaltmain = 'new long random string';

If you change your salt again in the future, you must retain all the previous salts for some time (until every user has logged in at least once, so they start using the new salt). You can use $CFG->passwordsaltalt2, $CFG->passwordsaltalt3, etc. to keep up to 20 previous salts.

Warning: If you change the salt and do not retain the old one in config.php you will no longer be able to login to your site!

Importing users from another site

If you import users from another Moodle site which uses a password salt, you need to add the other site's salt to config.php too. Upto 20 alternate salts may be added

$CFG->passwordsaltalt1, $CFG->passwordsaltalt2, ...  $CFG->passwordsaltalt20

How does password salting work?

When a password is checked, the code looks for CFG->passwordsaltmain. If set, it appends the user's password to the salt before calculating the md5 hash.

If the unsalted md5 hash of a user's password validates, it is assumed that the salt was set for the first time since the last time the user logged in. The user's password is upgraded, using the salt.

If neither the unsalted md5 hash, or the salted md5 hash validates, the code looks for up to 20 alternate salts.

If you change salts, in order not to orphan existing user accounts, you must enter the old salt into one of the alternate slots.

When a user who has an "old salt" password logs in, the first test of their authentication with the new salt will fail... then the code will test any alternate salts, looking for one that allows the password to be proven valid.

If a user is deemed valid, the system will upgrade the user's hashed password to the latest salt.