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