MediaWiki  master
Throttler.php
Go to the documentation of this file.
1 <?php
22 namespace MediaWiki\Auth;
23 
24 use BagOStuff;
28 use Psr\Log\LoggerAwareInterface;
29 use Psr\Log\LoggerInterface;
30 use Psr\Log\LogLevel;
31 
38 class Throttler implements LoggerAwareInterface {
40  protected $type;
47  protected $conditions;
49  protected $cache;
51  protected $logger;
53  protected $warningLimit;
54 
64  public function __construct( array $conditions = null, array $params = [] ) {
65  $invalidParams = array_diff_key( $params,
66  array_fill_keys( [ 'type', 'cache', 'warningLimit' ], true ) );
67  if ( $invalidParams ) {
68  throw new \InvalidArgumentException( 'unrecognized parameters: '
69  . implode( ', ', array_keys( $invalidParams ) ) );
70  }
71 
72  if ( $conditions === null ) {
73  $config = MediaWikiServices::getInstance()->getMainConfig();
75  $params += [
76  'type' => 'password',
78  'warningLimit' => 50,
79  ];
80  } else {
81  $params += [
82  'type' => 'custom',
84  'warningLimit' => INF,
85  ];
86  }
87 
88  $this->type = $params['type'];
89  $this->conditions = static::normalizeThrottleConditions( $conditions );
90  $this->cache = $params['cache'];
91  $this->warningLimit = $params['warningLimit'];
92 
93  $this->setLogger( LoggerFactory::getInstance( 'throttler' ) );
94  }
95 
96  public function setLogger( LoggerInterface $logger ) {
97  $this->logger = $logger;
98  }
99 
114  public function increase( $username = null, $ip = null, $caller = null ) {
115  if ( $username === null && $ip === null ) {
116  throw new \InvalidArgumentException( 'Either username or IP must be set for throttling' );
117  }
118 
119  $userKey = $username ? md5( $username ) : null;
120  foreach ( $this->conditions as $index => $throttleCondition ) {
121  $ipKey = isset( $throttleCondition['allIPs'] ) ? null : $ip;
122  $count = $throttleCondition['count'];
123  $expiry = $throttleCondition['seconds'];
124 
125  // a limit of 0 is used as a disable flag in some throttling configuration settings
126  // throttling the whole world is probably a bad idea
127  if ( !$count || $userKey === null && $ipKey === null ) {
128  continue;
129  }
130 
131  $throttleKey = $this->cache->makeGlobalKey(
132  'throttler',
133  $this->type,
134  $index,
135  $ipKey ?? '',
136  $userKey ?? ''
137  );
138  $throttleCount = $this->cache->get( $throttleKey );
139  if ( $throttleCount && $throttleCount >= $count ) {
140  // Throttle limited reached
141  $this->logRejection( [
142  'throttle' => $this->type,
143  'index' => $index,
144  'ipKey' => $ipKey,
145  'username' => $username,
146  'count' => $count,
147  'expiry' => $expiry,
148  // @codeCoverageIgnoreStart
149  'method' => $caller ?: __METHOD__,
150  // @codeCoverageIgnoreEnd
151  ] );
152 
153  return [ 'throttleIndex' => $index, 'count' => $count, 'wait' => $expiry ];
154  } else {
155  $this->cache->incrWithInit( $throttleKey, $expiry, 1 );
156  }
157  }
158 
159  return false;
160  }
161 
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 = $this->cache->makeGlobalKey( 'throttler', $this->type, $index, $ipKey, $userKey );
176  $this->cache->delete( $throttleKey );
177  }
178  }
179 
186  protected static function normalizeThrottleConditions( $throttleConditions ) {
187  if ( !is_array( $throttleConditions ) ) {
188  return [];
189  }
190  if ( isset( $throttleConditions['count'] ) ) { // old style
191  $throttleConditions = [ $throttleConditions ];
192  }
193  return $throttleConditions;
194  }
195 
196  protected function logRejection( array $context ) {
197  $logMsg = 'Throttle {throttle} hit, throttled for {expiry} seconds due to {count} attempts '
198  . 'from username {username} and IP {ipKey}';
199 
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;
203 
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 );
208  }
209 
210 }
Class representing a cache/ephemeral data store.
Definition: BagOStuff.php:85
array[] $conditions
See documentation of $wgPasswordAttemptThrottle for format.
Definition: Throttler.php:47
increase( $username=null, $ip=null, $caller=null)
Increase the throttle counter and return whether the attempt should be throttled.
Definition: Throttler.php:114
clear( $username=null, $ip=null)
Clear the throttle counter.
Definition: Throttler.php:171
setLogger(LoggerInterface $logger)
Definition: Throttler.php:96
__construct(array $conditions=null, array $params=[])
Definition: Throttler.php:64
logRejection(array $context)
Definition: Throttler.php:196
static normalizeThrottleConditions( $throttleConditions)
Handles B/C for $wgPasswordAttemptThrottle.
Definition: Throttler.php:186
LoggerInterface $logger
Definition: Throttler.php:51
PSR-3 logger instance factory.
static getInstance( $channel)
Get a named logger instance from the currently configured logger factory.
A class containing constants representing the names of configuration variables.
const PasswordAttemptThrottle
Name constant for the PasswordAttemptThrottle setting, for use with Config::get()
Service locator for MediaWiki core services.
static getInstance()
Returns the global default instance of the top level service locator.
static getLocalClusterInstance()
Get the main cluster-local cache object.