added benchmark cost, sodium_compact and fixed options

Author: brenno-duarte

CHANGELOG.md

@@ -1,6 +1,27 @@
 # Released Notes
 
-## v3.0.0 - (2022-11-11)
+## v3.1.0 - (2024-02-xx)
+
+### Added
+
+- Added method to benchmark cost
+- Added microseconds in `usleep`
+- Added set cost using `getOptimalBcryptCost` class
+- Added `password_get_info` in `verifyHash`
+- Added `paragonie/sodium_compat` component
+
+### Fixed
+
+- Fixed usleep in `verifyHash` method
+- Fixed options at `password_hash`
+
+## Removed
+
+- Removed `HashException` class
+
+-----------------------------------------------------------
+
+## v3.0.0 - (2023-11-11)
 
 ### Added
 

README.md

@@ -104,6 +104,20 @@ $hash = $password->createHash('my_password')->verifyHash();
 var_dump($res);
 ```
 
+To make timing attacks more difficult, the `verifyHash` method waits 0.25 seconds (250000 microseconds) to return the value. You can change this time by changing the third parameter.
+
+```php
+# First way
+$hash = $password->createHash('my_password')->getHash();
+$res = $password->verifyHash('my_password', $hash, 300000);
+
+# Second way
+$hash = $password->createHash('my_password')->verifyHash(wait_microseconds: 300000);
+
+/** Return bool */
+var_dump($res);
+```
+
 **NOTE: If you are using the settings passed in the constructor then you can ignore the code below.**
 
 You can change the type of algorithm that will be used to check the hash.
@@ -116,14 +130,34 @@ $res = $password->useArgon2()->verifyHash('my_password', $hash);
 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.
+## Needs Rehash
+
+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
+/**
+ * EXAMPLE 1
+ */
+$password = new SecurePassword();
 $hash = $password->useArgon2()->createHash('my_password')->getHash();
 $needs = $password->useDefault()->needsRehash('my_password', $hash);
 
-/** Return bool or string */
-var_dump($res);
+/** Return string */
+var_dump($needs);
+
+/**
+ * EXAMPLE 2
+ */
+
+$hash = $password->createHash('my_password')->getHash();
+
+$password = new SecurePassword([
+    'algo' => HashAlgorithm::BCRYPT
+]);
+$needs = $password->needsRehash('my_password', $hash);
+
+/** Return false */
+var_dump($needs);
 ```
 
 ## Adding options
@@ -152,6 +186,8 @@ $hash = $password->useArgon2(true, PASSWORD_ARGON2_DEFAULT_MEMORY_COST, PASSWORD
 
 ## Using OpenSSL and Sodium encryption
 
+Secure Password has the component [paragonie/sodium_compat](https://github.com/paragonie/sodium_compat). Therefore, it is not necessary to use the Sodium library in PECL format.
+
 You can use OpenSSL and Sodium encryption using the `Encryption` class:
 
 ```php 
@@ -213,11 +249,12 @@ $password->setPepper('new_pepper', 'sodium');
 Here's a quick little function that will help you determine what cost parameter you should be using for your server to make sure you are within this range.
 
 ```php
-$password = new SecurePassword();
-$cost = $password->getOptimalBcryptCost();
+$optimal_cost = SecurePassword::getOptimalBcryptCost('my_password');
 
-/** Return int */
-var_dump($cost);
+$password = new SecurePassword([
+    'cost' => $optimal_cost
+]);
+$hash = $password->createHash('my_password')->getHash();
 ```
 
 ## License

composer.json

@@ -8,7 +8,8 @@
         "php-password"
     ],
     "require": {
-        "php": "^8.2"
+        "php": "^8.2",
+        "paragonie/sodium_compat": "^1.20"
     },
     "require-dev": {
         "phpunit/phpunit": "^10"

src/Encrypt/Adapter/OpenSslEncryption.php

@@ -37,7 +37,7 @@ public function __construct(string $key)
         if ($key === '') {
             throw new \InvalidArgumentException('The key should not be empty string.');
         }
-
+        
         $this->iv = openssl_random_pseudo_bytes($this->ivBytes($this->cipher));
         $this->key = hash('sha512', $key);
     }

src/Encrypt/Adapter/SodiumEncryption.php

@@ -21,7 +21,7 @@ public function __construct(string $key)
         if ($key === '') {
             throw new \InvalidArgumentException('The key should not be empty string.');
         }
-
+        
         if (!function_exists('sodium_crypto_secretbox_keygen')) {
             throw new \Exception('The sodium php extension does not installed or enabled', 500);
         }

src/Encrypt/Encryption.php

@@ -11,11 +11,7 @@ class Encryption
      */
     public function __construct(
         private AbstractAdapterInterface $adapter
-    )
-    {
-        if ($this->adapter === null) {
-            throw new \InvalidArgumentException('The adapter class should not be null.');
-        }
+    ) {
     }
 
     /**

src/HashAlgorithm.php

@@ -65,10 +65,10 @@ public function useArgon2(
             'threads' => $threads
         ];
 
+        $this->algo = self::ARGON2I;
+
         if ($use_argon2d == true) {
             $this->algo = self::ARGON2ID;
-        } else {
-            $this->algo = self::ARGON2I;
         }
 
         return $this;

src/HashException.php

@@ -2,9 +2,8 @@
 
 namespace SecurePassword;
 
-use SecurePassword\Encrypt\Adapter\OpenSslEncryption;
-use SecurePassword\Encrypt\Adapter\SodiumEncryption;
 use SecurePassword\Encrypt\Encryption;
+use SecurePassword\Encrypt\Adapter\{OpenSslEncryption, SodiumEncryption};
 
 trait PepperTrait
 {
@@ -57,7 +56,6 @@ private function useSodium(): mixed
         return $encryption->encrypt($this->pepper);
     }
 
-
     /**
      * Adds a secret entry (commonly called `pepper`) to the password 
      * 

src/PepperTrait.php

@@ -2,9 +2,10 @@
 
 namespace SecurePassword;
 
-use SecurePassword\PepperTrait;
-use SecurePassword\HashAlgorithm;
-use SecurePassword\HashException;
+use SecurePassword\{
+    PepperTrait,
+    HashAlgorithm
+};
 
 class SecurePassword extends HashAlgorithm
 {
@@ -20,27 +21,25 @@ class SecurePassword extends HashAlgorithm
      */
     private string $password = "";
 
+    /**
+     * @var int|null|null
+     */
+    private ?int $cost_min_ms = null;
+
     /**
      * @param array $config
      */
     public function __construct(
         private array $config = [
             "algo" => HashAlgorithm::DEFAULT,
-            "cost" => "",
+            "cost" => "10",
             "memory_cost" => "",
             "time_cost" => "",
             "threads" => ""
         ]
     ) {
-        foreach ($config as $key => $value) {
-            if (!isset($this->config[$key])) {
-                throw new HashException("Key '$key' not exists");
-            }
-
-            $this->options = $this->config;
-            $this->algo = $this->config['algo'];
-        }
-
+        $this->options = $this->config;
+        $this->algo = $this->config['algo'];
         $this->setPepper();
     }
 
@@ -54,15 +53,15 @@ public function __construct(
     public function createHash(string $password): SecurePassword
     {
         $this->password = $password;
-
         $pwd_peppered = $this->passwordPeppered($this->password);
-
-        $this->pwd_hashed = password_hash($pwd_peppered, $this->algo);
+        $this->pwd_hashed = password_hash($pwd_peppered, $this->algo, $this->options);
 
         return $this;
     }
 
     /**
+     * Return password hash
+     * 
      * @return string
      */
     public function getHash(): string
@@ -71,6 +70,10 @@ public function getHash(): string
     }
 
     /**
+     * Returns information about the given hash
+     * 
+     * @param string|null $hash
+     * 
      * @return mixed
      */
     public function getHashInfo(): mixed
@@ -83,10 +86,11 @@ public function getHashInfo(): mixed
      * 
      * @param null|string $password
      * @param null|string $hash
+     * @param int $wait
      * 
      * @return bool
      */
-    public function verifyHash(?string $password = null, ?string $hash = null): bool
+    public function verifyHash(?string $password = null, ?string $hash = null, int $wait_microseconds = 250000): bool
     {
         if (is_null($password)) {
             $password = $this->password;
@@ -96,33 +100,31 @@ public function verifyHash(?string $password = null, ?string $hash = null): bool
             $hash = $this->pwd_hashed;
         }
 
-        $pph_strt = microtime(true);
-        $pwd_peppered = $this->passwordPeppered($password);
-
-        if (password_verify($pwd_peppered, $hash)) {
-            try {
-                return true;
-            } finally {
-                $end = (microtime(true) - $pph_strt);
-                $wait = bcmul((1 - $end), 1000000);  // usleep(250000) 1/4 of a second
-                usleep($wait);
-            }
+        if (password_get_info($hash)['algoName'] === 'unknown') {
+            return false;
         }
 
-        return false;
+        $pwd_peppered = $this->passwordPeppered($password);
+        $res = password_verify($pwd_peppered, $hash);
+        usleep($wait_microseconds);
+
+        return $res;
     }
 
     /**
      * Here's a quick little function that will help you determine what cost parameter you should be 
      * using for your server to make sure you are within this range.
      * 
-     * @param int $min_ms
      * @param string $password
+     * @param string $crypt
+     * @param int $min_ms
      * 
      * @return int
      */
-    public function getOptimalBcryptCost(int $min_ms = 250, string $password = "test"): int
-    {
+    public static function getOptimalBcryptCost(
+        string $password,
+        int $min_ms = 250
+    ): int {
         for ($i = 4; $i < 31; $i++) {
             $time_start = microtime(true);
             password_hash($password, PASSWORD_BCRYPT, ['cost' => $i]);
@@ -146,11 +148,35 @@ public function getOptimalBcryptCost(int $min_ms = 250, string $password = "test
     public function needsRehash(string $password, string $hash): string|false
     {
         if (password_needs_rehash($hash, $this->algo)) {
-            $newHash = $this->createHash($password)->getHash();
-
-            return $newHash;
+            return $this->createHash($password)->getHash();
         }
 
         return false;
     }
+
+    /**
+     * This code will benchmark your server to determine how high of a cost you can
+     * afford. You want to set the highest cost that you can without slowing down
+     * you server too much. 10 is a good baseline, and more is good if your servers
+     * are fast enough. The code below aims for ≤ 350 milliseconds stretching time,
+     * which is an appropriate delay for systems handling interactive logins.
+     * 
+     * @param string $password
+     * 
+     * @return int
+     */
+    public static function benchmarkCost(string $password): int
+    {
+        $timeTarget = 0.350; // 350 milliseconds
+        $cost = 10;
+
+        do {
+            $cost++;
+            $start = microtime(true);
+            password_hash($password, PASSWORD_BCRYPT, ["cost" => $cost]);
+            $end = microtime(true);
+        } while (($end - $start) < $timeTarget);
+
+        return $cost;
+    }
 }