Skip to content

Framework to automatically tune password hashing functions.

License

Notifications You must be signed in to change notification settings

elchris/hashtuner

Repository files navigation

hashtuner

Framework to automatically suggest settings for password hashing functions, starting with Argon2id. This library was inspired by Bryan Burman's article.

It requires php 8.0 or greater.

It can be used:

  • as an executable from the command line, which outputs a JSON payload containing target settings
  • integrated in any PHP system thru Object-Oriented API

Maintainability Test Coverage CircleCI

What it does

Various algorithms give us different "levers" to control the cost of computing a hash.

Argon2id

With a minimum of 3 iterations, it strives to dominate the cost of password hashing with memory, up to a specified hard memory limit, to achieve an execution time within a given range.

Once it achieves 75% of the upper execution time limit, or the hard memory limit has been reached, it stops augmenting the memory then tries to get even closer to the upper execution time limit by augmenting iterations.

For the time-being, "threads" are locked-down to 1, because the libsodium integration with password_hash won't accept a value other than 1. - Insert link to article explaining this behavior here -

Hard Memory Limit

  • Estimate a server's available memory for concurrent password-hashing processes, say 8GB
  • Estimate a worst-case scenario for concurrent users logging-in at a given time, say 50.
  • Divide the two: 8GB / 50 = 160MB
  • Hard Memory Limit should be set to 160000 aka 160,000KB

Quickest Usage with Phar File

Usage with Defaults

php ./hashtuner.phar
  • Assumes your hard memory limit is the value of "mem_limit" in php.ini
    • in most instances, this is way too high.
  • Assumes a desired execution time between 0.5 and 1.0 seconds

Usage with Custom Hard Memory Limit

php ./hashtuner.phar 128000
  • Sets your hard memory limit to roughly 128 Megabytes
  • Assumes a desired execution time between 0.5 and 1.0 seconds

Usage with Custom Hard Memory Limit and Desired Execution Time

php ./hashtuner.phar 128000 0.8 1.3
  • Sets your hard memory limit to roughly 128 Megabytes
  • Sets your desired execution time between 0.8 and 1.3 seconds

Usage in a Project: Composer

Installation

composer require chrisholland/hashtuner

API

(new ArgonTuner())->getTunedSettings()->toJson()
(new ArgonTuner())->getTunedSettingsForMemoryLimit(128000)->toJson()
(new ArgonTuner())->getTunedSettingsForSpeedAndMemoryLimit(
0.5,
1.0,
128000
)->toJson()

More Reading

Symfony

Other Links

Coding Practices & Contributions

Contributions are welcome and gratefuly appreciated. Please ensure that every commit includes a new test signaling intent, or a fix to an existing test to correct erroneous or missing assumptions.

Standards

Driving Code, with Tests

Aside from src/index.php, 100% of this code was driven by tests, which is how I achieved "100% coverage". Having said this, I don't test-drive code to achieve any "code coverage" percentage, I only do it to more quickly understand what I'm trying to deliver, more easily arrive at a solution, and in the end deliver better software, faster than I would without doing any testing whatsoever. A high "code coverage" percentage just happens to be a mere byproduct of this process.

Generate hashtuner.phar with box-project

About

Framework to automatically tune password hashing functions.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages