Argon2i Hasher

Purpose and Scope

This page documents the ArgonHasher class, which implements the Argon2i password hashing algorithm within the Hypervel hashing library. The ArgonHasher class provides a wrapper around PHP's native PASSWORD_ARGON2I algorithm with configurable memory, time, and thread parameters, as well as optional algorithm verification.

For information about the alternative Bcrypt algorithm, see Bcrypt Hasher. For the Argon2id variant that extends this implementation, see Argon2id Hasher. For general architecture and how this hasher is instantiated, see Hash Manager.

Class Structure and Inheritance

The ArgonHasher class is located at src/ArgonHasher.php1-161 and follows the standard hasher implementation pattern used throughout the library. It extends AbstractHasher to inherit common functionality and implements the HasherContract interface to ensure API compliance.

Sources: src/ArgonHasher.php10

Configuration Properties

The ArgonHasher class maintains four primary configuration properties that control hashing behavior:

Property	Type	Default Value	Description
memory	int	1024	Memory cost factor in kilobytes
time	int	2	Time cost factor (iterations)
threads	int	2	Number of parallel threads (modified for sodium)
verifyAlgorithm	bool	false	Whether to enforce algorithm verification during check()

These properties are defined at src/ArgonHasher.php15-30 and can be set during construction or via setter methods.

Constructor Configuration

The constructor accepts an options array that allows overriding default values:

Sources: src/ArgonHasher.php35-41

Algorithm Implementation

The ArgonHasher uses PHP's PASSWORD_ARGON2I constant, which corresponds to the Argon2i variant of the Argon2 algorithm. The algorithm selection is encapsulated in the protected algorithm() method:

src/ArgonHasher.php66-69

This method returns PASSWORD_ARGON2I, differentiating this implementation from the Argon2id variant which uses PASSWORD_ARGON2ID.

Hash Creation (make Method)

The make() method creates a hashed representation of the input value using the configured Argon2i parameters:

The implementation at src/ArgonHasher.php48-61 uses the @ error suppression operator when calling password_hash() and validates that the result is a string. If hashing fails (returns false), it throws a RuntimeException indicating that Argon2 hashing is not supported on the current PHP installation.

Sources: src/ArgonHasher.php48-61

Parameter Extraction Methods

Three protected methods extract configuration parameters, applying a cascade of precedence: runtime options → instance properties:

memory() Method

src/ArgonHasher.php136-139

Returns $options['memory'] if present, otherwise falls back to $this->memory.

time() Method

src/ArgonHasher.php144-147

Returns $options['time'] if present, otherwise falls back to $this->time.

threads() Method

src/ArgonHasher.php152-159

This method has special logic for the sodium cryptography provider:

When PHP's Argon2 implementation is provided by the sodium extension, the threads parameter is forced to 1 regardless of configuration. This is because libsodium's Argon2 implementation does not support multithreading.

Sources: src/ArgonHasher.php136-159

Algorithm Verification (check Method)

The check() method verifies a plain value against a hashed value, with optional algorithm enforcement:

src/ArgonHasher.php76-83

When verifyAlgorithm is enabled, the method performs an additional check before delegating to the parent implementation:

Verification Step	Condition	Action
1. Algorithm check	verifyAlgorithm === true	Call info($hashedValue)['algoName']
2. Name comparison	algoName !== 'argon2i'	Throw RuntimeException
3. Parent verification	Algorithm matches or verification disabled	Call parent::check()

This feature protects against verifying passwords that were hashed with a different algorithm, preventing potential security issues from mixed algorithm usage.

Sources: src/ArgonHasher.php76-83

Rehash Detection (needsRehash Method)

The needsRehash() method determines whether an existing hash should be regenerated due to changed configuration parameters:

src/ArgonHasher.php88-95

This method delegates to PHP's password_needs_rehash() function, passing the current algorithm and all three cost parameters:

PHP's underlying function compares the hash's embedded parameters against the provided parameters. If any parameter has changed, it returns true, signaling that the hash should be regenerated with the new settings.

Sources: src/ArgonHasher.php88-95

Configuration Setter Methods

The class provides three fluent setter methods that allow runtime modification of cost parameters:

setMemory() Method

src/ArgonHasher.php102-107

Sets the memory property and returns $this for method chaining.

setTime() Method

src/ArgonHasher.php114-119

Sets the time property and returns $this for method chaining.

setThreads() Method

src/ArgonHasher.php126-131

Sets the threads property and returns $this for method chaining.

All three methods follow the same fluent interface pattern, enabling usage like:

$hasher->setMemory(2048)->setTime(3)->setThreads(4);

Sources: src/ArgonHasher.php102-131

Integration with Hash Manager

The ArgonHasher is instantiated by the HashManager through its factory method. The creation flow ties configuration to driver instantiation:

The manager passes configuration options from the application's hashing.php file directly to the ArgonHasher constructor, establishing the instance's default behavior.

Sources: src/ArgonHasher.php35-41

Relationship to Argon2IdHasher

The ArgonHasher class serves as the parent class for Argon2IdHasher. The inheritance relationship means that Argon2IdHasher inherits all configuration logic, parameter extraction methods, and the special sodium provider handling:

The only difference between the two classes is the algorithm constant returned by their respective algorithm() methods. This design eliminates code duplication while allowing each variant to maintain its distinct cryptographic characteristics.

For detailed information about the Argon2id variant, see Argon2id Hasher.

Sources: src/ArgonHasher.php66-69

Error Handling

The class includes error handling for platform compatibility issues:

Error Condition	Location	Exception Type	Message
password_hash() returns false	src/ArgonHasher.php56-58	RuntimeException	"Argon2 hashing not supported."
Algorithm mismatch during verification	src/ArgonHasher.php78-80	RuntimeException	"This password does not use the Argon2i algorithm."

The first error typically occurs when PHP is compiled without Argon2 support. The second occurs only when verifyAlgorithm is enabled and a hash from a different algorithm is checked.

Sources: src/ArgonHasher.php56-80

Summary Table: Method Overview

Method	Visibility	Return Type	Purpose
__construct()	public	void	Initialize with configuration options
make()	public	string	Create hash with current parameters
check()	public	bool	Verify value with optional algorithm enforcement
needsRehash()	public	bool	Check if hash needs regeneration
setMemory()	public	static	Set memory cost factor
setTime()	public	static	Set time cost factor
setThreads()	public	static	Set thread count
algorithm()	protected	int	Return PASSWORD_ARGON2I
memory()	protected	int	Extract memory from options or use default
time()	protected	int	Extract time from options or use default
threads()	protected	int	Extract threads with sodium provider logic

Sources: src/ArgonHasher.php1-161