diff options
Diffstat (limited to 'includes')
| -rw-r--r-- | includes/password.inc | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/includes/password.inc b/includes/password.inc new file mode 100644 index 000000000..143410c73 --- /dev/null +++ b/includes/password.inc @@ -0,0 +1,239 @@ +<?php +// $Id$ + +/** + * @file + * Secure password hashing functions for user authentication. + * + * Based on the Portable PHP password hashing framework. + * @see http://www.openwall.com/phpass/ + * + * An alternative or custom version of this password hashing API may be + * used by setting the variable password_inc to the name of the PHP file + * containing replacement user_hash_password(), user_check_password(), and + * user_needs_new_hash() functions. + */ + +/** + * The standard log2 number of iterations for password stretching. This should + * increase by 1 at least every other Drupal version in order to counteract + * increases in the speed and power of computers available to crack the hashes. + */ +define('DRUPAL_HASH_COUNT', 14); + +/** + * The min and max allowed log2 number of iterations for password stretching. + */ +define('DRUPAL_MIN_HASH_COUNT', 7); +define('DRUPAL_MAX_HASH_COUNT', 30); + +/** + * Returns a string for mapping an int to the corresponding base 64 character. + */ +function _password_itoa64() { + return './0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'; +} + +/** + * Encode bytes into printable base 64 using the *nix standard from crypt(). + * + * @param $input + * The string containing bytes to encode. + * @param $count + * The number of characters (bytes) to encode. + * + * @return + * Encoded string + */ +function _password_base64_encode($input, $count) { + $output = ''; + $i = 0; + $itoa64 = _password_itoa64(); + do { + $value = ord($input[$i++]); + $output .= $itoa64[$value & 0x3f]; + if ($i < $count) { + $value |= ord($input[$i]) << 8; + } + $output .= $itoa64[($value >> 6) & 0x3f]; + if ($i++ >= $count) { + break; + } + if ($i < $count) { + $value |= ord($input[$i]) << 16; + } + $output .= $itoa64[($value >> 12) & 0x3f]; + if ($i++ >= $count) { + break; + } + $output .= $itoa64[($value >> 18) & 0x3f]; + } while ($i < $count); + + return $output; +} + +/** + * Generates a random base 64-encoded salt prefixed with settings for the hash. + * + * Proper use of salts may defeat a number of attacks, including: + * - The ability to try candidate passwords against multiple hashes at once. + * - The ability to use pre-hashed lists of candidate passwords. + * - The ability to determine whether two users have the same (or different) + * password without actually having to guess one of the passwords. + * + * @param $count_log2 + * Integer that determines the number of iterations used in the hashing + * process. A larger value is more secure, but takes more time to complete. + * + * @return + * A 12 character string containing the iteration count and a random salt. + */ +function _password_generate_salt($count_log2) { + $output = '$P$'; + // Minimum log2 iterations is DRUPAL_MIN_HASH_COUNT. + $count_log2 = max($count_log2, DRUPAL_MIN_HASH_COUNT); + // Maximum log2 iterations is DRUPAL_MAX_HASH_COUNT. + // We encode the final log2 iteration count in base 64. + $itoa64 = _password_itoa64(); + $output .= $itoa64[min($count_log2, DRUPAL_MAX_HASH_COUNT)]; + // 6 bytes is the standard salt for a portable phpass hash. + $output .= _password_base64_encode(drupal_random_bytes(6), 6); + return $output; +} + +/** + * Hash a password using a secure stretched hash. + * + * By using a salt and repeated hashing the password is "stretched". Its + * security is increased because it becomes much more computationally costly + * for an attacker to try to break the hash by brute-force computation of the + * hashes of a large number of plain-text words or strings to find a match. + * + * @param $password + * The plain-text password to hash. + * @param $setting + * An existing hash or the output of _password_generate_salt(). + * + * @return + * A string containing the hashed password (and salt) or FALSE on failure. + */ +function _password_crypt($password, $setting) { + // The first 12 characters of an existing hash are its setting string. + $setting = substr($setting, 0, 12); + + if (substr($setting, 0, 3) != '$P$') { + return FALSE; + } + $count_log2 = _password_get_count_log2($setting); + // Hashes may be imported from elsewhere, so we allow != DRUPAL_HASH_COUNT + if ($count_log2 < DRUPAL_MIN_HASH_COUNT || $count_log2 > DRUPAL_MAX_HASH_COUNT) { + return FALSE; + } + $salt = substr($setting, 4, 8); + // Hashes must have an 8 character salt. + if (strlen($salt) != 8) { + return FALSE; + } + + // We must use md5() or sha1() here since they are the only cryptographic + // primitives always available in PHP 5. To implement our own low-level + // cryptographic function in PHP would result in much worse performance and + // consequently in lower iteration counts and hashes that are quicker to crack + // (by non-PHP code). + + $count = 1 << $count_log2; + + $hash = md5($salt . $password, TRUE); + do { + $hash = md5($hash . $password, TRUE); + } while (--$count); + + $output = $setting . _password_base64_encode($hash, 16); + // _password_base64_encode() of a 16 byte MD5 will always be 22 characters. + return (strlen($output) == 34) ? $output : FALSE; +} + +/** + * Parse the log2 iteration count from a stored hash or setting string. + */ +function _password_get_count_log2($setting) { + $itoa64 = _password_itoa64(); + return strpos($itoa64, $setting[3]); +} + +/** + * Hash a password using a secure hash. + * + * @param $password + * A plain-text password. + * @param $count_log2 + * Optional integer to specify the iteration count. Generally used only during + * mass operations where a value less than the default is needed for speed. + * + * @return + * A string containing the hashed password (and a salt), or FALSE on failure. + */ +function user_hash_password($password, $count_log2 = 0) { + if (empty($count_log2)) { + // Use the standard iteration count. + $count_log2 = variable_get('password_count_log2', DRUPAL_HASH_COUNT); + } + return _password_crypt($password, _password_generate_salt($count_log2)); +} + +/** + * Check whether a plain text password matches a stored hashed password. + * + * Alternative implementations of this function may use other data in the + * $account object, for example the uid to look up the hash in a custom table + * or remote database. + * + * @param $password + * A plain-text password + * @param $account + * A user object with at least the fields from the {users} table. + * + * @return + * TRUE or FALSE. + */ +function user_check_password($password, $account) { + if (substr($account->pass, 0, 3) == 'U$P') { + // This may be an updated password from user_update_7000(). Such hashes + // have 'U' added as the first character and need an extra md5(). + $stored_hash = substr($account->pass, 1); + $password = md5($password); + } + else { + $stored_hash = $account->pass; + } + $hash = _password_crypt($password, $stored_hash); + return ($hash && $stored_hash == $hash); +} + +/** + * Check whether a user's hashed password needs to be replaced with a new hash. + * + * This is typically called during the login process when the plain text + * password is available. A new hash is needed when the desired iteration count + * has changed through a change in the variable password_count_log2 or + * DRUPAL_HASH_COUNT or if the user's password hash was generated in an update + * like user_update_7000(). + * + * Alternative implementations of this function might use other criteria based + * on the fields in $account. + * + * @param $account + * A user object with at least the fields from the {users} table. + * + * @return + * TRUE or FALSE. + */ +function user_needs_new_hash($account) { + // Check whether this was an updated password. + if ((substr($account->pass, 0, 3) != '$P$') || (strlen($account->pass) != 34)) { + return TRUE; + } + // Check whether the iteration count used differs from the standard number. + return (_password_get_count_log2($account->pass) != variable_get('password_count_log2', DRUPAL_HASH_COUNT)); +} + |