Password salting

What are password salting and peppering?

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.

Password peppering is a secret added to a password at hashing time to increase the security of the hashed password. This value differs from a salt in that it is not stored with the password hash, instead the pepper is kept separate in the config.php file. It must also be kept secret and be be hard to guess. Keeping the value separate to the salt and hashed password, meaning if password hashes are compromised, it is much harder to reverse engineer the plain text passwords.

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.

How does Moodle use password peppering?

New feature
in Moodle 4.3! Moodle 4.3 introduces password peppers that are configured and managed via the config.php file. A pepper needs to have at least 112 bits of entropy, so the pepper itself cannot be easily brute forced if you have a known password + hash combo.

Once a pepper is set, existing passwords will be updated on next user login. To set peppers for your site, the following setting must be set in config.php:

      $CFG->passwordpeppers = [
          1 => '#GV]NLie|x$H9[$rW%94bXZvJHa%z'
     ];

The 'passwordpeppers' array must be numerically indexed with a positive number. New peppers can be added by adding a new element to the array with a higher numerical index. Upon next login a users password will be rehashed with the new pepper:

      $CFG->passwordpeppers = [
          1 => '#GV]NLie|x$H9[$rW%94bXZvJHa%z',
          2 => '#GV]NLie|x$H9[$rW%94bXZvJHa%$'
      ];

Peppers can not be removed in bulk without resetting all user passwords. However, peppers can be progressively removed by setting the latest pepper to an empty string:

      $CFG->passwordpeppers = [
          1 => '#GV]NLie|x$H9[$rW%94bXZvJHa%z',
          2 => '#GV]NLie|x$H9[$rW%94bXZvJHa%$',
          3 => ''
      ];

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.