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
23 use Wikimedia\Assert\Assert
;
26 * Represents a password hash for use in authentication
28 * Note: All password types are transparently prefixed with :<TYPE>:, where <TYPE>
29 * is the registered type of the hash. This prefix is stripped in the constructor
30 * and is added back in the toString() function.
32 * When inheriting this class, there are a couple of expectations
34 * * If Password::toString() is called on an object, and the result is passed back in
35 * to PasswordFactory::newFromCiphertext(), the result will be identical to the original.
36 * * The string representations of two Password objects are equal only if
37 * the original plaintext passwords match. In other words, if the toString() result of
38 * two objects match, the passwords are the same, and the user will be logged in.
39 * Since the string representation of a hash includes its type name (@see Password::toString),
40 * this property is preserved across all classes that inherit Password.
41 * If a hashing scheme does not fulfill this expectation, it must make sure to override the
42 * Password::equals() function and use custom comparison logic. However, this is not
43 * recommended unless absolutely required by the hashing mechanism.
44 * With these two points in mind, when creating a new Password sub-class, there are some functions
45 * you have to override (because they are abstract) and others that you may want to override.
47 * The abstract functions that must be overridden are:
48 * * Password::crypt(), which takes a plaintext password and hashes it into a string hash suitable
49 * for being passed to the constructor of that class, and then stores that hash (and whatever
50 * other data) into the internal state of the object.
51 * The functions that can optionally be overridden are:
52 * * Password::parseHash(), which can be useful to override if you need to extract values from or
53 * otherwise parse a password hash when it's passed to the constructor.
54 * * Password::needsUpdate(), which can be useful if a specific password hash has different
55 * logic for when the hash needs to be updated.
56 * * Password::toString(), which can be useful if the hash was changed in the constructor and
57 * needs to be re-assembled before being returned as a string. This function is expected to add
58 * the type back on to the hash, so make sure to do that if you override the function.
59 * * Password::equals() - This function compares two Password objects to see if they are equal.
60 * The default is to just do a timing-safe string comparison on the $this->hash values.
62 * After creating a new password hash type, it can be registered using the static
63 * Password::register() method. The default type is set using the Password::setDefaultType() type.
64 * Types must be registered before they can be set as the default.
68 abstract class Password
{
70 * @var PasswordFactory Factory that created the object
75 * String representation of the hash without the type
81 * Array of configuration variables injected from the constructor
87 * Hash must fit in user_password, which is a tinyblob
89 const MAX_HASH_SIZE
= 255;
92 * Construct the Password object using a string hash
94 * It is strongly recommended not to call this function directly unless you
95 * have a reason to. Use the PasswordFactory class instead.
97 * @throws MWException If $config does not contain required parameters
99 * @param PasswordFactory $factory Factory object that created the password
100 * @param array $config Array of engine configuration options for hashing
101 * @param string|null $hash The raw hash, including the type
103 final public function __construct( PasswordFactory
$factory, array $config, $hash = null ) {
104 if ( !$this->isSupported() ) {
105 throw new Exception( 'PHP support not found for ' . get_class( $this ) );
107 if ( !isset( $config['type'] ) ) {
108 throw new Exception( 'Password configuration must contain a type name.' );
110 $this->config
= $config;
111 $this->factory
= $factory;
113 if ( $hash !== null && strlen( $hash ) >= 3 ) {
114 // Strip the type from the hash for parsing
115 $hash = substr( $hash, strpos( $hash, ':', 1 ) +
1 );
119 $this->parseHash( $hash );
123 * Get the type name of the password
125 * @return string Password type
127 final public function getType() {
128 return $this->config
['type'];
132 * Whether current password type is supported on this system.
136 protected function isSupported() {
141 * Perform any parsing necessary on the hash to see if the hash is valid
142 * and/or to perform logic for seeing if the hash needs updating.
144 * @param string $hash The hash, with the :<TYPE>: prefix stripped
145 * @throws PasswordError If there is an error in parsing the hash
147 protected function parseHash( $hash ) {
151 * Determine if the hash needs to be updated
153 * @return bool True if needs update, false otherwise
155 abstract public function needsUpdate();
158 * Compare one Password object to this object
160 * By default, do a timing-safe string comparison on the result of
161 * Password::toString() for each object. This can be overridden to do
162 * custom comparison, but it is not recommended unless necessary.
164 * @deprecated since 1.33, use verify()
166 * @param Password|string $other The other password
167 * @return bool True if equal, false otherwise
169 public function equals( $other ) {
170 if ( is_string( $other ) ) {
171 return $this->verify( $other );
174 return hash_equals( $this->toString(), $other->toString() );
178 * Checks whether the given password matches the hash stored in this object.
180 * @param string $password Password to check
183 public function verify( $password ) {
184 Assert
::parameterType( 'string', $password, '$password' );
186 // No need to use the factory because we're definitely making
187 // an object of the same type.
189 $obj->crypt( $password );
191 return hash_equals( $this->toString(), $obj->toString() );
195 * Convert this hash to a string that can be stored in the database
197 * The resulting string should be considered the seralized representation
198 * of this hash, i.e., if the return value were recycled back into
199 * PasswordFactory::newFromCiphertext, the returned object would be equivalent to
200 * this; also, if two objects return the same value from this function, they
201 * are considered equivalent.
204 * @throws PasswordError if password cannot be serialized to fit a tinyblob.
206 public function toString() {
207 $result = ':' . $this->config
['type'] . ':' . $this->hash
;
208 $this->assertIsSafeSize( $result );
213 * Assert that hash will fit in a tinyblob field.
215 * This prevents MW from inserting it into the DB
216 * and having MySQL silently truncating it, locking
217 * the user out of their account.
219 * @param string $hash The hash in question.
220 * @throws PasswordError If hash does not fit in DB.
222 final protected function assertIsSafeSize( $hash ) {
223 if ( strlen( $hash ) > self
::MAX_HASH_SIZE
) {
224 throw new PasswordError( "Password hash is too big" );
229 * Hash a password and store the result in this object
231 * The result of the password hash should be put into the internal
232 * state of the hash object.
234 * @param string $password Password to hash
235 * @throws PasswordError If an internal error occurs in hashing
237 abstract public function crypt( $password );