init

Author: brenno-duarte

.gitignore

@@ -0,0 +1,2 @@
+vendor/
+composer.lock

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,130 @@
+# PHP SecurePassword
+
+SecurePassword is a PHP component for creating strong passwords using modern encryption.
+
+## 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.
+
+## Requirements
+
+PHP >= 7.3 
+
+## How to use
+
+The code below shows an example for creating the hash. Simply use the `createHash` method by entering your password.
+
+```php
+use SecurePassword\SecurePassword;
+
+$password = new SecurePassword();
+$hash = $password->createHash('my_hash');
+
+var_dump($hash);
+```
+
+## Changing the encryption algorithm
+
+You can change the type of algorithm used to generate the hash. It is possible to use `PASSWORD_BCRYPT`,` PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID` and even `PASSWORD_DEFAULT`.
+
+`useDefault()` will use standard encryption
+`useBcrypt()` will use Bcrypt encryption
+`useArgon2()` will use Argon2 encryption
+`useArgon2(null)` passing `true` will use Argon2d encryption 
+
+```php
+# standard encryption
+$hash = $password->useDefault()->createHash('my_hash');
+
+# Bcrypt encryption
+$hash = $password->useBcrypt()->createHash('my_hash');
+
+# Argon2 encryption
+$hash = $password->useArgon2()->createHash('my_hash');
+
+# Argon2d encryption (with `true`)
+$hash = $password->useArgon2(true)->createHash('my_hash');
+```
+
+## Returns information about the given hash
+
+To return the information of the created hash, use `$info` as `true`.
+
+```php
+$hash = $password->createHash('my_hash', true);
+
+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.
+
+```php
+$hash = $password->createHash('my_hash');
+$res = $password->verifyHash('my_hash', $hash);
+
+var_dump($res);
+```
+
+You can change the type of algorithm that will be used to check the hash.
+
+```php
+$hash = $password->useArgon2()->createHash('my_hash');
+$res = $password->useArgon2()->verifyHash('my_hash', $hash);
+
+/** Return bool */
+var_dump($res);
+```
+
+If the encryption type has been changed, you can generate a new hash with the new encryption. Use `true` for the last parameter.
+
+```php
+$hash = $password->useArgon2()->createHash('my_hash');
+$res = $password->useArgon2()->verifyHash('my_hash', $hash, true);
+
+/** Return string|new hash */
+var_dump($res);
+```
+
+## Adding options
+
+Add options in the `useDefault`, `useBcrypt` and `useArgon2` methods.
+
+- useDefault: default options, use an array.
+- useBcrypt: you can change `$cost`. The default is `10`.
+- 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_hash');
+
+# Bcrypt encryption
+$hash = $password->useBcrypt(10)->createHash('my_hash');
+
+# Argon2 encryption
+$hash = $password->useArgon2(false, PASSWORD_ARGON2_DEFAULT_MEMORY_COST, PASSWORD_ARGON2_DEFAULT_TIME_COST, PASSWORD_ARGON2_DEFAULT_THREADS)->createHash('my_hash');
+
+# Argon2d encryption (with `true`)
+$hash = $password->useArgon2(true, PASSWORD_ARGON2_DEFAULT_MEMORY_COST, PASSWORD_ARGON2_DEFAULT_TIME_COST, PASSWORD_ARGON2_DEFAULT_THREADS)->createHash('my_hash');
+```
+
+## Changing the secret entry (recommended)
+
+It is recommended to change the secret entry (or pepper) that will be added to your password. Use `setPepper` to change.
+
+```php
+$password = new SecurePassword();
+$password->setPepper('new_pepper');
+```
+
+## Getting the ideal encryption cost
+
+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();
+
+var_dump($cost);
+```

composer.json

@@ -0,0 +1,17 @@
+{
+    "name": "brenno-duarte/php-secure-password",
+    "description": "SecurePassword is a PHP component for creating strong passwords using modern encryption.",
+    "keywords": [
+        "php-security",
+        "php",
+        "php-password"
+    ],
+    "require": {
+        "php": "^7.3|8.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "SecurePassword\\": "src/"
+        }
+    }
+}

src/HashAlgorithm.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace SecurePassword;
+
+abstract class HashAlgorithm
+{
+    protected const DEFAULT = PASSWORD_DEFAULT;
+    protected const BCRYPT  = PASSWORD_BCRYPT;
+    protected const ARGON2I = PASSWORD_ARGON2I;
+    protected const ARGON2ID = PASSWORD_ARGON2ID;
+
+    /**
+     * @var const
+     */
+    protected $algo;
+
+    /**
+     * @var array
+     */
+    protected array $options = [];
+
+    /**
+     * @return SecurePassword
+     */
+    public function useDefault(array $options = []): SecurePassword
+    {
+        $this->options = $options;
+        $this->algo = self::DEFAULT;
+
+        return $this;
+    }
+
+    /**
+     * @param int $cost
+     * 
+     * @return SecurePassword
+     */
+    public function useBcrypt(int $cost = 10): SecurePassword
+    {
+        $this->options['cost'] = $cost;
+        $this->algo = self::BCRYPT;
+
+        return $this;
+    }
+
+    /**
+     * @param bool $argon2d
+     * @param int $memory_cost
+     * @param int $time_cost
+     * @param int $threads
+     * 
+     * @return SecurePassword
+     */
+    public function useArgon2(
+        bool $use_argon2d = false,
+        int $memory_cost = PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
+        int $time_cost = PASSWORD_ARGON2_DEFAULT_TIME_COST,
+        int $threads = PASSWORD_ARGON2_DEFAULT_THREADS
+    ): SecurePassword {
+        $this->options = [
+            'memory_cost' => $memory_cost,
+            'time_cost' => $time_cost,
+            'threads' => $threads
+        ];
+
+        if ($use_argon2d == true) {
+            $this->algo = self::ARGON2ID;
+        } else {
+            $this->algo = self::ARGON2I;
+        }
+
+        return $this;
+    }
+}

src/HashException.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace SecurePassword;
+
+class HashException extends \Exception
+{
+    
+}