X-Git-Url: https://git.heureux-cyclage.org/?p=lhc%2Fweb%2Fwiklou.git;a=blobdiff_plain;f=includes%2Fpassword%2FPasswordPolicyChecks.php;h=c3af88f07dd8621bdb2551ed890475c8e75ff9a3;hp=3c565359d9664d6710d41d6948636614d2fb8cb8;hb=0d3807c510762187f6364f22a3d1c78fab8f51d8;hpb=41fa0b12e7c4d38c7e7d20ac099394015ef7a55c

diff --git a/includes/password/PasswordPolicyChecks.php b/includes/password/PasswordPolicyChecks.php
index 3c565359d9..c3af88f07d 100644
--- 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
@@ -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
@@ -126,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,
@@ -134,12 +143,16 @@ 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;
 		$status = Status::newGood();
 		if ( $policyVal > 0 ) {
+			wfDeprecated( __METHOD__, '1.33' );
+
 			$langEn = Language::factory( 'en' );
 			$passwordKey = $langEn->lc( trim( $password ) );
 
@@ -173,7 +186,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