1
|
<?php
|
2
|
|
3
|
/**
|
4
|
* @file
|
5
|
* Secure password hashing functions for user authentication.
|
6
|
*
|
7
|
* Based on the Portable PHP password hashing framework.
|
8
|
* @see http://www.openwall.com/phpass/
|
9
|
*
|
10
|
* An alternative or custom version of this password hashing API may be
|
11
|
* used by setting the variable password_inc to the name of the PHP file
|
12
|
* containing replacement user_hash_password(), user_check_password(), and
|
13
|
* user_needs_new_hash() functions.
|
14
|
*/
|
15
|
|
16
|
/**
|
17
|
* The standard log2 number of iterations for password stretching. This should
|
18
|
* increase by 1 every Drupal version in order to counteract increases in the
|
19
|
* speed and power of computers available to crack the hashes.
|
20
|
*/
|
21
|
define('DRUPAL_HASH_COUNT', 15);
|
22
|
|
23
|
/**
|
24
|
* The minimum allowed log2 number of iterations for password stretching.
|
25
|
*/
|
26
|
define('DRUPAL_MIN_HASH_COUNT', 7);
|
27
|
|
28
|
/**
|
29
|
* The maximum allowed log2 number of iterations for password stretching.
|
30
|
*/
|
31
|
define('DRUPAL_MAX_HASH_COUNT', 30);
|
32
|
|
33
|
/**
|
34
|
* The expected (and maximum) number of characters in a hashed password.
|
35
|
*/
|
36
|
define('DRUPAL_HASH_LENGTH', 55);
|
37
|
|
38
|
/**
|
39
|
* Returns a string for mapping an int to the corresponding base 64 character.
|
40
|
*/
|
41
|
function _password_itoa64() {
|
42
|
return './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
|
43
|
}
|
44
|
|
45
|
/**
|
46
|
* Encodes bytes into printable base 64 using the *nix standard from crypt().
|
47
|
*
|
48
|
* @param $input
|
49
|
* The string containing bytes to encode.
|
50
|
* @param $count
|
51
|
* The number of characters (bytes) to encode.
|
52
|
*
|
53
|
* @return
|
54
|
* Encoded string
|
55
|
*/
|
56
|
function _password_base64_encode($input, $count) {
|
57
|
$output = '';
|
58
|
$i = 0;
|
59
|
$itoa64 = _password_itoa64();
|
60
|
do {
|
61
|
$value = ord($input[$i++]);
|
62
|
$output .= $itoa64[$value & 0x3f];
|
63
|
if ($i < $count) {
|
64
|
$value |= ord($input[$i]) << 8;
|
65
|
}
|
66
|
$output .= $itoa64[($value >> 6) & 0x3f];
|
67
|
if ($i++ >= $count) {
|
68
|
break;
|
69
|
}
|
70
|
if ($i < $count) {
|
71
|
$value |= ord($input[$i]) << 16;
|
72
|
}
|
73
|
$output .= $itoa64[($value >> 12) & 0x3f];
|
74
|
if ($i++ >= $count) {
|
75
|
break;
|
76
|
}
|
77
|
$output .= $itoa64[($value >> 18) & 0x3f];
|
78
|
} while ($i < $count);
|
79
|
|
80
|
return $output;
|
81
|
}
|
82
|
|
83
|
/**
|
84
|
* Generates a random base 64-encoded salt prefixed with settings for the hash.
|
85
|
*
|
86
|
* Proper use of salts may defeat a number of attacks, including:
|
87
|
* - The ability to try candidate passwords against multiple hashes at once.
|
88
|
* - The ability to use pre-hashed lists of candidate passwords.
|
89
|
* - The ability to determine whether two users have the same (or different)
|
90
|
* password without actually having to guess one of the passwords.
|
91
|
*
|
92
|
* @param $count_log2
|
93
|
* Integer that determines the number of iterations used in the hashing
|
94
|
* process. A larger value is more secure, but takes more time to complete.
|
95
|
*
|
96
|
* @return
|
97
|
* A 12 character string containing the iteration count and a random salt.
|
98
|
*/
|
99
|
function _password_generate_salt($count_log2) {
|
100
|
$output = '$S$';
|
101
|
// Ensure that $count_log2 is within set bounds.
|
102
|
$count_log2 = _password_enforce_log2_boundaries($count_log2);
|
103
|
// We encode the final log2 iteration count in base 64.
|
104
|
$itoa64 = _password_itoa64();
|
105
|
$output .= $itoa64[$count_log2];
|
106
|
// 6 bytes is the standard salt for a portable phpass hash.
|
107
|
$output .= _password_base64_encode(drupal_random_bytes(6), 6);
|
108
|
return $output;
|
109
|
}
|
110
|
|
111
|
/**
|
112
|
* Ensures that $count_log2 is within set bounds.
|
113
|
*
|
114
|
* @param $count_log2
|
115
|
* Integer that determines the number of iterations used in the hashing
|
116
|
* process. A larger value is more secure, but takes more time to complete.
|
117
|
*
|
118
|
* @return
|
119
|
* Integer within set bounds that is closest to $count_log2.
|
120
|
*/
|
121
|
function _password_enforce_log2_boundaries($count_log2) {
|
122
|
if ($count_log2 < DRUPAL_MIN_HASH_COUNT) {
|
123
|
return DRUPAL_MIN_HASH_COUNT;
|
124
|
}
|
125
|
elseif ($count_log2 > DRUPAL_MAX_HASH_COUNT) {
|
126
|
return DRUPAL_MAX_HASH_COUNT;
|
127
|
}
|
128
|
|
129
|
return (int) $count_log2;
|
130
|
}
|
131
|
|
132
|
/**
|
133
|
* Hash a password using a secure stretched hash.
|
134
|
*
|
135
|
* By using a salt and repeated hashing the password is "stretched". Its
|
136
|
* security is increased because it becomes much more computationally costly
|
137
|
* for an attacker to try to break the hash by brute-force computation of the
|
138
|
* hashes of a large number of plain-text words or strings to find a match.
|
139
|
*
|
140
|
* @param $algo
|
141
|
* The string name of a hashing algorithm usable by hash(), like 'sha256'.
|
142
|
* @param $password
|
143
|
* The plain-text password to hash.
|
144
|
* @param $setting
|
145
|
* An existing hash or the output of _password_generate_salt(). Must be
|
146
|
* at least 12 characters (the settings and salt).
|
147
|
*
|
148
|
* @return
|
149
|
* A string containing the hashed password (and salt) or FALSE on failure.
|
150
|
* The return string will be truncated at DRUPAL_HASH_LENGTH characters max.
|
151
|
*/
|
152
|
function _password_crypt($algo, $password, $setting) {
|
153
|
// The first 12 characters of an existing hash are its setting string.
|
154
|
$setting = substr($setting, 0, 12);
|
155
|
|
156
|
if ($setting[0] != '$' || $setting[2] != '$') {
|
157
|
return FALSE;
|
158
|
}
|
159
|
$count_log2 = _password_get_count_log2($setting);
|
160
|
// Hashes may be imported from elsewhere, so we allow != DRUPAL_HASH_COUNT
|
161
|
if ($count_log2 < DRUPAL_MIN_HASH_COUNT || $count_log2 > DRUPAL_MAX_HASH_COUNT) {
|
162
|
return FALSE;
|
163
|
}
|
164
|
$salt = substr($setting, 4, 8);
|
165
|
// Hashes must have an 8 character salt.
|
166
|
if (strlen($salt) != 8) {
|
167
|
return FALSE;
|
168
|
}
|
169
|
|
170
|
// Convert the base 2 logarithm into an integer.
|
171
|
$count = 1 << $count_log2;
|
172
|
|
173
|
// We rely on the hash() function being available in PHP 5.2+.
|
174
|
$hash = hash($algo, $salt . $password, TRUE);
|
175
|
do {
|
176
|
$hash = hash($algo, $hash . $password, TRUE);
|
177
|
} while (--$count);
|
178
|
|
179
|
$len = strlen($hash);
|
180
|
$output = $setting . _password_base64_encode($hash, $len);
|
181
|
// _password_base64_encode() of a 16 byte MD5 will always be 22 characters.
|
182
|
// _password_base64_encode() of a 64 byte sha512 will always be 86 characters.
|
183
|
$expected = 12 + ceil((8 * $len) / 6);
|
184
|
return (strlen($output) == $expected) ? substr($output, 0, DRUPAL_HASH_LENGTH) : FALSE;
|
185
|
}
|
186
|
|
187
|
/**
|
188
|
* Parse the log2 iteration count from a stored hash or setting string.
|
189
|
*/
|
190
|
function _password_get_count_log2($setting) {
|
191
|
$itoa64 = _password_itoa64();
|
192
|
return strpos($itoa64, $setting[3]);
|
193
|
}
|
194
|
|
195
|
/**
|
196
|
* Hash a password using a secure hash.
|
197
|
*
|
198
|
* @param $password
|
199
|
* A plain-text password.
|
200
|
* @param $count_log2
|
201
|
* Optional integer to specify the iteration count. Generally used only during
|
202
|
* mass operations where a value less than the default is needed for speed.
|
203
|
*
|
204
|
* @return
|
205
|
* A string containing the hashed password (and a salt), or FALSE on failure.
|
206
|
*/
|
207
|
function user_hash_password($password, $count_log2 = 0) {
|
208
|
if (empty($count_log2)) {
|
209
|
// Use the standard iteration count.
|
210
|
$count_log2 = variable_get('password_count_log2', DRUPAL_HASH_COUNT);
|
211
|
}
|
212
|
return _password_crypt('sha512', $password, _password_generate_salt($count_log2));
|
213
|
}
|
214
|
|
215
|
/**
|
216
|
* Check whether a plain text password matches a stored hashed password.
|
217
|
*
|
218
|
* Alternative implementations of this function may use other data in the
|
219
|
* $account object, for example the uid to look up the hash in a custom table
|
220
|
* or remote database.
|
221
|
*
|
222
|
* @param $password
|
223
|
* A plain-text password
|
224
|
* @param $account
|
225
|
* A user object with at least the fields from the {users} table.
|
226
|
*
|
227
|
* @return
|
228
|
* TRUE or FALSE.
|
229
|
*/
|
230
|
function user_check_password($password, $account) {
|
231
|
if (substr($account->pass, 0, 2) == 'U$') {
|
232
|
// This may be an updated password from user_update_7000(). Such hashes
|
233
|
// have 'U' added as the first character and need an extra md5().
|
234
|
$stored_hash = substr($account->pass, 1);
|
235
|
$password = md5($password);
|
236
|
}
|
237
|
else {
|
238
|
$stored_hash = $account->pass;
|
239
|
}
|
240
|
|
241
|
$type = substr($stored_hash, 0, 3);
|
242
|
switch ($type) {
|
243
|
case '$S$':
|
244
|
// A normal Drupal 7 password using sha512.
|
245
|
$hash = _password_crypt('sha512', $password, $stored_hash);
|
246
|
break;
|
247
|
case '$H$':
|
248
|
// phpBB3 uses "$H$" for the same thing as "$P$".
|
249
|
case '$P$':
|
250
|
// A phpass password generated using md5. This is an
|
251
|
// imported password or from an earlier Drupal version.
|
252
|
$hash = _password_crypt('md5', $password, $stored_hash);
|
253
|
break;
|
254
|
default:
|
255
|
return FALSE;
|
256
|
}
|
257
|
return ($hash && $stored_hash == $hash);
|
258
|
}
|
259
|
|
260
|
/**
|
261
|
* Check whether a user's hashed password needs to be replaced with a new hash.
|
262
|
*
|
263
|
* This is typically called during the login process when the plain text
|
264
|
* password is available. A new hash is needed when the desired iteration count
|
265
|
* has changed through a change in the variable password_count_log2 or
|
266
|
* DRUPAL_HASH_COUNT or if the user's password hash was generated in an update
|
267
|
* like user_update_7000().
|
268
|
*
|
269
|
* Alternative implementations of this function might use other criteria based
|
270
|
* on the fields in $account.
|
271
|
*
|
272
|
* @param $account
|
273
|
* A user object with at least the fields from the {users} table.
|
274
|
*
|
275
|
* @return
|
276
|
* TRUE or FALSE.
|
277
|
*/
|
278
|
function user_needs_new_hash($account) {
|
279
|
// Check whether this was an updated password.
|
280
|
if ((substr($account->pass, 0, 3) != '$S$') || (strlen($account->pass) != DRUPAL_HASH_LENGTH)) {
|
281
|
return TRUE;
|
282
|
}
|
283
|
// Ensure that $count_log2 is within set bounds.
|
284
|
$count_log2 = _password_enforce_log2_boundaries(variable_get('password_count_log2', DRUPAL_HASH_COUNT));
|
285
|
// Check whether the iteration count used differs from the standard number.
|
286
|
return (_password_get_count_log2($account->pass) !== $count_log2);
|
287
|
}
|