includes/password/PasswordFactory.php

   1 <?php
   2 /**
   3  * Implements the Password class for the MediaWiki software.
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * Factory class for creating and checking Password objects
  25  *
  26  * @since 1.24
  27  */
  28 final class PasswordFactory {
  29         /**
  30          * The default PasswordHash type
  31          *
  32          * @var string
  33          * @see PasswordFactory::setDefaultType
  34          */
  35         private $default = '';
  36
  37         /**
  38          * Mapping of password types to classes
  39          *
  40          * @var array
  41          * @see PasswordFactory::register
  42          * @see Setup.php
  43          */
  44         private $types = [
  45                 '' => [ 'type' => '', 'class' => InvalidPassword::class ],
  46         ];
  47
  48         /**
  49          * Construct a new password factory.
  50          * Most of the time you'll want to use MediaWikiServices::getInstance()->getPasswordFactory
  51          * instead.
  52          * @param array $config Mapping of password type => config
  53          * @param string $default Default password type
  54          * @see PasswordFactory::register
  55          * @see PasswordFactory::setDefaultType
  56          */
  57         public function __construct( array $config = [], $default = '' ) {
  58                 foreach ( $config as $type => $options ) {
  59                         $this->register( $type, $options );
  60                 }
  61
  62                 if ( $default !== '' ) {
  63                         $this->setDefaultType( $default );
  64                 }
  65         }
  66
  67         /**
  68          * Register a new type of password hash
  69          *
  70          * @param string $type Unique type name for the hash. Will be prefixed to the password hashes
  71          *   to identify what hashing method was used.
  72          * @param array $config Array of configuration options. 'class' is required (the Password
  73          *   subclass name), everything else is passed to the constructor of that class.
  74          */
  75         public function register( $type, array $config ) {
  76                 $config['type'] = $type;
  77                 $this->types[$type] = $config;
  78         }
  79
  80         /**
  81          * Set the default password type
  82          *
  83          * This type will be used for creating new passwords when the type is not specified.
  84          * Passwords of a different type will be considered outdated and in need of update.
  85          *
  86          * @param string $type Password hash type
  87          * @throws InvalidArgumentException If the type is not registered
  88          */
  89         public function setDefaultType( $type ) {
  90                 if ( !isset( $this->types[$type] ) ) {
  91                         throw new InvalidArgumentException( "Invalid password type $type." );
  92                 }
  93                 $this->default = $type;
  94         }
  95
  96         /**
  97          * Get the default password type
  98          *
  99          * @return string
 100          */
 101         public function getDefaultType() {
 102                 return $this->default;
 103         }
 104
 105         /**
 106          * @deprecated since 1.32 Initialize settings using the constructor
 107          *
 108          * Initialize the internal static variables using the global variables
 109          *
 110          * @param Config $config Configuration object to load data from
 111          */
 112         public function init( Config $config ) {
 113                 foreach ( $config->get( 'PasswordConfig' ) as $type => $options ) {
 114                         $this->register( $type, $options );
 115                 }
 116
 117                 $this->setDefaultType( $config->get( 'PasswordDefault' ) );
 118         }
 119
 120         /**
 121          * Get the list of types of passwords
 122          *
 123          * @return array
 124          */
 125         public function getTypes() {
 126                 return $this->types;
 127         }
 128
 129         /**
 130          * Create a new Hash object from an existing string hash
 131          *
 132          * Parse the type of a hash and create a new hash object based on the parsed type.
 133          * Pass the raw hash to the constructor of the new object. Use InvalidPassword type
 134          * if a null hash is given.
 135          *
 136          * @param string|null $hash Existing hash or null for an invalid password
 137          * @return Password
 138          * @throws PasswordError If hash is invalid or type is not recognized
 139          */
 140         public function newFromCiphertext( $hash ) {
 141                 if ( $hash === null || $hash === false || $hash === '' ) {
 142                         return new InvalidPassword( $this, [ 'type' => '' ], null );
 143                 } elseif ( $hash[0] !== ':' ) {
 144                         throw new PasswordError( 'Invalid hash given' );
 145                 }
 146
 147                 $type = substr( $hash, 1, strpos( $hash, ':', 1 ) - 1 );
 148                 if ( !isset( $this->types[$type] ) ) {
 149                         throw new PasswordError( "Unrecognized password hash type $type." );
 150                 }
 151
 152                 $config = $this->types[$type];
 153
 154                 return new $config['class']( $this, $config, $hash );
 155         }
 156
 157         /**
 158          * Make a new default password of the given type.
 159          *
 160          * @param string $type Existing type
 161          * @return Password
 162          * @throws PasswordError If hash is invalid or type is not recognized
 163          */
 164         public function newFromType( $type ) {
 165                 if ( !isset( $this->types[$type] ) ) {
 166                         throw new PasswordError( "Unrecognized password hash type $type." );
 167                 }
 168
 169                 $config = $this->types[$type];
 170
 171                 return new $config['class']( $this, $config );
 172         }
 173
 174         /**
 175          * Create a new Hash object from a plaintext password
 176          *
 177          * If no existing object is given, make a new default object. If one is given, clone that
 178          * object. Then pass the plaintext to Password::crypt().
 179          *
 180          * @param string|null $password Plaintext password, or null for an invalid password
 181          * @param Password|null $existing Optional existing hash to get options from
 182          * @return Password
 183          */
 184         public function newFromPlaintext( $password, Password $existing = null ) {
 185                 if ( $password === null ) {
 186                         return new InvalidPassword( $this, [ 'type' => '' ], null );
 187                 }
 188
 189                 if ( $existing === null ) {
 190                         $config = $this->types[$this->default];
 191                         $obj = new $config['class']( $this, $config );
 192                 } else {
 193                         $obj = clone $existing;
 194                 }
 195
 196                 $obj->crypt( $password );
 197
 198                 return $obj;
 199         }
 200
 201         /**
 202          * Determine whether a password object needs updating
 203          *
 204          * Check whether the given password is of the default type. If it is,
 205          * pass off further needsUpdate checks to Password::needsUpdate.
 206          *
 207          * @param Password $password
 208          *
 209          * @return bool True if needs update, false otherwise
 210          */
 211         public function needsUpdate( Password $password ) {
 212                 if ( $password->getType() !== $this->default ) {
 213                         return true;
 214                 } else {
 215                         return $password->needsUpdate();
 216                 }
 217         }
 218
 219         /**
 220          * Generate a random string suitable for a password
 221          *
 222          * @param int $minLength Minimum length of password to generate
 223          * @return string
 224          */
 225         public static function generateRandomPasswordString( $minLength = 10 ) {
 226                 // Decide the final password length based on our min password length,
 227                 // stopping at a minimum of 10 chars.
 228                 $length = max( 10, $minLength );
 229                 // Multiply by 1.25 to get the number of hex characters we need
 230                 // Generate random hex chars
 231                 $hex = MWCryptRand::generateHex( ceil( $length * 1.25 ) );
 232                 // Convert from base 16 to base 32 to get a proper password like string
 233                 return substr( Wikimedia\base_convert( $hex, 16, 32, $length ), -$length );
 234         }
 235
 236         /**
 237          * Create an InvalidPassword
 238          *
 239          * @return InvalidPassword
 240          */
 241         public static function newInvalidPassword() {
 242                 static $password = null;
 243
 244                 if ( $password === null ) {
 245                         $factory = new self();
 246                         $password = new InvalidPassword( $factory, [ 'type' => '' ], null );
 247                 }
 248
 249                 return $password;
 250         }
 251 }