includes/password/ParameterizedPassword.php

   1 <?php
   2 /**
   3  * Implements the ParameterizedPassword 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 declare( strict_types = 1 );
  24
  25 namespace MediaWiki\Password;
  26
  27 /**
  28  * Helper class for password hash types that have a delimited set of parameters
  29  * inside the hash.
  30  *
  31  * All passwords are in the form of :<TYPE>:... as explained in the main Password
  32  * class. This class is for hashes in the form of :<TYPE>:<PARAM1>:<PARAM2>:... where
  33  * <PARAM1>, <PARAM2>, etc. are parameters that determine how the password was hashed.
  34  * Of course, the internal delimiter (which is : by convention and default), can be
  35  * changed by overriding the ParameterizedPassword::getDelimiter() function.
  36  *
  37  * This class requires overriding an additional function: ParameterizedPassword::getDefaultParams().
  38  * See the function description for more details on the implementation.
  39  *
  40  * @since 1.24
  41  */
  42 abstract class ParameterizedPassword extends Password {
  43         /**
  44          * Named parameters that have default values for this password type
  45          * @var array
  46          */
  47         protected $params = [];
  48
  49         /**
  50          * Extra arguments that were found in the hash. This may or may not make
  51          * the hash invalid.
  52          * @var string[]
  53          */
  54         protected $args = [];
  55
  56         /**
  57          * @inheritDoc
  58          */
  59         protected function parseHash( ?string $hash ): void {
  60                 parent::parseHash( $hash );
  61
  62                 if ( $hash === null ) {
  63                         $this->params = $this->getDefaultParams();
  64                         return;
  65                 }
  66
  67                 $parts = explode( $this->getDelimiter(), $hash );
  68                 $paramKeys = array_keys( $this->getDefaultParams() );
  69
  70                 if ( count( $parts ) < count( $paramKeys ) ) {
  71                         throw new PasswordError( 'Hash is missing required parameters.' );
  72                 }
  73
  74                 if ( $paramKeys ) {
  75                         $this->args = array_splice( $parts, count( $paramKeys ) );
  76                         $this->params = array_combine( $paramKeys, $parts );
  77                 } else {
  78                         $this->args = $parts;
  79                 }
  80
  81                 if ( $this->args ) {
  82                         $this->hash = array_pop( $this->args );
  83                 } else {
  84                         $this->hash = null;
  85                 }
  86         }
  87
  88         public function needsUpdate(): bool {
  89                 return $this->params !== $this->getDefaultParams();
  90         }
  91
  92         public function toString(): string {
  93                 $str = ':' . $this->config['type'] . ':';
  94
  95                 if ( count( $this->params ) || count( $this->args ) ) {
  96                         $str .= implode( $this->getDelimiter(), array_merge( $this->params, $this->args ) );
  97                         $str .= $this->getDelimiter();
  98                 }
  99
 100                 $res = $str . $this->hash;
 101                 $this->assertIsSafeSize( $res );
 102                 return $res;
 103         }
 104
 105         /**
 106          * Returns the delimiter for the parameters inside the hash
 107          *
 108          * @return string
 109          */
 110         abstract protected function getDelimiter(): string;
 111
 112         /**
 113          * Return an ordered array of default parameters for this password hash
 114          *
 115          * The keys should be the parameter names and the values should be the default
 116          * values. Additionally, the order of the array should be the order in which they
 117          * appear in the hash.
 118          *
 119          * When parsing a password hash, the constructor will split the hash based on
 120          * the delimiter, and consume as many parts as it can, matching each to a parameter
 121          * in this list. Once all the parameters have been filled, all remaining parts will
 122          * be considered extra arguments, except, of course, for the very last part, which
 123          * is the hash itself.
 124          *
 125          * @return array
 126          */
 127         abstract protected function getDefaultParams(): array;
 128 }
 129
 130 /** @deprecated since 1.43 use MediaWiki\\Password\\ParameterizedPassword */
 131 class_alias( ParameterizedPassword::class, 'ParameterizedPassword' );