3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 * http://www.gnu.org/copyleft/gpl.html
22 namespace MediaWiki\Auth
;
26 use MediaWiki\Logger\LoggerFactory
;
27 use Psr\Log\LoggerAwareInterface
;
28 use Psr\Log\LoggerInterface
;
30 use Psr\Log\NullLogger
;
34 * A helper class for throttling authentication attempts.
35 * @package MediaWiki\Auth
39 class Throttler
implements LoggerAwareInterface
{
43 * See documentation of $wgPasswordAttemptThrottle for format. Old (pre-1.27) format is not
46 * @see https://www.mediawiki.org/wiki/Manual:$wgPasswordAttemptThrottle
48 protected $conditions;
51 /** @var LoggerInterface */
54 protected $warningLimit;
57 * @param array $conditions An array of arrays describing throttling conditions.
58 * Defaults to $wgPasswordAttemptThrottle. See documentation of that variable for format.
59 * @param array $params Parameters (all optional):
60 * - type: throttle type, used as a namespace for counters,
61 * - cache: a BagOStuff object where throttle counters are stored.
62 * - warningLimit: the log level will be raised to warning when rejecting an attempt after
63 * no less than this many failures.
65 public function __construct( array $conditions = null, array $params = [] ) {
66 $invalidParams = array_diff_key( $params,
67 array_fill_keys( [ 'type', 'cache', 'warningLimit' ], true ) );
68 if ( $invalidParams ) {
69 throw new \
InvalidArgumentException( 'unrecognized parameters: '
70 . implode( ', ', array_keys( $invalidParams ) ) );
73 if ( $conditions === null ) {
74 $config = \ConfigFactory
::getDefaultInstance()->makeConfig( 'main' );
75 $conditions = $config->get( 'PasswordAttemptThrottle' );
78 'cache' => \ObjectCache
::getLocalClusterInstance(),
84 'cache' => \ObjectCache
::getLocalClusterInstance(),
85 'warningLimit' => INF
,
89 $this->type
= $params['type'];
90 $this->conditions
= static::normalizeThrottleConditions( $conditions );
91 $this->cache
= $params['cache'];
92 $this->warningLimit
= $params['warningLimit'];
94 $this->setLogger( LoggerFactory
::getInstance( 'throttler' ) );
97 public function setLogger( LoggerInterface
$logger ) {
98 $this->logger
= $logger;
102 * Increase the throttle counter and return whether the attempt should be throttled.
104 * Should be called before an authentication attempt.
106 * @param string|null $username
107 * @param string|null $ip
108 * @param string|null $caller The authentication method from which we were called.
109 * @return array|false False if the attempt should not be throttled, an associative array
110 * with three keys otherwise:
111 * - throttleIndex: which throttle condition was met (a key of the conditions array)
112 * - count: throttle count (ie. number of failed attempts)
113 * - wait: time in seconds until authentication can be attempted
115 public function increase( $username = null, $ip = null, $caller = null ) {
116 if ( $username === null && $ip === null ) {
117 throw new \
InvalidArgumentException( 'Either username or IP must be set for throttling' );
120 $userKey = $username ?
md5( $username ) : null;
121 foreach ( $this->conditions
as $index => $throttleCondition ) {
122 $ipKey = isset( $throttleCondition['allIPs'] ) ?
null : $ip;
123 $count = $throttleCondition['count'];
124 $expiry = $throttleCondition['seconds'];
126 // a limit of 0 is used as a disable flag in some throttling configuration settings
127 // throttling the whole world is probably a bad idea
128 if ( !$count ||
$userKey === null && $ipKey === null ) {
132 $throttleKey = wfGlobalCacheKey( 'throttler', $this->type
, $index, $ipKey, $userKey );
133 $throttleCount = $this->cache
->get( $throttleKey );
135 if ( !$throttleCount ) { // counter not started yet
136 $this->cache
->add( $throttleKey, 1, $expiry );
137 } elseif ( $throttleCount < $count ) { // throttle limited not yet reached
138 $this->cache
->incr( $throttleKey );
139 } else { // throttled
140 $this->logRejection( [
141 'type' => $this->type
,
144 'username' => $username,
147 // @codeCoverageIgnoreStart
148 'method' => $caller ?
: __METHOD__
,
149 // @codeCoverageIgnoreEnd
153 'throttleIndex' => $index,
163 * Clear the throttle counter.
165 * Should be called after a successful authentication attempt.
167 * @param string|null $username
168 * @param string|null $ip
169 * @throws \MWException
171 public function clear( $username = null, $ip = null ) {
172 $userKey = $username ?
md5( $username ) : null;
173 foreach ( $this->conditions
as $index => $specificThrottle ) {
174 $ipKey = isset( $specificThrottle['allIPs'] ) ?
null : $ip;
175 $throttleKey = wfGlobalCacheKey( 'throttler', $this->type
, $index, $ipKey, $userKey );
176 $this->cache
->delete( $throttleKey );
181 * Handles B/C for $wgPasswordAttemptThrottle.
182 * @param array $throttleConditions
184 * @see $wgPasswordAttemptThrottle for structure
186 protected static function normalizeThrottleConditions( $throttleConditions ) {
187 if ( !is_array( $throttleConditions ) ) {
190 if ( isset( $throttleConditions['count'] ) ) { // old style
191 $throttleConditions = [ $throttleConditions ];
193 return $throttleConditions;
196 protected function logRejection( array $context ) {
197 $logMsg = 'Throttle {type} hit, throttled for {expiry} seconds due to {count} attempts '
198 . 'from username {username} and IP {ip}';
200 // If we are hitting a throttle for >= warningLimit attempts, it is much more likely to be
201 // an attack than someone simply forgetting their password, so log it at a higher level.
202 $level = $context['count'] >= $this->warningLimit ? LogLevel
::WARNING
: LogLevel
::INFO
;
204 // It should be noted that once the throttle is hit, every attempt to login will
205 // generate the log message until the throttle expires, not just the attempt that
206 // puts the throttle over the top.
207 $this->logger
->log( $level, $logMsg, $context );