From MediaWiki.org
Jump to: navigation, search
Warning Warning: This extension does not work with MW 1.24 and may not be needed there since 1.24 includes better password hashing.
Version 3.0beta1 is ready for general testing, please report any bugs you may find in bugzilla under the "SecurePasswords" component. It is not recommended that SecurePasswords be run on production servers.

MediaWiki extensions manual
Crystal Clear action run.png

Release status: beta

Implementation User identity
Description Creates more secure password hashes in the database as well as a password strength checker
Author(s) Ryan Schmidt
Latest version 3.0beta1
MediaWiki 1.20.0+
PHP 5.3.7+
Database changes Yes
Tables password history
passwords uninstall‎
License GPL Version 2 (or any later version)

$wgValidPasswords, $wgSecurePasswordsSpecialChars, $wgSecurePasswordsSecretKeys, $wgSecurePasswordsRounds, $wgSecurePasswordsAutoRounds, $wgSecurePasswordsAutoRoundsThreshold, $wgSecurePasswordsExpiry, $wgSecurePasswordsSecretKey, $wgSecurePasswordsMigrateOnLogin, $wgSecurePasswordsStrengthTuning, $wgSecurePasswordsAdditionalDictionary

Hooks used

Translate the SecurePasswords extension if it is available at translatewiki.net

Check usage and version matrix; code metrics


Open tasks · Report a bug

What can this extension do?[edit]

SecurePasswords is currently the only MediaWiki extension that can provide peace of mind to wiki owners that their wiki accounts are secure. It combines secure password hashes in the bcrypt format (optionally encrypted) with a configurable set of options to enforce when setting new passwords to ensure that user accounts do not fall victim to random password-cracking attempts.

From the front-end, you can enforce security policies on passwords by configuring the $wgValidPasswords variable:

  • Enforce a minimum password length to deter brute force attacks
  • Enforce that passwords need to contain a mixture of lowercase, uppercase, digits, and symbols (or any combination of the four that you see fit)
  • Enforce that the password cannot be the same as the username
  • Enforce that the password cannot be a word or a combination of words in the Dictionary (Requires either the "pspell" or "enchant" extensions for PHP, listed in #Prerequisites)
  • Enforce password expiration either globally or on a per-group level (coming in 3.0 but not yet implemented)
  • Enforce a minimum password "strength" and show a strength checker on the password change form (coming in 3.0 but not yet implemented)
  • Enforce that a password was not previously used by that user (coming in 3.0 but not yet implemented)

From the back-end, you can rest assured knowing that the hash format in use is bcrypt, which is widely recognized as ideal for password hashing compared to other formats such as SHA or MD5 due to the fact that it is slow. While a slow hash function will not greatly affect you since you only need to hash each password a couple times, it is a great deterrent in the event someone manages to acquire the password hash, as it would take an obscenely long time to test billions of passwords for a match. If that isn't enough, you can optionally encrypt the passwords in the database, so a database leak would not expose your user's passwords.


The following are required and SecurePasswords cannot run without them:

  • PHP version 5.3.7 or above. Versions lower than this suffer a vulnerability with the bcrypt hashing algorithm.

The following are optional but enable additional features:

  • mcrypt is needed for encrypting password hashes in the database. If you are upgrading from an earlier verson of SecurePasswords (version 1 or 2), this extension as well as and zlib are required instead.
  • pspell or enchant are needed for checking passwords against dictionary words or your own supplied wordlist.


Warning Warning: Before installing SecurePasswords beta, it is highly recommended that you take a backup of your user table, in case you need to restore it later for whatever reason.

To install this extension, unpack the extension to /extensions (it should create a new directory called SecurePasswords).

Then, add the following near the end of your LocalSettings.php file:

// Put all SecurePasswords configuration below this point

Finally, run the update.php maintenance script or re-run the web installer to perform the necessary database schema updates. SecurePasswords increases the maximum size of the password columns on the user table to accommodate larger hashes, and adds two additional tables for its own internal tracking purposes.

Configuration parameters[edit]

$wgValidPasswords is an associative array of what to check for when validating new passwords. The default values and descriptions are below:

$wgValidPasswords = array(
	'minlength' => $wgMinimalPasswordLength, #Minimum password length, should be at least 8 for decent security
	'lowercase' => 1, #How many lowercase letters to require
	'uppercase' => 1, #How many uppercase letters to require
	'digit'     => 1, #How many digits to require
	'special'   => 0, #How many special characters to require
	'previous'  => 0, #Number of previous passwords to retain (forcing users to not pick the same password they previously used)
	'strength'  => 0, #Minimum password strength needed (0 - 100) 
	'usercheck' => true, #Should we disallow passwords that are the same as the username?
	'wordcheck' => false, #Should we check the password against a dictionary to make sure that it is not a word? (force-disabled if server does not support it)

$wgSecurePasswordsSpecialChars is a character class of special characters checked for if 'special' is true in $wgValidPasswords. Characters that have special meanings in regular expressions must be escaped with "\". The default value is below:

$wgSecurePasswordsSpecialChars = '.|\/!@#$%^&*\(\)\-_=+\[\]{}`~,<>?\'";: '; # Character class of special characters for a regex

$wgSecurePasswordRounds is the number of rounds used in the bcrypt hash algorithm. Allowed values are integers 1-31 (inclusive). The default of 10 should be sufficient, but you can also enable $wgSecurePasswordsAutoRounds to dynamically increase it if 10 is found to be hashing passwords too quickly. If that is enabled, a benchmark will be run whenever a new hash has to be generated (e.g. during user creation) to determine how many rounds results in a runtime of a least half a second (configurable via $wgSecurePasswordsAutoRoundsThreshold).

$wgSecurePasswordsExpiry is used to determine when passwords expire. This feature does not yet exist, and this section will be expanded once more information is known.

$wgSecurePasswordsEncryptPasswords specifies whether or not to encrypt the passwords in the database in addition to hashing them. If this is set, you must define $wgSecurePasswordsSecretKey to some random value to use as the encryption key. Ideally, this key would be found in a file include()'d from LocalSettings.php that is not in any web accessible directory and is only readable by the web user. Changing this key will cause all previously encrypted passwords to become invalid -- the 3.0 release will include a maintenance script to safely decrypt all password hashes in the database so that you may change this value, but at this time that maintenance script does not exist.

$wgSecurePasswordsMigrateOnLogin controls whether or not users logging in that have password hashes not in the most recent SecurePasswords format will be migrated to the most recent SecurePasswords format, or only when they change their password. This has not yet been implemented, and currently only changing one's password will migrate the hash format.

$wgSecurePasswordsStrengthTuning allows one to control the strength checker. This feature does not exist yet, and will be documented once it does.

$wgSecurePasswordsAdditionalDictionary specifies an optional filename to check in addition to the normal dictionaries if word checking is enabled. This could be used, for example, to specify a dictionary of common passwords (such as the one that ships with John the Ripper) that is checked whenever a user attempts to set their password. The file format varies depending on if you are using pspell or enchant to check against the dictionary (if both are installed, pspell is used). For pspell, use the file format described here (a header line, and then one word per line). For enchant, simply have one word per line without any special header.

$wgSecurePasswordsTrialMode allows one to "trial" or "evaluate" SecurePasswords in a way so that it can be effortlessly uninstalled later on. Enabling this option will make SecurePasswords retain the default MediaWiki password hash format in a separate table, so that in the event of a future uninstallation these hashes can be restored and thus SecurePasswords disabled. It is not recommended to enable this option for any extended period of time, as you lose the security provided by the bcrypt hash format and optional hash encryption by retaining a second hash using the default MediaWiki format. However, if you are unsure of whether or not SecurePasswords is a right fit for your wiki, enabling this option before installation will allow you to easily uninstall it later on.

$wgSecurePasswordsUninstall disables all of the additional features of SecurePasswords, and should be set when you desire to uninstall the extension. If this option is enabled, any SecurePasswords password hashes will be converted back into the default MediaWiki format whenever a user successfully logs in or changes their password, and all additional features such as password requirements, expiration, and strength checking will be disabled. Enabling this option instead of uninstalling the extension outright allows you to slowly transition your userbase back to the standard hash format, whereas simply removing the extension will render all hashes generated by SecurePasswords invalid, meaning your users would need to reset their password in order to be able to log in again (which could prove troublesome if you are not requiring email addresses on signup).

Old parameters[edit]

These configuration parameters only take effect if you are upgrading from an older version of SecurePasswords. If you are doing a fresh installation, do not configure these, leave them at the default. Certain backwards-compatibility features will be turned on if these are configured.

$wgSecurePasswordsSecretKeys is an array of three secret keys to be used when hashing passwords. These keys, once set, should never be changed and should never be shared with anyone, as they are used when hashing and encrypting the password hashes. An example value is below:

$wgSecurePasswordsSecretKeys = array(
	//these MUST be changed to something else

$wgSecurePasswordSpecialChars (typo of $wgSecurePasswordsSpecialChars) is retained for backwards compatibility. If specified, its value will overwrite that of the correctly-spelled $wgSecurePasswordsSpecialChars.


Version 3.0beta1
Major overhaul. Now uses bcrypt and supports enchant. Certain features (migrating hashes on login, strength checking, expiration, password history) are not yet implemented.
Version 2.0
Refactor code to no longer depend on $wgSecretKey. In addition, the dependencies on mcrypt and zlib are now required, and only strong hash types (in hmac format) are used to hash passwords. Backwards-compatibility with version 1.x maintained. Now beta.
Version 1.1
Removed the 'maxlength' parameter to $wgValidPasswords, moved the special characters into a global, overrides the default "Invalid password" message with a custom one explaining the restrictions (albeit in an utterly-hacked way).
Version 1.0
Initial version. Experimental.