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          * @var array
  40          * @see PasswordFactory::register
  41          * @see Setup.php
  42          */
  43         private $types = [
  44                 '' => [ 'type' => '', 'class' => InvalidPassword::class ],
  45         ];
  46
  47         /**
  48          * Register a new type of password hash
  49          *
  50          * @param string $type Unique type name for the hash
  51          * @param array $config Array of configuration options
  52          */
  53         public function register( $type, array $config ) {
  54                 $config['type'] = $type;
  55                 $this->types[$type] = $config;
  56         }
  57
  58         /**
  59          * Set the default password type
  60          *
  61          * @throws InvalidArgumentException If the type is not registered
  62          * @param string $type Password hash type
  63          */
  64         public function setDefaultType( $type ) {
  65                 if ( !isset( $this->types[$type] ) ) {
  66                         throw new InvalidArgumentException( "Invalid password type $type." );
  67                 }
  68                 $this->default = $type;
  69         }
  70
  71         /**
  72          * Get the default password type
  73          *
  74          * @return string
  75          */
  76         public function getDefaultType() {
  77                 return $this->default;
  78         }
  79
  80         /**
  81          * Initialize the internal static variables using the global variables
  82          *
  83          * @param Config $config Configuration object to load data from
  84          */
  85         public function init( Config $config ) {
  86                 foreach ( $config->get( 'PasswordConfig' ) as $type => $options ) {
  87                         $this->register( $type, $options );
  88                 }
  89
  90                 $this->setDefaultType( $config->get( 'PasswordDefault' ) );
  91         }
  92
  93         /**
  94          * Get the list of types of passwords
  95          *
  96          * @return array
  97          */
  98         public function getTypes() {
  99                 return $this->types;
 100         }
 101
 102         /**
 103          * Create a new Hash object from an existing string hash
 104          *
 105          * Parse the type of a hash and create a new hash object based on the parsed type.
 106          * Pass the raw hash to the constructor of the new object. Use InvalidPassword type
 107          * if a null hash is given.
 108          *
 109          * @param string|null $hash Existing hash or null for an invalid password
 110          * @return Password
 111          * @throws PasswordError If hash is invalid or type is not recognized
 112          */
 113         public function newFromCiphertext( $hash ) {
 114                 if ( $hash === null || $hash === false || $hash === '' ) {
 115                         return new InvalidPassword( $this, [ 'type' => '' ], null );
 116                 } elseif ( $hash[0] !== ':' ) {
 117                         throw new PasswordError( 'Invalid hash given' );
 118                 }
 119
 120                 $type = substr( $hash, 1, strpos( $hash, ':', 1 ) - 1 );
 121                 if ( !isset( $this->types[$type] ) ) {
 122                         throw new PasswordError( "Unrecognized password hash type $type." );
 123                 }
 124
 125                 $config = $this->types[$type];
 126
 127                 return new $config['class']( $this, $config, $hash );
 128         }
 129
 130         /**
 131          * Make a new default password of the given type.
 132          *
 133          * @param string $type Existing type
 134          * @return Password
 135          * @throws PasswordError If hash is invalid or type is not recognized
 136          */
 137         public function newFromType( $type ) {
 138                 if ( !isset( $this->types[$type] ) ) {
 139                         throw new PasswordError( "Unrecognized password hash type $type." );
 140                 }
 141
 142                 $config = $this->types[$type];
 143
 144                 return new $config['class']( $this, $config );
 145         }
 146
 147         /**
 148          * Create a new Hash object from a plaintext password
 149          *
 150          * If no existing object is given, make a new default object. If one is given, clone that
 151          * object. Then pass the plaintext to Password::crypt().
 152          *
 153          * @param string|null $password Plaintext password, or null for an invalid password
 154          * @param Password|null $existing Optional existing hash to get options from
 155          * @return Password
 156          */
 157         public function newFromPlaintext( $password, Password $existing = null ) {
 158                 if ( $password === null ) {
 159                         return new InvalidPassword( $this, [ 'type' => '' ], null );
 160                 }
 161
 162                 if ( $existing === null ) {
 163                         $config = $this->types[$this->default];
 164                         $obj = new $config['class']( $this, $config );
 165                 } else {
 166                         $obj = clone $existing;
 167                 }
 168
 169                 $obj->crypt( $password );
 170
 171                 return $obj;
 172         }
 173
 174         /**
 175          * Determine whether a password object needs updating
 176          *
 177          * Check whether the given password is of the default type. If it is,
 178          * pass off further needsUpdate checks to Password::needsUpdate.
 179          *
 180          * @param Password $password
 181          *
 182          * @return bool True if needs update, false otherwise
 183          */
 184         public function needsUpdate( Password $password ) {
 185                 if ( $password->getType() !== $this->default ) {
 186                         return true;
 187                 } else {
 188                         return $password->needsUpdate();
 189                 }
 190         }
 191
 192         /**
 193          * Generate a random string suitable for a password
 194          *
 195          * @param int $minLength Minimum length of password to generate
 196          * @return string
 197          */
 198         public static function generateRandomPasswordString( $minLength = 10 ) {
 199                 // Decide the final password length based on our min password length,
 200                 // stopping at a minimum of 10 chars.
 201                 $length = max( 10, $minLength );
 202                 // Multiply by 1.25 to get the number of hex characters we need
 203                 // Generate random hex chars
 204                 $hex = MWCryptRand::generateHex( ceil( $length * 1.25 ) );
 205                 // Convert from base 16 to base 32 to get a proper password like string
 206                 return substr( Wikimedia\base_convert( $hex, 16, 32, $length ), -$length );
 207         }
 208
 209         /**
 210          * Create an InvalidPassword
 211          *
 212          * @return InvalidPassword
 213          */
 214         public static function newInvalidPassword() {
 215                 static $password = null;
 216
 217                 if ( $password === null ) {
 218                         $factory = new self();
 219                         $password = new InvalidPassword( $factory, [ 'type' => '' ], null );
 220                 }
 221
 222                 return $password;
 223         }
 224 }