Represents a password hash for use in authentication. More...
Public Member Functions | |
| __construct (PasswordFactory $factory, array $config, $hash=null) | |
| Construct the Password object using a string hash. More... | |
| crypt ($password) | |
| Hash a password and store the result in this object. More... | |
| equals ($other) | |
| Compare one Password object to this object. More... | |
| getType () | |
| Get the type name of the password. More... | |
| needsUpdate () | |
| Determine if the hash needs to be updated. More... | |
| toString () | |
| Convert this hash to a string that can be stored in the database. More... | |
Protected Member Functions | |
| parseHash ($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. More... | |
Protected Attributes | |
| array | $config |
| Array of configuration variables injected from the constructor. More... | |
| PasswordFactory | $factory |
| Factory that created the object. More... | |
| string | $hash |
| String representation of the hash without the type. More... | |
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.
- The string representations of two Password objects are equal only if the original plaintext passwords match. In other words, if the toString() result of two objects match, the passwords are the same, and the user will be logged in. Since the string representation of a hash includes its type name (
- See also
- Password::toString), this property is preserved across all classes that inherit Password. If a hashing scheme does not fulfill this expectation, it must make sure to override the Password::equals() function and use custom comparison logic. However, this is not recommended unless absolutely required by the hashing mechanism. 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.
- 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::equals() - This function compares two Password objects to see if they are equal. The default is to just do a timing-safe string comparison on the $this->hash values.
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
|
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.
- Exceptions
-
MWException If $config does not contain required parameters
- Parameters
-
PasswordFactory $factory Factory object that created the password array $config Array of engine configuration options for hashing string | null $hash The raw hash, including the type
Definition at line 96 of file Password.php.
References $config, $factory, $hash, and parseHash().
Member Function Documentation
|
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 $password Password to hash
- Exceptions
-
PasswordError If an internal error occurs in hashing
Referenced by LayeredParameterizedPassword\partialCrypt().
| Password::equals | ( | $other | ) |
Compare one Password object to this object.
By default, do a timing-safe string comparison on the result of Password::toString() for each object. This can be overridden to do custom comparison, but it is not recommended unless necessary.
- Parameters
-
Password | string $other The other password
- Returns
- bool True if equal, false otherwise
Definition at line 149 of file Password.php.
References toString().
|
final |
Get the type name of the password.
- Returns
- string Password type
Definition at line 117 of file Password.php.
Referenced by PasswordFactory\needsUpdate().
| Password::needsUpdate | ( | ) |
Determine if the hash needs to be updated.
- Returns
- bool True if needs update, false otherwise
Definition at line 136 of file Password.php.
Referenced by PasswordFactory\needsUpdate().
|
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 $hash The hash, with the :<TYPE>: prefix stripped
- Exceptions
-
PasswordError If there is an error in parsing the hash
Definition at line 128 of file Password.php.
Referenced by __construct().
| Password::toString | ( | ) |
Convert this hash to a string that can be stored in the database.
The resulting string should be considered the seralized 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
Definition at line 172 of file Password.php.
References $hash.
Referenced by equals().
Member Data Documentation
|
protected |
Array of configuration variables injected from the constructor.
Definition at line 82 of file Password.php.
Referenced by __construct().
|
protected |
Factory that created the object.
Definition at line 70 of file Password.php.
Referenced by __construct().
|
protected |
String representation of the hash without the type.
Definition at line 76 of file Password.php.
Referenced by __construct(), Pbkdf2Password\crypt(), BcryptPassword\crypt(), LayeredParameterizedPassword\crypt(), BcryptPassword\parseHash(), ParameterizedPassword\parseHash(), LayeredParameterizedPassword\partialCrypt(), ParameterizedPassword\toString(), and toString().
The documentation for this class was generated from the following file:
- includes/password/Password.php
