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