MediaWiki master
MediaWiki\Password\Password Class Reference

Represents a password hash for use in authentication. More...

Inherited by MediaWiki\Password\Argon2Password, MediaWiki\Password\InvalidPassword, and MediaWiki\Password\ParameterizedPassword.

Collaboration diagram for MediaWiki\Password\Password:

Public Member Functions

 __construct (PasswordFactory $factory, array $config, string $hash=null)
 Construct the Password object using a string hash.
 
 crypt (string $password)
 Hash a password and store the result in this object.
 
 getType ()
 Get the type name of the password.
 
 needsUpdate ()
 Determine if the hash needs to be updated.
 
 toString ()
 Convert this hash to a string that can be stored in the database.
 
 verify (string $password)
 Checks whether the given password matches the hash stored in this object.
 

Protected Member Functions

 assertIsSafeSize (string $hash)
 Assert that hash will fit in a tinyblob field.
 
 isSupported ()
 Whether current password type is supported on this system.
 
 parseHash (?string $hash)
 Perform any parsing necessary on the hash to see if the hash is valid and/or to perform logic for seeing if the hash needs updating.
 

Protected Attributes

array $config
 Array of configuration variables injected from the constructor.
 
PasswordFactory $factory
 Factory that created the object.
 
string null $hash
 String representation of the hash without the type.
 

Detailed Description

Represents a password hash for use in authentication.

Note: All password types are transparently prefixed with :<TYPE>:, where <TYPE> is the registered type of the hash. This prefix is stripped in the constructor and is added back in the toString() function.

When inheriting this class, there are a couple of expectations to be fulfilled:

  • If Password::toString() is called on an object, and the result is passed back in to PasswordFactory::newFromCiphertext(), the result will be identical to the original. With these two points in mind, when creating a new Password sub-class, there are some functions you have to override (because they are abstract) and others that you may want to override.

The abstract functions that must be overridden are:

  • Password::crypt(), which takes a plaintext password and hashes it into a string hash suitable for being passed to the constructor of that class, and then stores that hash (and whatever other data) into the internal state of the object. The functions that can optionally be overridden are:
  • Password::parseHash(), which can be useful to override if you need to extract values from or otherwise parse a password hash when it's passed to the constructor.
  • Password::needsUpdate(), which can be useful if a specific password hash has different logic for when the hash needs to be updated.
  • Password::toString(), which can be useful if the hash was changed in the constructor and needs to be re-assembled before being returned as a string. This function is expected to add the type back on to the hash, so make sure to do that if you override the function.
  • Password::verify() - This function checks if $this->hash was generated with the given password. The default is to just hash the password and do a timing-safe string comparison with $this->hash.

After creating a new password hash type, it can be registered using the static Password::register() method. The default type is set using the Password::setDefaultType() type. Types must be registered before they can be set as the default.

Since
1.24

Definition at line 66 of file Password.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Password\Password::__construct ( PasswordFactory $factory,
array $config,
string $hash = null )
final

Construct the Password object using a string hash.

It is strongly recommended not to call this function directly unless you have a reason to. Use the PasswordFactory class instead.

Parameters
PasswordFactory$factoryFactory object that created the password
array$configArray of engine configuration options for hashing
string | null$hashThe raw hash, including the type

Definition at line 99 of file Password.php.

References MediaWiki\Password\Password\$config, MediaWiki\Password\Password\$factory, MediaWiki\Password\Password\$hash, MediaWiki\Password\Password\isSupported(), and MediaWiki\Password\Password\parseHash().

Member Function Documentation

◆ assertIsSafeSize()

MediaWiki\Password\Password::assertIsSafeSize ( string $hash)
finalprotected

Assert that hash will fit in a tinyblob field.

This prevents MW from inserting it into the DB and having MySQL silently truncating it, locking the user out of their account.

Parameters
string$hashThe hash in question.
Exceptions
PasswordErrorIf hash does not fit in DB.

Definition at line 196 of file Password.php.

◆ crypt()

MediaWiki\Password\Password::crypt ( string $password)
abstract

Hash a password and store the result in this object.

The result of the password hash should be put into the internal state of the hash object.

Parameters
string$passwordPassword to hash
Exceptions
PasswordErrorIf an internal error occurs in hashing

Reimplemented in MediaWiki\Password\AbstractPbkdf2Password, MediaWiki\Password\Argon2Password, MediaWiki\Password\BcryptPassword, MediaWiki\Password\EncryptedPassword, MediaWiki\Password\LayeredParameterizedPassword, MediaWiki\Password\InvalidPassword, MediaWiki\Password\MWOldPassword, and MediaWiki\Password\MWSaltedPassword.

Referenced by MediaWiki\Password\LayeredParameterizedPassword\partialCrypt().

◆ getType()

MediaWiki\Password\Password::getType ( )
final

Get the type name of the password.

Returns
string Password type

Definition at line 123 of file Password.php.

◆ isSupported()

MediaWiki\Password\Password::isSupported ( )
protected

Whether current password type is supported on this system.

Returns
bool

Reimplemented in MediaWiki\Password\Argon2Password.

Definition at line 132 of file Password.php.

Referenced by MediaWiki\Password\Password\__construct().

◆ needsUpdate()

MediaWiki\Password\Password::needsUpdate ( )
abstract

Determine if the hash needs to be updated.

Returns
bool True if needs update, false otherwise

Reimplemented in MediaWiki\Password\Argon2Password, MediaWiki\Password\InvalidPassword, and MediaWiki\Password\ParameterizedPassword.

◆ parseHash()

MediaWiki\Password\Password::parseHash ( ?string $hash)
protected

Perform any parsing necessary on the hash to see if the hash is valid and/or to perform logic for seeing if the hash needs updating.

Parameters
string | null$hashThe hash, with the :<TYPE>: prefix stripped
Exceptions
PasswordErrorIf there is an error in parsing the hash

Reimplemented in MediaWiki\Password\BcryptPassword, and MediaWiki\Password\ParameterizedPassword.

Definition at line 143 of file Password.php.

Referenced by MediaWiki\Password\Password\__construct().

◆ toString()

MediaWiki\Password\Password::toString ( )

Convert this hash to a string that can be stored in the database.

The resulting string should be considered the serialized representation of this hash, i.e., if the return value were recycled back into PasswordFactory::newFromCiphertext, the returned object would be equivalent to this; also, if two objects return the same value from this function, they are considered equivalent.

Returns
string
Exceptions
PasswordErrorif password cannot be serialized to fit a tinyblob.

Reimplemented in MediaWiki\Password\Argon2Password, MediaWiki\Password\InvalidPassword, and MediaWiki\Password\ParameterizedPassword.

Definition at line 180 of file Password.php.

◆ verify()

MediaWiki\Password\Password::verify ( string $password)

Checks whether the given password matches the hash stored in this object.

Parameters
string$passwordPassword to check
Returns
bool

Reimplemented in MediaWiki\Password\Argon2Password, MediaWiki\Password\EncryptedPassword, and MediaWiki\Password\InvalidPassword.

Definition at line 159 of file Password.php.

Member Data Documentation

◆ $config

array MediaWiki\Password\Password::$config
protected

Array of configuration variables injected from the constructor.

Definition at line 82 of file Password.php.

Referenced by MediaWiki\Password\Password\__construct().

◆ $factory

PasswordFactory MediaWiki\Password\Password::$factory
protected

Factory that created the object.

Definition at line 70 of file Password.php.

Referenced by MediaWiki\Password\Password\__construct().

◆ $hash

string null MediaWiki\Password\Password::$hash
protected

String representation of the hash without the type.

Definition at line 76 of file Password.php.

Referenced by MediaWiki\Password\Password\__construct().


The documentation for this class was generated from the following file: