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

Password salting: Difference between revisions

From MoodleDocs
Main page ► Managing a Moodle site ► Security ► Password salting
Security
No edit summary
m (Updated link to spanish translation of page)
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Security}}
==What is password salting?==
==What is password salting?==


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 password hashing more secure by adding a random string of characters to passwords before their hash is calculated, which makes them harder to reverse.


[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 harder to reverse (the longer the random string, the harder you make it).
==How does Moodle use password salting?==


This feature has been available in all versions of Moodle since Moodle 1.6.
Prior to Moodle 2.5 there was a single site-wide salt which was used when hashing every user's password. From Moodle 2.5 onwards Moodle automatically generates and adds a different salt for each individual user. This is more secure and means that a site-wide configuration variable for the salt is no longer required for '''new''' installations of 2.5 or greater.


==Enabling password salting==
==Backwards compatibility for site upgrades==


To set a password salt, add the following line to your [[Configuration file|config.php file]]:
'''Important!''' If you are upgrading a site from 2.4 or below and you are already using a site-wide salt in your configuration file, '''you need to keep using it to ensure your existing users can still log in'''.


$CFG->passwordsaltmain = 'some long random string here with lots of characters';
Each time a user logs in their password hash will be converted to the new scheme, but it may take a long time before all your users have logged in. Alternatively, if you would like to force all your users to use the new scheme you could force reset all passwords using [[Bulk_user_actions|Bulk user actions]].


The random string of characters should be a mix of letters, numbers and other characters. The [http://dev.moodle.org/gensalt.php Moodle Salt Generator] may be used to obtain a suitable long random string. A string length of at least 40 characters is recommended.
For more details about the old site-wide salt configuration, see the [https://docs.moodle.org/24/en/Password_salting Moodle 2.4 Password Salt documentation].


''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.
==Sites running PHP version below 5.3.7==


''Tip'': Keep a note of your password salt somewhere other than config.php to prevent the situation of your password salt being lost and all site users having to go through password recovery to reset their passwords.
The new password hashing mechanism relies on bcrypt support from PHP which is only normally available in PHP version is 5.3.7 or greater (see note below). If you are using a version of PHP which doesn't properly support bcrypt, Moodle will fall back to the old password hashing scheme, so we recommend that you continue to use a site-wide salt until you are able to upgrade PHP.


==Changing the salt==
Note: While an important fix to PHP's hashing algorithm was added in 5.3.7, some distributions of Linux have backported the fix to bcrypt to earlier versions of PHP. This means that some earlier versions of PHP may still work. To confirm if your PHP supports the new hashing scheme you can use [https://github.com/ircmaxell/password_compat/blob/master/version-test.php this test].
 
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->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!''
 
==Disabling password salting==
 
'''Note''': Not Recommended! Once enabled, you should leave password salt enabled.
 
To disable password salting in Moodle, you can delete, comment out, or change the value of passwordsaltmain to "empty"
 
// EXAMPLE: set to empty string
$CFG->passwordsaltmain = <nowiki>''</nowiki>;
 
 
// EXAMPLE: comment out
/*
$CFG->passwordsaltmain = <nowiki>''</nowiki>;
*/
 
However, you are not done! You '''must also move the old salt to an "alt" value''', just like the "changing the salt" description, above:
 
$CFG->passwordsaltalt1 = 'old long random string';
$CFG->passwordsaltmain = <nowiki>''</nowiki>;
 
==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 <code>CFG->passwordsaltmain</code>. If set, salt is appended to user's password 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. '''The password is salted during the first login after the salt was set in config.php.'''
 
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]]


[[cs:Solení hesel]]
[[cs:Solení hesel]]
[[de:Kennwortverschlüsselung (Salt)]]
[[de:Kennwortverschlüsselung (Salt)]]
[[es:report/security/report_security_check_passwordsaltmain]]
[[es:Salado de contraseña]]
[[fr:Salage de mot de passe]]
[[fr:Salage de mot de passe]]
[[it:report/security/report_security_check_passwordsaltmain]]
[[it:report/security/report_security_check_passwordsaltmain]]

Latest revision as of 14:26, 21 June 2014

What is password salting?

Password salting is a way of making password hashing more secure by adding a random string of characters to passwords before their hash is calculated, which makes them harder to reverse.

How does Moodle use password salting?

Prior to Moodle 2.5 there was a single site-wide salt which was used when hashing every user's password. From Moodle 2.5 onwards Moodle automatically generates and adds a different salt for each individual user. This is more secure and means that a site-wide configuration variable for the salt is no longer required for new installations of 2.5 or greater.

Backwards compatibility for site upgrades

Important! If you are upgrading a site from 2.4 or below and you are already using a site-wide salt in your configuration file, you need to keep using it to ensure your existing users can still log in.

Each time a user logs in their password hash will be converted to the new scheme, but it may take a long time before all your users have logged in. Alternatively, if you would like to force all your users to use the new scheme you could force reset all passwords using Bulk user actions.

For more details about the old site-wide salt configuration, see the Moodle 2.4 Password Salt documentation.

Sites running PHP version below 5.3.7

The new password hashing mechanism relies on bcrypt support from PHP which is only normally available in PHP version is 5.3.7 or greater (see note below). If you are using a version of PHP which doesn't properly support bcrypt, Moodle will fall back to the old password hashing scheme, so we recommend that you continue to use a site-wide salt until you are able to upgrade PHP.

Note: While an important fix to PHP's hashing algorithm was added in 5.3.7, some distributions of Linux have backported the fix to bcrypt to earlier versions of PHP. This means that some earlier versions of PHP may still work. To confirm if your PHP supports the new hashing scheme you can use this test.

Retrieved from "https://docs.moodle.org/39/en/index.php?title=Password_salting&oldid=113252"
Powered by MediaWiki