gabrielfrdev/secure-passhash

Secure CLI password hashing with Argon2id - Production-ready tool with strict security validation

v1.0.1 2025-12-23 13:06 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Gabriel Ferreira

README

PassHash is a secure, developer-focused CLI tool and library for generating and verifying password hashes. It enforces modern security standards (Argon2id) with strict validation.

🔒 Security Features

• Argon2id Standard: Enforces Argon2id with a minimum of 64 MiB memory cost.
• Secure Input: Prevents password leakage in shell history by refusing CLI arguments.
• DoS Protection: Validates input length (Max 4 KiB) and computational costs (Max Threads/Memory).
• Zero Dependencies: Lightweight, PHP >= 8.1 only.

🚀 Installation

Global (Quick Use)

composer global require gabrielfrdev/secure-passhash

Local (Development)

git clone https://github.com/gabrielfrdev/secure-passhash.git
cd secure-passhash
composer install

🚀 Executable Location

Dependendo de como você instalou, o executável estará em um lugar diferente:

• Instalação Global: passhash
• Instalação Local (Composer): vendor/bin/passhash
• Pelo Código Fonte: ./bin/passhash

Nos exemplos abaixo, usaremos ./bin/passhash, substitua pelo comando correspondente ao seu modo de instalação.

🛠 Usage

1. Generating a Hash

PassHash uses secure prompts or pipes. Passwords are never accepted as arguments.

Interactive Mode (Recommended):

./bin/passhash hash
# You will be prompted securely to enter the password.

Automation (Pipe):

echo "my_super_secret_password" | ./bin/passhash hash

Output:

✔ Hash generated securely.

Algorithm: Argon2id
Hash:
$argon2id$v=19$m=65536,t=4,p=1$XyZ...

2. Verifying a Hash

To verify, provide the hash. You will be prompted for the password.

./bin/passhash verify '$argon2id$v=19$m=65536,t=4,p=1$...'
# Prompt: Enter password to verify:

3. Inspect Configuration

Check the current security parameters used by the machine.

./bin/passhash config

🛡 Security considerations

1. Shell History: We explicitly block passhash hash <password> to prevent your password from being saved in .bash_history or system logs (ps aux).
2. Memory Defaults: We default to 64 MiB memory cost. OWASP recommends ~19 MiB, but 64 MiB is chosen for higher resistance against GPU cracking on modern servers.
3. Windows Users: On Windows CMD/PowerShell, secure input masking might not work (input visible). Use with caution or in a private environment.

🧪 Development & Testing

Run the security test suite:

composer test
# or
vendor/bin/phpunit

License

MIT