includes/auth/Throttler.php

   1 <?php
   2 /**
   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.
   7  *
   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.
  12  *
  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
  17  *
  18  * @file
  19  * @ingroup Auth
  20  */
  21
  22 namespace MediaWiki\Auth;
  23
  24 use BagOStuff;
  25 use Config;
  26 use MediaWiki\Logger\LoggerFactory;
  27 use Psr\Log\LoggerAwareInterface;
  28 use Psr\Log\LoggerInterface;
  29 use Psr\Log\LogLevel;
  30 use Psr\Log\NullLogger;
  31 use User;
  32
  33 /**
  34  * A helper class for throttling authentication attempts.
  35  * @package MediaWiki\Auth
  36  * @ingroup Auth
  37  * @since 1.27
  38  */
  39 class Throttler implements LoggerAwareInterface {
  40         /** @var string */
  41         protected $type;
  42         /**
  43          * See documentation of $wgPasswordAttemptThrottle for format. Old (pre-1.27) format is not
  44          * allowed here.
  45          * @var array
  46          * @see https://www.mediawiki.org/wiki/Manual:$wgPasswordAttemptThrottle
  47          */
  48         protected $conditions;
  49         /** @var BagOStuff */
  50         protected $cache;
  51         /** @var LoggerInterface */
  52         protected $logger;
  53         /** @var int|float */
  54         protected $warningLimit;
  55
  56         /**
  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.
  64          */
  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 ) ) );
  71                 }
  72
  73                 if ( $conditions === null ) {
  74                         $config = \ConfigFactory::getDefaultInstance()->makeConfig( 'main' );
  75                         $conditions = $config->get( 'PasswordAttemptThrottle' );
  76                         $params += [
  77                                 'type' => 'password',
  78                                 'cache' => \ObjectCache::getLocalClusterInstance(),
  79                                 'warningLimit' => 50,
  80                         ];
  81                 } else {
  82                         $params += [
  83                                 'type' => 'custom',
  84                                 'cache' => \ObjectCache::getLocalClusterInstance(),
  85                                 'warningLimit' => INF,
  86                         ];
  87                 }
  88
  89                 $this->type = $params['type'];
  90                 $this->conditions = static::normalizeThrottleConditions( $conditions );
  91                 $this->cache = $params['cache'];
  92                 $this->warningLimit = $params['warningLimit'];
  93
  94                 $this->setLogger( LoggerFactory::getInstance( 'throttler' ) );
  95         }
  96
  97         public function setLogger( LoggerInterface $logger ) {
  98                 $this->logger = $logger;
  99         }
 100
 101         /**
 102          * Increase the throttle counter and return whether the attempt should be throttled.
 103          *
 104          * Should be called before an authentication attempt.
 105          *
 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
 114          */
 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' );
 118                 }
 119
 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'];
 125
 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 ) {
 129                                 continue;
 130                         }
 131
 132                         $throttleKey = wfGlobalCacheKey( 'throttler', $this->type, $index, $ipKey, $userKey );
 133                         $throttleCount = $this->cache->get( $throttleKey );
 134
 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,
 142                                         'index' => $index,
 143                                         'ip' => $ipKey,
 144                                         'username' => $username,
 145                                         'count' => $count,
 146                                         'expiry' => $expiry,
 147                                         // @codeCoverageIgnoreStart
 148                                         'method' => $caller ?: __METHOD__,
 149                                         // @codeCoverageIgnoreEnd
 150                                 ] );
 151
 152                                 return [
 153                                         'throttleIndex' => $index,
 154                                         'count' => $count,
 155                                         'wait' => $expiry,
 156                                 ];
 157                         }
 158                 }
 159                 return false;
 160         }
 161
 162         /**
 163          * Clear the throttle counter.
 164          *
 165          * Should be called after a successful authentication attempt.
 166          *
 167          * @param string|null $username
 168          * @param string|null $ip
 169          * @throws \MWException
 170          */
 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 );
 177                 }
 178         }
 179
 180         /**
 181          * Handles B/C for $wgPasswordAttemptThrottle.
 182          * @param array $throttleConditions
 183          * @return array
 184          * @see $wgPasswordAttemptThrottle for structure
 185          */
 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 {type} hit, throttled for {expiry} seconds due to {count} attempts '
 198                         . 'from username {username} and IP {ip}';
 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 }