Merge pull request #8 from activecollab/feature/password-handling

Port password handling from Active Collab application

Author: ilijastuden

README.md

@@ -9,3 +9,90 @@ Authentication library builds on top of `activecollab/user` package. There are t
 1. Users with accounts - People with actual accounts in our application.
 
 Only users with accounts in our application can be authenticated.
+
+## Working with Passwords
+
+### Hashing and Validating Passwords
+
+Passwords can be hashed using one of the three mechanisms:
+
+1. PHP's built in `password_*` functions. This is default and recommended method
+1. Using PBKDF2
+1. Using SHA1
+
+Later two are there for compatibility reasons only, so you can transition your hashed passwords to PHP's password management system if you have not done that already. Password manager's `needsRehash()` method will always recommend rehashing for PBKDF2 and SHA1 hashed passwords.
+
+Example:
+
+```php
+$manager = new PasswordManager('global salt, if needed');
+
+$hash = $manager->hash('easy to remember, hard to guess');
+
+if ($manager->verify('easy to remember, hard to guess', $hash, PasswordManagerInterface::HASHED_WITH_PHP)) {
+    print "All good\n";
+} else {
+    print "Not good\n";
+}
+```
+
+Library offers a way to check if password needs to be rehashed, usually after you successfully checked if password that user provided is correct one:
+
+```php
+$manager = new PasswordManager('global salt, if needed');
+
+if ($manager->verify($user_provided_password, $hash_from_storage, PasswordManagerInterface::HASHED_WITH_PHP)) {
+    if ($manager->needsRehash($hash_from_storage, PasswordManagerInterface::HASHED_WITH_PHP)) {
+        // Update hash in our data storage
+    }
+    
+    // Proceed with user authentication
+} else {
+    print "Invalid password\n";
+}
+```
+
+### Password Policy
+
+All passwords are validated against password policies. By default, policy will accept any non-empty string:
+
+```php
+(new PasswordStrengthValidator())->isPasswordValid('weak', new PasswordPolicy()); // Will return TRUE
+```
+
+Policy can enforce following rules:
+
+1. Password is longer than N characters
+1. Password contains at least one number
+1. Password contains mixed case (uppercase and lowercase) letters
+1. Password contains at least one of the following symbols: `,.;:!$\%^&~@#*`
+
+Here's an example where all rules are enforced:
+
+```php
+// Weak password, not accepted
+(new PasswordStrengthValidator())->isPasswordValid('weak', new PasswordPolicy(32, true, true, true));
+ 
+// Strong password, accepted
+(new PasswordStrengthValidator())->isPasswordValid('BhkXuemYY#WMdU;QQd4QpXpcEjbw2XHP', new PasswordPolicy(32, true, true, true));
+```
+
+### Generating Random Passwords
+
+Password strength validator can also be used to prepare new passwords that meed the requirements of provided policies:
+
+```php
+$validator = new PasswordStrengthValidator();
+$policy = new PasswordPolicy(32, true, true, true);
+
+// Prepare 32 characters long password that mixes case, numbers and symbols
+$password = $validator->generateValidPassword(32, $policy); 
+```
+
+Password generator uses letters and numbers by default, unless symbols are required by the provided password policy.
+
+Note that generator may throw an exeception if it fails to prepare a password in 10000 tries.
+
+## To Do
+
+1. Consider adding previously used passwords repository, so library can enforce no-repeat policy for passwords

composer.json

@@ -16,10 +16,12 @@
     ],
     "require": {
         "php": ">=5.6.0",
+        "ext-mbstring": "*",
         "activecollab/user": "^3.0",
         "activecollab/cookies": "~0.1",
-        "guzzlehttp/psr7": "~1.2",
-        "google/apiclient": "^1.1"
+        "guzzlehttp/psr7": "^1.2",
+        "google/apiclient": "^1.1",
+        "ircmaxell/random-lib" : "^1.2"
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^1.0",

composer.lock

@@ -16,8 +16,8 @@ interface AuthorizerInterface
     /**
      * Perform user credentials verification against the real user database provider.
      *
-     * @param  array                           $credentials
-     * @return AuthenticatedUserInterface|null
+     * @param  array                                                                          $credentials
+     * @return \ActiveCollab\Authentication\AuthenticatedUser\AuthenticatedUserInterface|null
      */
     public function verifyCredentials(array $credentials);
 

src/Authorizer/AuthorizerInterface.php

@@ -0,0 +1,114 @@
+<?php
+
+/*
+ * This file is part of the Active Collab Authentication project.
+ *
+ * (c) A51 doo <[email protected]>. All rights reserved.
+ */
+
+namespace ActiveCollab\Authentication\Password\Manager;
+
+use InvalidArgumentException;
+
+/**
+ * @package ActiveCollab\Authentication\Password
+ */
+class PasswordManager implements PasswordManagerInterface
+{
+    /**
+     * @var string
+     */
+    private $global_salt;
+
+    /**
+     * @param string $global_salt
+     */
+    public function __construct($global_salt = '')
+    {
+        $this->global_salt = (string) $global_salt;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function verify($password, $hash, $hashed_with)
+    {
+        switch ($hashed_with) {
+            case self::HASHED_WITH_PHP:
+                return password_verify($this->global_salt . $password, $hash);
+            case self::HASHED_WITH_PBKDF2:
+            case self::HASHED_WITH_SHA1:
+                return $this->hash($password, $hashed_with) === $hash;
+            default:
+                throw new InvalidArgumentException("Hashing mechanism '$hashed_with' is not supported");
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function hash($password, $hash_with = self::HASHED_WITH_PHP)
+    {
+        switch ($hash_with) {
+            case self::HASHED_WITH_PHP:
+                return password_hash($this->global_salt . $password, PASSWORD_DEFAULT);
+            case self::HASHED_WITH_PBKDF2:
+                return base64_encode($this->pbkdf2($password, $this->global_salt, 1000, 40));
+            case self::HASHED_WITH_SHA1:
+                return sha1($this->global_salt . $password);
+            default:
+                throw new InvalidArgumentException("Hashing mechanism '$hash_with' is not supported");
+        }
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function needsRehash($hash, $hashed_with)
+    {
+        if ($hashed_with === self::HASHED_WITH_PHP) {
+            return password_needs_rehash($hash, PASSWORD_DEFAULT);
+        } else {
+            return true;
+        }
+    }
+
+    /**
+     * PBKDF2 Implementation (described in RFC 2898).
+     *
+     * Source: http://www.itnewb.com/tutorial/Encrypting-Passwords-with-PHP-for-Storage-Using-the-RSA-PBKDF2-Standard
+     *
+     * @param  string $p  password
+     * @param  string $s  salt
+     * @param  int    $c  iteration count (use 1000 or higher)
+     * @param  int    $kl derived key length
+     * @param  string $a  hash algorithm
+     * @return string derived key
+     */
+    private function pbkdf2($p, $s, $c, $kl, $a = 'sha256')
+    {
+        $hl = strlen(hash($a, null, true)); # Hash length
+        $kb = ceil($kl / $hl);              # Key blocks to compute
+        $dk = '';                           # Derived key
+
+        # Create key
+        for ($block = 1; $block <= $kb; ++$block) {
+
+            # Initial hash for this block
+            $ib = $b = hash_hmac($a, $s . pack('N', $block), $p, true);
+
+            # Perform block iterations
+            for ($i = 1; $i < $c; ++$i) {
+                # XOR each iterate
+
+                $ib ^= ($b = hash_hmac($a, $b, $p, true));
+            }
+
+            $dk .= $ib; # Append iterated block
+        }
+
+        # Return derived key of correct length
+
+        return substr($dk, 0, $kl);
+    }
+}