Remove hard deprecation of PasswordPolicyChecks::checkPopularPasswordBlacklist

[lhc/web/wiklou.git] / includes / password / PasswordPolicyChecks.php

diff --git a/includes/password/PasswordPolicyChecks.php b/includes/password/PasswordPolicyChecks.php
index 04ee6e9..8eecbcc 100644 (file)
--- a/includes/password/PasswordPolicyChecks.php
+++ b/includes/password/PasswordPolicyChecks.php
@@ -25,13 +25,20 @@ use MediaWiki\MediaWikiServices;
 use Wikimedia\PasswordBlacklist;
 
 /**
- * Functions to check passwords against a policy requirement
+ * Functions to check passwords against a policy requirement.
+ *
+ * $policyVal is the value configured in $wgPasswordPolicy. If the return status is fatal,
+ * the user won't be allowed to login. If the status is not good but not fatal, the user
+ * will not be allowed to set the given password (on registration or password change),
+ * but can still log in after bypassing a warning.
+ *
  * @since 1.26
+ * @see $wgPasswordPolicy
  */
 class PasswordPolicyChecks {
 
        /**
-        * Check password is longer than minimum, not fatal
+        * Check password is longer than minimum, not fatal.
         * @param int $policyVal minimal length
         * @param User $user
         * @param string $password
@@ -46,7 +53,7 @@ class PasswordPolicyChecks {
        }
 
        /**
-        * Check password is longer than minimum, fatal
+        * Check password is longer than minimum, fatal.
         * @param int $policyVal minimal length
         * @param User $user
         * @param string $password
@@ -61,7 +68,8 @@ class PasswordPolicyChecks {
        }
 
        /**
-        * Check password is shorter than maximum, fatal
+        * Check password is shorter than maximum, fatal.
+        * Intended for preventing DoS attacks when using a more expensive password hash like PBKDF2.
         * @param int $policyVal maximum length
         * @param User $user
         * @param string $password
@@ -76,7 +84,7 @@ class PasswordPolicyChecks {
        }
 
        /**
-        * Check if username and password match
+        * Check if username and password are a (case-insensitive) match.
         * @param bool $policyVal true to force compliance.
         * @param User $user
         * @param string $password
@@ -87,7 +95,7 @@ class PasswordPolicyChecks {
                $username = $user->getName();
                $contLang = MediaWikiServices::getInstance()->getContentLanguage();
                if (
-                       $policyVal && $contLang->lc( $password ) === $contLang->lc( $username )
+                       $policyVal && hash_equals( $contLang->lc( $username ), $contLang->lc( $password ) )
                ) {
                        $status->error( 'password-name-match' );
                }
@@ -95,7 +103,7 @@ class PasswordPolicyChecks {
        }
 
        /**
-        * Check if username and password are on a blacklist
+        * Check if username and password are on a blacklist of past MediaWiki default passwords.
         * @param bool $policyVal true to force compliance.
         * @param User $user
         * @param string $password
@@ -110,12 +118,15 @@ class PasswordPolicyChecks {
                $status = Status::newGood();
                $username = $user->getName();
                if ( $policyVal ) {
-                       if ( isset( $blockedLogins[$username] ) && $password == $blockedLogins[$username] ) {
+                       if (
+                               isset( $blockedLogins[$username] ) &&
+                               hash_equals( $blockedLogins[$username], $password )
+                       ) {
                                $status->error( 'password-login-forbidden' );
                        }
 
                        // Example from ApiChangeAuthenticationRequest
-                       if ( $password === 'ExamplePassword' ) {
+                       if ( hash_equals( 'ExamplePassword', $password ) ) {
                                $status->error( 'password-login-forbidden' );
                        }
                }
@@ -123,7 +134,8 @@ class PasswordPolicyChecks {
        }
 
        /**
-        * Ensure that password isn't in top X most popular passwords
+        * Ensure that password isn't in top X most popular passwords, as defined by
+        * $wgPopularPasswordFile.
         *
         * @param int $policyVal Cut off to use. Will automatically shrink to the max
         *   supported for error messages if set to more than max number of passwords on file,
@@ -131,7 +143,9 @@ class PasswordPolicyChecks {
         * @param User $user
         * @param string $password
         * @since 1.27
+        * @deprecated since 1.33
         * @return Status
+        * @see $wgPopularPasswordFile
         */
        public static function checkPopularPasswordBlacklist( $policyVal, User $user, $password ) {
                global $wgPopularPasswordFile, $wgSitename;
@@ -170,7 +184,9 @@ class PasswordPolicyChecks {
 
        /**
         * Ensure the password isn't in the list of passwords blacklisted by the
-        * wikimedia/password-blacklist library
+        * wikimedia/password-blacklist library, which contains (as of 0.1.4) the
+        * 100.000 top passwords from SecLists (as a Bloom filter, with an
+        * 0.000001 false positive ratio).
         *
         * @param bool $policyVal Whether to apply this policy
         * @param User $user