Lithe Hash is a robust module designed for securely hashing passwords using the Bcrypt algorithm. This module simplifies the process of creating, verifying, and managing password hashes, ensuring that security best practices are followed.

Table of Contents

1. Installation
2. Usage
   • Importing the Class
   • Creating a Hash
   • Verifying a Hash
   • Checking if a Hash Needs Rehashing
   • Understanding Bcrypt
   • Handling Exceptions
3. Testing
4. License

Installation

To install the lithemod/hash package, you can use Composer. Run the following command in your terminal:

composer require lithemod/hash

This will add the package to your project's dependencies, allowing you to use the Hash class in your application.

Usage

Importing the Class

Before using the Hash class, you must import it in your PHP file:

use Lithe\Support\Security\Hash;

Creating a Hash

To create a hash from a password, use the make method. The method accepts a password and an optional array of options:

$hash = Hash::make('your_password', ['cost' => 10]);

Parameters:

• string $value: The password to be hashed.
• array $options: Optional parameters (e.g., cost) to adjust the hashing algorithm.

Returns: A hashed string that can be stored in a database.

Example:

$password = 'my_secure_password';
$hash = Hash::make($password, ['cost' => 12]);
echo "Hashed Password: " . $hash;

Verifying a Hash

To check if a given password matches the hash, use the check method:

$isValid = Hash::check('your_password', $hash);
if ($isValid) {
    echo 'Password is valid!';
} else {
    echo 'Invalid password.';
}

Parameters:

• string $value: The password to verify.
• string $hash: The hashed password to compare against.

Returns: true if the password matches the hash; false otherwise.

Example:

if (Hash::check('my_secure_password', $hash)) {
    echo 'Password is correct!';
} else {
    echo 'Password is incorrect!';
}

Checking if a Hash Needs Rehashing

You can determine if a hash needs to be rehashed (for example, if you change the cost factor) using the needsRehash method:

$needsRehash = Hash::needsRehash($hash, ['cost' => 14]);
if ($needsRehash) {
    // Rehash with a new cost
    $hash = Hash::make('your_password', ['cost' => 14]);
}

Parameters:

• string $hash: The hashed password to evaluate.
• array $options: Optional parameters to specify the cost.

Returns: true if the hash needs to be rehashed; false otherwise.

Example:

if (Hash::needsRehash($hash, ['cost' => 15])) {
    $hash = Hash::make('my_secure_password', ['cost' => 15]);
    echo "Rehashed Password: " . $hash;
}

Understanding Bcrypt

Bcrypt is a widely-used password hashing function designed to be slow and computationally intensive, making it resistant to brute-force attacks. By using a configurable cost factor, Bcrypt allows you to increase the difficulty of hashing as hardware becomes faster.

• Cost Factor: The cost factor determines the computational complexity of hashing a password. It represents the number of iterations of the hashing algorithm. A higher cost means more security but also increases processing time. The recommended range is between 10 and 12 for most applications.

Handling Exceptions

The make method throws an InvalidArgumentException if the cost is set outside the valid range (4 to 31). You should handle this in your code to ensure robustness:

try {
    $hash = Hash::make('your_password', ['cost' => 3]); // Invalid cost
} catch (\InvalidArgumentException $e) {
    echo "Error: " . $e->getMessage();
}

With Lithe Hash, you can manage passwords securely and efficiently while following security best practices. If you have any questions or suggestions, feel free to comment!