Added AlgorithmEnum and deprecated constants in HashAlgorithm

Author: brenno-duarte

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Released Notes
 
+## v3.1.3 - (2024-08-25)
+
+### Added
+
+- Added `AlgorithmEnum` enum
+
+### Changed
+
+- Changed default cost for bcrypt to 12
+- Changed constants in `HashAlgorithm` to deprecated
+
+-----------------------------------------------------------
+
 ## v3.1.2 - (2024-03-11)
 
 ### Fixed

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Brenno Duarte de Lima
+Copyright (c) 2024 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

@@ -4,7 +4,7 @@ SecurePassword is a PHP component for creating strong passwords using modern enc
 
 ## Why use this component?
 
-Unlike just using `password_hash`, SecurePassword adds a secret entry (commonly called a pepper) to make it difficult to break the generated hash.
+Unlike just using `password_hash` or `password_verify`, SecurePassword adds a secret entry (commonly called a pepper) to make it difficult to break the generated hash.
 
 ## Requirements
 
@@ -35,11 +35,11 @@ var_dump($hash);
 You can change encryption settings without using the methods that will be listed below. To do this, enter the following code in the constructor:
 
 ```php
-use SecurePassword\HashAlgorithm;
+use SecurePassword\AlgorithmEnum;
 
 $config = [
-    'algo' => HashAlgorithm::DEFAULT,
-    'cost' => 10,
+    'algo' => AlgorithmEnum::DEFAULT,
+    'cost' => 12,
     'memory_cost' => PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
     'time_cost' => PASSWORD_ARGON2_DEFAULT_TIME_COST,
     'threads' => PASSWORD_ARGON2_DEFAULT_THREADS
@@ -134,25 +134,24 @@ 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`.
 
+**Example 1**
+
 ```php
-/**
- * EXAMPLE 1
- */
 $password = new SecurePassword();
 $hash = $password->useArgon2()->createHash('my_password')->getHash();
 $needs = $password->useDefault()->needsRehash('my_password', $hash);
 
 /** Return string */
 var_dump($needs);
+```
 
-/**
- * EXAMPLE 2
- */
+**Example 2**
 
+```php
 $hash = $password->createHash('my_password')->getHash();
 
 $password = new SecurePassword([
-    'algo' => HashAlgorithm::BCRYPT
+    'algo' => AlgorithmEnum::BCRYPT
 ]);
 $needs = $password->needsRehash('my_password', $hash);
 
@@ -167,15 +166,15 @@ var_dump($needs);
 Add options in the `useDefault`, `useBcrypt` and `useArgon2` methods.
 
 - useDefault: default options, use an array.
-- useBcrypt: you can change `$cost`. The default is `10`.
+- useBcrypt: you can change `$cost`. The default is `12`.
 - useArgon2: you can change `$memory_cost`, `$time_cost` and `$threads`. The default is the constants `PASSWORD_ARGON2_DEFAULT_MEMORY_COST`, `PASSWORD_ARGON2_DEFAULT_TIME_COST` and `PASSWORD_ARGON2_DEFAULT_THREADS`.
 
 ```php
 # standard encryption
 $hash = $password->useDefault([])->createHash('my_password');
 
 # Bcrypt encryption
-$hash = $password->useBcrypt(10)->createHash('my_password');
+$hash = $password->useBcrypt(12)->createHash('my_password');
 
 # Argon2 encryption
 $hash = $password->useArgon2(false, PASSWORD_ARGON2_DEFAULT_MEMORY_COST, PASSWORD_ARGON2_DEFAULT_TIME_COST, PASSWORD_ARGON2_DEFAULT_THREADS)->createHash('my_password');
@@ -197,7 +196,6 @@ $encryption = new Encryption('your-key');
 
 //Encrypt the message
 $encrypt = $encryption->encrypt("This is a text");
-
 echo $encrypt;
 ```
 
@@ -208,17 +206,19 @@ $encryption = new Encryption('your-key');
 
 //Decrypt the message
 $decrypt = $encryption->decrypt($encrypt);
-
 echo $decrypt;
 ```
 
 You can pass supported adapter to class like:
 
-Use of OpenSSL
+**Use of OpenSSL**
+
 ```php 
 $encryption = new Encryption(new OpenSslEncryption('your-key'));
 ```
-Use of Sodium
+
+**Use of Sodium**
+
 ```php 
 $encryption = new Encryption(new SodiumEncryption('your-key'));
 ```

composer.json

@@ -18,5 +18,8 @@
         "psr-4": {
             "SecurePassword\\": "src/"
         }
+    },
+    "suggest": {
+        "ext-libsodium": "To use Sodium encryption"
     }
 }

phpunit.xml

@@ -1,8 +1,18 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="vendor/autoload.php" colors="true" stopOnFailure="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.4/phpunit.xsd" cacheDirectory=".phpunit.cache">
+<phpunit 
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        bootstrap="vendor/autoload.php"
+        colors="true"
+        stopOnFailure="false"
+        xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.0/phpunit.xsd"
+        cacheDirectory=".phpunit.cache"
+        displayDetailsOnTestsThatTriggerDeprecations="true"
+        displayDetailsOnTestsThatTriggerErrors="true"
+        displayDetailsOnTestsThatTriggerNotices="true"
+        displayDetailsOnTestsThatTriggerWarnings="true">
   <testsuites>
-    <testsuite name="Password Test Suite">
+    <testsuite name="Password test suite">
       <directory>tests</directory>
     </testsuite>
   </testsuites>
-</phpunit>
+</phpunit>

src/AlgorithmEnum.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace SecurePassword;
+
+enum AlgorithmEnum: string
+{
+    case DEFAULT = "default";
+    case BCRYPT  = PASSWORD_BCRYPT;
+    case ARGON2I = PASSWORD_ARGON2I;
+    case ARGON2ID = PASSWORD_ARGON2ID;
+}

src/Encrypt/Adapter/OpenSslEncryption.php

@@ -34,10 +34,7 @@ class OpenSslEncryption implements AbstractAdapterInterface
      */
     public function __construct(string $key)
     {
-        if ($key === '') {
-            throw new \InvalidArgumentException('The key should not be empty string.');
-        }
-        
+        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);
     }
@@ -47,25 +44,26 @@ public function __construct(string $key)
      *
      * @param mixed $data => data to be encrypted
      *
-     * @return token
+     * @return mixed
      */
     public function encrypt(mixed $data): mixed
     {
-        return base64_encode(openssl_encrypt($data, $this->cipher, $this->key, 0, $this->iv).'&&'.bin2hex($this->iv));
+        return base64_encode(
+            openssl_encrypt($data, $this->cipher, $this->key, 0, $this->iv) . '&&' . bin2hex($this->iv)
+        );
     }
 
     /**
      * Decrypt the message.
      *
      * @param mixed $token => encrypted token
 
-     * @return mix-data
+     * @return string|bool
      */
-    public function decrypt(mixed $token): mixed
+    public function decrypt(mixed $token): string|bool
     {
         $token = base64_decode($token);
         list($token, $this->iv) = explode('&&', $token);
-
         return openssl_decrypt($token, $this->cipher, $this->key, 0, hex2bin($this->iv));
     }
 

src/Encrypt/Adapter/SodiumEncryption.php

@@ -18,13 +18,10 @@ class SodiumEncryption implements AbstractAdapterInterface
      */
     public function __construct(string $key)
     {
-        if ($key === '') {
-            throw new \InvalidArgumentException('The key should not be empty string.');
-        }
-        
-        if (!function_exists('sodium_crypto_secretbox_keygen')) {
+        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);
-        }
 
         //should use user define key.
         $this->key = substr(hash('sha512', $key), 0, 32);
@@ -40,8 +37,7 @@ public function __construct(string $key)
     public function encrypt(mixed $data): mixed
     {
         $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
-        $token = base64_encode($nonce.sodium_crypto_secretbox($data, $nonce, $this->key).'&&'.$this->key);
-
+        $token = base64_encode($nonce . sodium_crypto_secretbox($data, $nonce, $this->key) . '&&' . $this->key);
         return $token;
     }
 
@@ -56,25 +52,18 @@ public function decrypt(mixed $token): mixed
     {
         $decoded = base64_decode($token);
         list($decoded, $this->key) = explode('&&', $decoded);
-        
-        if ($decoded === false) {
-            throw new \Exception('The decoding failed');
-        }
+        if ($decoded === false) throw new \Exception('The decoding failed');
 
-        if (mb_strlen($decoded, '8bit') < (SODIUM_CRYPTO_SECRETBOX_NONCEBYTES + SODIUM_CRYPTO_SECRETBOX_MACBYTES)) {
+        if (
+            mb_strlen($decoded, '8bit') < (SODIUM_CRYPTO_SECRETBOX_NONCEBYTES + SODIUM_CRYPTO_SECRETBOX_MACBYTES)
+        ) {
             throw new \Exception('The token was truncated');
         }
 
         $nonce = mb_substr($decoded, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, '8bit');
         $ciphertext = mb_substr($decoded, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, null, '8bit');
-
-        $plain = sodium_crypto_secretbox_open($ciphertext,
-        $nonce, $this->key);
-
-        if ($plain === false) {
-            throw new \Exception('The message was tampered with in transit');
-        }
-
+        $plain = sodium_crypto_secretbox_open($ciphertext, $nonce, $this->key);
+        if ($plain === false) throw new \Exception('The message was tampered with in transit');
         return $plain;
     }
 }

src/HashAlgorithm.php

@@ -4,9 +4,28 @@
 
 abstract class HashAlgorithm
 {
+    /**
+     * @deprecated Use `AlgorithmEnum` enum
+     * @var mixed
+     */
     const DEFAULT = PASSWORD_DEFAULT;
+
+    /**
+     * @deprecated Use `AlgorithmEnum` enum
+     * @var mixed
+     */
     const BCRYPT  = PASSWORD_BCRYPT;
+
+    /**
+     * @deprecated Use `AlgorithmEnum` enum
+     * @var mixed
+     */
     const ARGON2I = PASSWORD_ARGON2I;
+
+    /**
+     * @deprecated Use `AlgorithmEnum` enum
+     * @var mixed
+     */
     const ARGON2ID = PASSWORD_ARGON2ID;
 
     /**
@@ -27,8 +46,7 @@ abstract class HashAlgorithm
     public function useDefault(array $options = []): SecurePassword
     {
         $this->options = $options;
-        $this->algo = self::DEFAULT;
-
+        $this->algo = PASSWORD_DEFAULT;
         return $this;
     }
 
@@ -37,11 +55,10 @@ public function useDefault(array $options = []): SecurePassword
      * 
      * @return SecurePassword
      */
-    public function useBcrypt(int $cost = 10): SecurePassword
+    public function useBcrypt(int $cost = 12): SecurePassword
     {
         $this->options['cost'] = $cost;
-        $this->algo = self::BCRYPT;
-
+        $this->algo = AlgorithmEnum::BCRYPT->value;
         return $this;
     }
 
@@ -65,12 +82,8 @@ public function useArgon2(
             'threads' => $threads
         ];
 
-        $this->algo = self::ARGON2I;
-
-        if ($use_argon2d == true) {
-            $this->algo = self::ARGON2ID;
-        }
-
+        $this->algo = AlgorithmEnum::ARGON2I->value;
+        if ($use_argon2d == true) $this->algo = AlgorithmEnum::ARGON2ID->value;
         return $this;
     }
 }

src/PepperTrait.php

@@ -43,15 +43,11 @@ public function setPepper(string $pepper = "default_hash", string $crypt_type =
     public function getPepper(): string
     {
         if ($this->pepper !== '') {
-            if ($this->crypt_type == 'openssl') {
-                $encryption = new Encryption(new OpenSslEncryption($this->pepper));
-                $this->pepper = $encryption->decrypt($this->pepper);
-            }
+            if ($this->crypt_type == 'openssl') $adapter = new OpenSslEncryption($this->pepper);
+            if ($this->crypt_type == 'sodium') $adapter = new SodiumEncryption($this->pepper);
 
-            if ($this->crypt_type == 'sodium') {
-                $encryption = new Encryption(new SodiumEncryption($this->pepper));
-                $this->pepper = $encryption->decrypt($this->pepper);
-            }
+            $encryption = new Encryption($adapter);
+            $this->pepper = $encryption->decrypt($this->pepper);
         }
 
         return $this->pepper;