Note: You are currently viewing documentation for Moodle 3.8. Up-to-date documentation for the latest stable version of Moodle may be available here: Password salting.

Password salting: Difference between revisions

From MoodleDocs
(content copied from Configuration file)
 
(How does password salting work? thanks to Garret Gengler)
Line 1: Line 1:
==What is password salting?==
==What is password salting?==


Moodle stores passwords as md5 strings. [http://en.wikipedia.org/wiki/Salt_%28cryptography%29 Password salting] adds some random string to passwords before their md5 hash is calculated to make them practically impossible to reverse.
Passwords are stored in Moodle in an encrypted form, called an '[http://en.wikipedia.org/wiki/MD5_hash md5 hash]'.
 
[http://en.wikipedia.org/wiki/Salt_%28cryptography%29 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 practically impossible to reverse.


==Enabling password salting==
==Enabling password salting==


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


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


You can use the [http://dev.moodle.org/gensalt.php Moodle Salt Generator] to obtain a suitable long random string.
The [http://dev.moodle.org/gensalt.php 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.
''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.
Line 15: Line 17:
==Changing the salt==
==Changing the salt==


If you wish to change the salt, you must add it to config.php as follows:
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.
 
<code>passwordsaltmain</code> should be changed to <code>passwordsaltalt1</code> (note that the exact expressions must be used) for the old salt as follows:


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


''Warning: If you change the salt and do not include the old one in config.php you will no longer be able to login to your site!''
''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==
==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.
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 <code>CFG->passwordsaltmain</code>. If set, it appends the user's password to the salt before calculating the md5 hash.


In addition to <code>$CFG->passwordsaltmain</code>, Moodle checks for all salts defined in variables
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.


$CFG->passwordsaltalt1, $CFG->passwordsaltalt2, ... $CFG->passwordsaltalt20
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.


[[Category:Security]]
[[Category:Security]]

Revision as of 22:22, 17 November 2009

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 practically impossible to reverse.

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';

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.