paragonie/argon2-refiner

Calculate the appropriate Argon2id parameters for the local hardware environment.

v0.3.0 2021-04-19 03:00 UTC

Requires

• php: >=7.3

Requires (Dev)

• phpunit/phpunit: ^8|^9
• vimeo/psalm: ^3|^4

ISC

• Paragon Initiative Enterprises

README

Easily and effectively benchmark the real time to perform Argon2id password hashes on your machine.

Warning: This might take many seconds or minutes to complete.

Installation Instructions

Use Composer.

composer require paragonie/argon2-refiner

Alternatively, you can install this with Git.

git clone https://github.com/paragonie/argon2-refiner
cd argon2-refiner
composer install

Usage Instructions

Command Line

Run the bundled benchmark script like so:

# Installed via Composer:
vendor/bin/benchmark [milliseconds=500] [tolerance=250]

# Installed via Git:
composer run-benchmarks [milliseconds=500] [tolerance=250]

The expected output will look something like this:

$ vendor/bin/benchmark 125
 Recommended Argon2id parameters:
 	       Memory cost (sodium): 79691776
 	Memory cost (password_hash): 77824
 	                  Time cost: 3
 
 Real time: 124ms

This means that if you set your Argon2id mem_cost to 79691776 bytes (or 77824 KiB, which is what password_hash() expects) and the time_cost to 3, you will get the closest parameters that take about 125 milliseconds to process (in this example, it took 124).

Object-Oriented API

You can fine-tune your min/max costs to search within from the object by invoking the appropriate methods.

<?php
use ParagonIE\Argon2Refiner\ParameterRecommender;

$refiner = (new ParameterRecommender(125))
    ->setMinMemory(1 << 20)
    ->setMaxMemory(1 << 31)
    ->setMinTime(2)
    ->setMaxTime(4)
    ->setTolerance(25);

$results = $refiner->runBenchmarks();

The runBenchmarks() method returns a two-dimensional array of arrays. Each child array consists of the following data:

• mem_cost (int) -- Candidate parameter
• time_cost (int) -- Candidate parameter
• bench_time (int) -- Milliseconds elapsed in Argon2id calculation

From this data, you can devise your own strategy for selecting which parameters set is most suitable for your environment.