Add password hashing info to README.md

Author: ilijastuden

README.md

@@ -12,6 +12,30 @@ Only users with accounts in our application can be authenticated.
 
 ## Working with Passwords
 
+### Hashing 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 resons 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";
+}
+```
+
 ### Password Policy
 
 All passwords are validated against password policies. By default, policy will accept any non-empty string:

src/Password/Manager/PasswordManager.php

@@ -23,7 +23,7 @@ class PasswordManager implements PasswordManagerInterface
     /**
      * @param string $global_salt
      */
-    public function __construct($global_salt)
+    public function __construct($global_salt = '')
     {
         $this->global_salt = (string) $global_salt;
     }

test/src/PasswordManagerTest.php

@@ -0,0 +1,95 @@
+<?php
+
+/*
+ * This file is part of the Active Collab Authentication project.
+ *
+ * (c) A51 doo <[email protected]>. All rights reserved.
+ */
+
+namespace ActiveCollab\Authentication\Test;
+
+use ActiveCollab\Authentication\Password\Manager\PasswordManager;
+use ActiveCollab\Authentication\Password\Manager\PasswordManagerInterface;
+use ActiveCollab\Authentication\Test\TestCase\TestCase;
+
+/**
+ * @package ActiveCollab\Authentication\Test
+ */
+class PasswordManagerTest extends TestCase
+{
+    /**
+     * @expectedException \InvalidArgumentException
+     * @expectedExceptionMessage Hashing mechanism 'unknown hash algo' is not supported
+     */
+    public function testVerifyExceptionOnInvalidMechanism()
+    {
+        (new PasswordManager())->verify('123', '1234567890', 'unknown hash algo');
+    }
+
+    /**
+     * @expectedException \InvalidArgumentException
+     * @expectedExceptionMessage Hashing mechanism 'unknown hash algo' is not supported
+     */
+    public function testHashExceptionOnInvalidMechanism()
+    {
+        (new PasswordManager())->hash('123', 'unknown hash algo');
+    }
+
+    /**
+     * Test if PHP password hashing works as expected.
+     */
+    public function testPhp()
+    {
+        $manager = new PasswordManager('salt');
+
+        $hash = $manager->hash('123', PasswordManagerInterface::HASHED_WITH_PHP);
+
+        $this->assertInternalType('string', $hash);
+        $this->assertGreaterThan(40, strlen($hash));
+
+        $this->assertTrue($manager->verify('123', $hash, PasswordManagerInterface::HASHED_WITH_PHP));
+    }
+
+    /**
+     * Test if PBKDF2 hashing works as expected.
+     */
+    public function testPbkdf2()
+    {
+        $manager = new PasswordManager('salt');
+
+        $hash = $manager->hash('123', PasswordManagerInterface::HASHED_WITH_PBKDF2);
+
+        $this->assertInternalType('string', $hash);
+        $this->assertGreaterThan(40, strlen($hash));
+        $this->assertStringEndsWith('==', $hash);
+
+        $this->assertTrue($manager->verify('123', $hash, PasswordManagerInterface::HASHED_WITH_PBKDF2));
+    }
+
+    /**
+     * Test if SHA1 hashing works as expected.
+     */
+    public function testSha1()
+    {
+        $manager = new PasswordManager('salt');
+
+        $hash = $manager->hash('123', PasswordManagerInterface::HASHED_WITH_SHA1);
+
+        $this->assertInternalType('string', $hash);
+        $this->assertEquals(40, strlen($hash));
+
+        $this->assertTrue($manager->verify('123', $hash, PasswordManagerInterface::HASHED_WITH_SHA1));
+    }
+
+    /**
+     * Test if PBKDF2 and SHA1 hashed password always recommend rehashing (using PHP password hashing system).
+     */
+    public function testSha1AndPbkdf2NeedRehash()
+    {
+        $manager = new PasswordManager('salt');
+
+        $this->assertFalse($manager->needsRehash($manager->hash('123', PasswordManagerInterface::HASHED_WITH_PHP), PasswordManagerInterface::HASHED_WITH_PHP));
+        $this->assertTrue($manager->needsRehash($manager->hash('123', PasswordManagerInterface::HASHED_WITH_PBKDF2), PasswordManagerInterface::HASHED_WITH_PBKDF2));
+        $this->assertTrue($manager->needsRehash($manager->hash('123', PasswordManagerInterface::HASHED_WITH_SHA1), PasswordManagerInterface::HASHED_WITH_SHA1));
+    }
+}