- Oops, I forgot to add this file to CVS when I committed the secure password hashing patch last night. Mea culpa.

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));
+}
+