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