3 * Implements the Password class for the MediaWiki software.
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.
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.
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
24 * Factory class for creating and checking Password objects
28 final class PasswordFactory
{
30 * The default PasswordHash type
33 * @see PasswordFactory::setDefaultType
35 private $default = '';
38 * Mapping of password types to classes
41 * @see PasswordFactory::register
45 '' => [ 'type' => '', 'class' => InvalidPassword
::class ],
49 * Construct a new password factory.
50 * Most of the time you'll want to use MediaWikiServices::getInstance()->getPasswordFactory
52 * @param array $config Mapping of password type => config
53 * @param string $default Default password type
54 * @see PasswordFactory::register
55 * @see PasswordFactory::setDefaultType
57 public function __construct( array $config = [], $default = '' ) {
58 foreach ( $config as $type => $options ) {
59 $this->register( $type, $options );
62 if ( $default !== '' ) {
63 $this->setDefaultType( $default );
68 * Register a new type of password hash
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.
75 public function register( $type, array $config ) {
76 $config['type'] = $type;
77 $this->types
[$type] = $config;
81 * Set the default password type
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.
86 * @param string $type Password hash type
87 * @throws InvalidArgumentException If the type is not registered
89 public function setDefaultType( $type ) {
90 if ( !isset( $this->types
[$type] ) ) {
91 throw new InvalidArgumentException( "Invalid password type $type." );
93 $this->default = $type;
97 * Get the default password type
101 public function getDefaultType() {
102 return $this->default;
106 * @deprecated since 1.32 Initialize settings using the constructor
108 * Initialize the internal static variables using the global variables
110 * @param Config $config Configuration object to load data from
112 public function init( Config
$config ) {
113 foreach ( $config->get( 'PasswordConfig' ) as $type => $options ) {
114 $this->register( $type, $options );
117 $this->setDefaultType( $config->get( 'PasswordDefault' ) );
121 * Get the list of types of passwords
125 public function getTypes() {
130 * Create a new Hash object from an existing string hash
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.
136 * @param string|null $hash Existing hash or null for an invalid password
138 * @throws PasswordError If hash is invalid or type is not recognized
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' );
147 $type = substr( $hash, 1, strpos( $hash, ':', 1 ) - 1 );
148 if ( !isset( $this->types
[$type] ) ) {
149 throw new PasswordError( "Unrecognized password hash type $type." );
152 $config = $this->types
[$type];
154 return new $config['class']( $this, $config, $hash );
158 * Make a new default password of the given type.
160 * @param string $type Existing type
162 * @throws PasswordError If hash is invalid or type is not recognized
164 public function newFromType( $type ) {
165 if ( !isset( $this->types
[$type] ) ) {
166 throw new PasswordError( "Unrecognized password hash type $type." );
169 $config = $this->types
[$type];
171 return new $config['class']( $this, $config );
175 * Create a new Hash object from a plaintext password
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().
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
184 public function newFromPlaintext( $password, Password
$existing = null ) {
185 if ( $password === null ) {
186 return new InvalidPassword( $this, [ 'type' => '' ], null );
189 if ( $existing === null ) {
190 $config = $this->types
[$this->default];
191 $obj = new $config['class']( $this, $config );
193 $obj = clone $existing;
196 $obj->crypt( $password );
202 * Determine whether a password object needs updating
204 * Check whether the given password is of the default type. If it is,
205 * pass off further needsUpdate checks to Password::needsUpdate.
207 * @param Password $password
209 * @return bool True if needs update, false otherwise
211 public function needsUpdate( Password
$password ) {
212 if ( $password->getType() !== $this->default ) {
215 return $password->needsUpdate();
220 * Generate a random string suitable for a password
222 * @param int $minLength Minimum length of password to generate
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 );
237 * Create an InvalidPassword
239 * @return InvalidPassword
241 public static function newInvalidPassword() {
242 static $password = null;
244 if ( $password === null ) {
245 $factory = new self();
246 $password = new InvalidPassword( $factory, [ 'type' => '' ], null );