2.0.0

Author: solital

.gitignore

@@ -1,3 +1,4 @@
 vendor/
 composer.lock
-index.php
+index.php
+.phpunit.result.cache

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Brenno Duarte de Lima
+Copyright (c) 2022 Brenno Duarte de Lima
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -8,7 +8,7 @@ Unlike just using `password_hash`, SecurePassword adds a secret entry (commonly
 
 ## Requirements
 
-PHP >= 7.4
+PHP >= 8.0
 
 ## Installing via Composer
 
@@ -18,13 +18,13 @@ composer require brenno-duarte/php-secure-password
 
 ## How to use
 
-The code below shows an example for creating the hash. Simply use the `createHash` method by entering your password.
+The code below shows an example for creating the hash. The `createHash` method generates the password hash along with the "peeper", and the `getHash` method returns the generated hash.
 
 ```php
 use SecurePassword\SecurePassword;
 
 $password = new SecurePassword();
-$hash = $password->createHash('my_password');
+$hash = $password->createHash('my_password')->getHash();
 
 /** Return string */
 var_dump($hash);
@@ -63,39 +63,43 @@ You can change the type of algorithm used to generate the hash. It is possible t
 
 ```php
 # standard encryption
-$hash = $password->useDefault()->createHash('my_password');
+$hash = $password->useDefault()->createHash('my_password')->getHash();
 
 # Bcrypt encryption
-$hash = $password->useBcrypt()->createHash('my_password');
+$hash = $password->useBcrypt()->createHash('my_password')->getHash();
 
 # Argon2 encryption
-$hash = $password->useArgon2()->createHash('my_password');
+$hash = $password->useArgon2()->createHash('my_password')->getHash();
 
 # Argon2d encryption (with `true`)
-$hash = $password->useArgon2(true)->createHash('my_password');
+$hash = $password->useArgon2(true)->createHash('my_password')->getHash();
 ```
 
 If the type of algorithm is not provided, the default encryption will be 'PASSWORD_DEFAULT'.
 
 ## Returns information about the given hash
 
-To return the information of the created hash, use `$info` as `true`.
+To return the information of the created hash, use `getHashInfo` method.
 
 ```php
-$hash = $password->createHash('my_password', true);
+$hash = $password->createHash('my_password')->getHashInfo();
 
 /** Return array */
 var_dump($hash);
 ```
 
 ## Verifies that a password matches a hash
 
-Checks whether the hash in `$hash` is valid. If the hash entered does not match the options received in the `createHash` method, it is possible to regenerate a new hash in `$verify_needs_rehash`. This function also makes timing attacks difficult.
+To verify that the hash generated with `createHash` is valid, you can use `verifyHash` in two ways:
 
 ```php
-$hash = $password->createHash('my_password');
+# First way
+$hash = $password->createHash('my_password')->getHash();
 $res = $password->verifyHash('my_password', $hash);
 
+# Second way
+$hash = $password->createHash('my_password')->verifyHash();
+
 /** Return bool */
 var_dump($res);
 ```
@@ -105,7 +109,7 @@ var_dump($res);
 You can change the type of algorithm that will be used to check the hash.
 
 ```php
-$hash = $password->useArgon2()->createHash('my_password');
+$hash = $password->useArgon2()->createHash('my_password')->getHash();
 $res = $password->useArgon2()->verifyHash('my_password', $hash);
 
 /** Return bool */
@@ -115,7 +119,7 @@ var_dump($res);
 If the encryption type has been changed, you can generate a new hash with the new encryption. The `needsHash()` method checks whether the reported hash needs to be regenerated. Otherwise, it will return false.
 
 ```php
-$hash = $password->useArgon2()->createHash('my_password');
+$hash = $password->useArgon2()->createHash('my_password')->getHash();
 $needs = $password->useDefault()->needsRehash('my_password', $hash);
 
 /** Return bool or string */

composer.json

@@ -8,7 +8,10 @@
         "php-password"
     ],
     "require": {
-        "php": "^7.3|8.0"
+        "php": ">=8.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.5"
     },
     "autoload": {
         "psr-4": {

phpunit.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<phpunit bootstrap="vendor/autoload.php"
+    colors="true"
+    verbose="true"
+    stopOnFailure="false">
+    <testsuites>
+        <testsuite name="Password Test Suite">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

src/HashAlgorithm.php

@@ -12,14 +12,16 @@ abstract class HashAlgorithm
     /**
      * @var mixed
      */
-    protected $algo;
+    protected mixed $algo;
 
     /**
      * @var array
      */
     protected array $options = [];
 
     /**
+     * @param array $options
+     * 
      * @return SecurePassword
      */
     public function useDefault(array $options = []): SecurePassword

src/HashException.php

@@ -4,4 +4,8 @@
 
 class HashException extends \Exception
 {
+    public function __toString()
+    {
+        return __CLASS__ . ": {$this->message}\n";
+    }
 }

src/SecurePassword.php

@@ -12,6 +12,16 @@ class SecurePassword extends HashAlgorithm
      */
     private string $pepper;
 
+    /**
+     * @var string
+     */
+    private string $pwd_hashed = "";
+
+    /**
+     * @var string
+     */
+    private string $password = "";
+
     /**
      * @var array
      */
@@ -69,39 +79,54 @@ public function getPepper(): string
     }
 
     /**
-     * Creates a password peppered using the entered password and the secret entry. To return the 
-     * information of the created hash, use `$info` as `true`. 
+     * Creates a password peppered using the entered password and the secret entry. 
      * 
      * @param string $password
      * 
-     * @return mixed
+     * @return SecurePassword
      */
-    public function createHash(string $password, bool $info = false)
+    public function createHash(string $password): SecurePassword
     {
-        $pwd_peppered = $this->passwordPeppered($password);
-        $pwd_hashed = password_hash($pwd_peppered, $this->algo, $this->options);
+        $this->password = $password;
 
-        if ($info == true) {
-            return password_get_info($pwd_hashed);
-        }
+        $pwd_peppered = $this->passwordPeppered($this->password);
+        $this->pwd_hashed = password_hash($pwd_peppered, $this->algo, $this->options);
+
+        return $this;
+    }
 
-        return $pwd_hashed;
+    /**
+     * @return string
+     */
+    public function getHash(): string
+    {
+        return $this->pwd_hashed;
     }
 
     /**
-     * Checks whether the hash in `$hash` is valid. If the hash entered does not match the options 
-     * received in the `createHash` method, it is possible to regenerate a new hash in `$verify_needs_rehash`. 
-     * This function also makes timing attacks difficult. 
+     * @return array
+     */
+    public function getHashInfo(): array
+    {
+        return password_get_info($this->pwd_hashed);
+    }
+
+    /**
+     * Verify if the hash generated with `createHash` is valid
      * 
-     * @param string $password
-     * @param string $hash
+     * @param null|string $password
+     * @param null|string $hash
      * 
      * @return mixed
      */
-    public function verifyHash(string $password, $hash)
+    public function verifyHash(?string $password = null, ?string $hash = null): mixed
     {
-        if (is_array($hash)) {
-            throw new HashException("You are returning the hash information. Enter 'false' in the 'createHash' method");
+        if (is_null($password) && $this->password != "") {
+            $password = $this->password;
+        }
+
+        if (is_null($hash) && $this->pwd_hashed != "") {
+            $hash = $this->pwd_hashed;
         }
 
         $pph_strt = microtime(true);
@@ -151,10 +176,10 @@ public function getOptimalBcryptCost(int $min_ms = 250, string $password = "test
      * 
      * @return mixed
      */
-    public function needsRehash(string $password, string $hash)
+    public function needsRehash(string $password, string $hash): mixed
     {
         if (password_needs_rehash($hash, $this->algo)) {
-            $newHash = $this->createHash($password);
+            $newHash = $this->createHash($password)->getHash();
 
             return $newHash;
         } else {
@@ -169,9 +194,7 @@ public function needsRehash(string $password, string $hash)
      */
     private function createPepper(string $pepper): string
     {
-        $hash = openssl_encrypt($pepper, "AES-128-CBC", pack('a16', 'secure_password_1'), 0, pack('a16', 'secure_password_2'));
-
-        return $hash;
+        return openssl_encrypt($pepper, "AES-128-CBC", pack('a16', 'secure_password_1'), 0, pack('a16', 'secure_password_2'));
     }
 
     /**
@@ -183,8 +206,6 @@ private function createPepper(string $pepper): string
      */
     private function passwordPeppered(string $password): string
     {
-        $pwd_peppered = hash_hmac("sha256", $password, $this->getPepper());
-
-        return $pwd_peppered;
+        return hash_hmac("sha256", $password, $this->getPepper());
     }
 }

tests/SecurePasswordTest.php

@@ -0,0 +1,109 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+use SecurePassword\HashAlgorithm;
+use SecurePassword\SecurePassword;
+
+class SecurePasswordTest extends TestCase
+{
+    public function testCreateHash()
+    {
+        $password = new SecurePassword();
+        $hash = $password->createHash('my_password')->getHash();
+
+        $this->assertIsString($hash);
+    }
+
+    public function testChangePepper()
+    {
+        $password = new SecurePassword();
+        $password->setPepper('new_pepper');
+        $hash = $password->createHash('my_password')->getHash();
+
+        $this->assertIsString($hash);
+    }
+
+    public function testChangeHashAlgorithm()
+    {
+        $password = new SecurePassword([
+            'algo' => HashAlgorithm::ARGON2I
+        ]);
+        $hash = $password->createHash('my_password')->getHash();
+
+        $this->assertIsString($hash);
+    }
+
+    public function testCreateWithAlgorithm()
+    {
+        $password = new SecurePassword();
+        $hash = $password->useArgon2()->createHash('my_password')->getHash();
+        $res = $password->useArgon2()->verifyHash('my_password', $hash);
+
+        $this->assertTrue($res);
+    }
+
+    public function testCreateWithOtherAlgorithm()
+    {
+        $password = new SecurePassword();
+        $hash = $password->useArgon2()->createHash('my_password')->getHash();
+        $needs = $password->useDefault()->needsRehash('my_password', $hash);
+
+        $this->assertIsString($needs);
+    }
+
+    public function testHashInfo()
+    {
+        $password = new SecurePassword();
+        $hash = $password->createHash('my_password')->getHashInfo();
+
+        $this->assertIsArray($hash);
+    }
+
+    public function testCreateAndVerifyHashChained()
+    {
+        $password = new SecurePassword();
+        $hash = $password->createHash('my_password')->verifyHash();
+
+        $this->assertTrue($hash);
+    }
+
+    public function testCreateAndVerifyHash()
+    {
+        $password = new SecurePassword();
+        $hash = $password->createHash('my_password')->getHash();
+        $res = $password->verifyHash('my_password', $hash);
+
+        $this->assertTrue($res);
+    }
+
+    public function testVerifyHash()
+    {
+        $hash = '$2y$10$Er0wYRuY7LTYkmWmL8YMMeuxiRIEZ7Vn/8kPb4.aNkzIFRN/N.qG.';
+        $res = (new SecurePassword)->verifyHash('my_password', $hash);
+
+        $this->assertTrue($res);
+    }
+
+    public function testVerifyHashWrong()
+    {
+        $hash = '$2y$10$Er0wYRuY7LTYkmWmL8YMMeuxiRIEZ7Vn/8kPb4.aNkzIFRN/N.qG.';
+        $res = (new SecurePassword)->verifyHash('mypassword', $hash);
+
+        $this->assertFalse($res);
+    }
+
+    public function testVerifyRehash()
+    {
+        $hash = '$2y$10$Er0wYRuY7LTYkmWmL8YMMeuxiRIEZ7Vn/8kPb4.aNkzIFRN/N.qG.';
+        $res = (new SecurePassword)->useArgon2()->needsRehash('mypassword', $hash);
+
+        $this->assertIsString($res);
+    }
+
+    public function testOptimalBcryptCost()
+    {
+        $res = (new SecurePassword)->getOptimalBcryptCost();
+
+        $this->assertIsInt($res);
+    }
+}