3 * Password policy checking for a user
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * Check if a user's password complies with any password policies that apply to that
25 * user, based on the user's group membership.
28 class UserPasswordPolicy
{
36 * Mapping of statements to the function that will test the password for compliance. The
37 * checking functions take the policy value, the user, and password, and return a Status
38 * object indicating compliance.
41 private $policyCheckFunctions;
44 * @param array $policies
45 * @param array $checks mapping statement to its checking function. Checking functions are
46 * called with the policy value for this user, the user object, and the password to check.
48 public function __construct( array $policies, array $checks ) {
49 if ( !isset( $policies['default'] ) ) {
50 throw new InvalidArgumentException(
51 'Must include a \'default\' password policy'
54 $this->policies
= $policies;
56 foreach ( $checks as $statement => $check ) {
57 if ( !is_callable( $check ) ) {
58 throw new InvalidArgumentException(
59 "Policy check functions must be callable. '$statement' isn't callable."
62 $this->policyCheckFunctions
[$statement] = $check;
67 * Check if a password meets the effective password policy for a User.
68 * @param User $user whose policy we are checking
69 * @param string $password the password to check
70 * @return Status error to indicate the password didn't meet the policy, or fatal to
71 * indicate the user shouldn't be allowed to login. The status value will be an array,
72 * potentially with the following keys:
73 * - forceChange: do not allow the user to login without changing the password if invalid.
74 * - suggestChangeOnLogin: prompt for a password change on login if the password is invalid.
76 public function checkUserPassword( User
$user, $password ) {
77 $effectivePolicy = $this->getPoliciesForUser( $user );
78 return $this->checkPolicies(
82 $this->policyCheckFunctions
87 * Check if a password meets the effective password policy for a User, using a set
88 * of groups they may or may not belong to. This function does not use the DB, so can
89 * be used in the installer.
90 * @param User $user whose policy we are checking
91 * @param string $password the password to check
92 * @param array $groups list of groups to which we assume the user belongs
93 * @return Status error to indicate the password didn't meet the policy, or fatal to
94 * indicate the user shouldn't be allowed to login. The status value will be an array,
95 * potentially with the following keys:
96 * - forceChange: do not allow the user to login without changing the password if invalid.
97 * - suggestChangeOnLogin: prompt for a password change on login if the password is invalid.
99 public function checkUserPasswordForGroups( User
$user, $password, array $groups ) {
100 $effectivePolicy = self
::getPoliciesForGroups(
103 $this->policies
['default']
105 return $this->checkPolicies(
109 $this->policyCheckFunctions
115 * @param string $password
116 * @param array $policies
117 * @param array $policyCheckFunctions
120 private function checkPolicies( User
$user, $password, $policies, $policyCheckFunctions ) {
121 $status = Status
::newGood( [] );
122 $forceChange = false;
123 $suggestChangeOnLogin = false;
124 foreach ( $policies as $policy => $settings ) {
125 if ( !isset( $policyCheckFunctions[$policy] ) ) {
126 throw new DomainException( "Invalid password policy config. No check defined for '$policy'." );
128 if ( !is_array( $settings ) ) {
130 $settings = [ 'value' => $settings ];
132 if ( !array_key_exists( 'value', $settings ) ) {
133 throw new DomainException( "Invalid password policy config. No value defined for '$policy'." );
135 $value = $settings['value'];
136 /** @var StatusValue $policyStatus */
137 $policyStatus = call_user_func(
138 $policyCheckFunctions[$policy],
144 if ( !$policyStatus->isGood() ) {
145 if ( !empty( $settings['forceChange'] ) ) {
149 if ( !empty( $settings['suggestChangeOnLogin'] ) ) {
150 $suggestChangeOnLogin = true;
153 $status->merge( $policyStatus );
156 if ( $status->isOK() ) {
157 if ( $forceChange ) {
158 $status->value
['forceChange'] = true;
159 } elseif ( $suggestChangeOnLogin ) {
160 $status->value
['suggestChangeOnLogin'] = true;
168 * Get the policy for a user, based on their group membership. Public so
169 * UI elements can access and inform the user.
171 * @return array the effective policy for $user
173 public function getPoliciesForUser( User
$user ) {
174 $effectivePolicy = self
::getPoliciesForGroups(
176 $user->getEffectiveGroups(),
177 $this->policies
['default']
180 Hooks
::run( 'PasswordPoliciesForUser', [ $user, &$effectivePolicy ] );
182 return $effectivePolicy;
186 * Utility function to get the effective policy from a list of policies, based
187 * on a list of groups.
188 * @param array $policies list of policies to consider
189 * @param array $userGroups the groups from which we calculate the effective policy
190 * @param array $defaultPolicy the default policy to start from
191 * @return array effective policy
193 public static function getPoliciesForGroups( array $policies, array $userGroups,
196 $effectivePolicy = $defaultPolicy;
197 foreach ( $policies as $group => $policy ) {
198 if ( in_array( $group, $userGroups ) ) {
199 $effectivePolicy = self
::maxOfPolicies(
206 return $effectivePolicy;
210 * Utility function to get a policy that is the most restrictive of $p1 and $p2. For
211 * simplicity, we setup the policy values so the maximum value is always more restrictive.
212 * It is also used recursively to merge settings within the same policy.
215 * @return array containing the more restrictive values of $p1 and $p2
217 public static function maxOfPolicies( array $p1, array $p2 ) {
219 $keys = array_merge( array_keys( $p1 ), array_keys( $p2 ) );
220 foreach ( $keys as $key ) {
221 if ( !isset( $p1[$key] ) ) {
222 $ret[$key] = $p2[$key];
223 } elseif ( !isset( $p2[$key] ) ) {
224 $ret[$key] = $p1[$key];
225 } elseif ( !is_array( $p1[$key] ) && !is_array( $p2[$key] ) ) {
226 $ret[$key] = max( $p1[$key], $p2[$key] );
228 if ( !is_array( $p1[$key] ) ) {
229 $p1[$key] = [ 'value' => $p1[$key] ];
230 } elseif ( !is_array( $p2[$key] ) ) {
231 $p2[$key] = [ 'value' => $p2[$key] ];
233 $ret[$key] = self
::maxOfPolicies( $p1[$key], $p2[$key] );