 |
VOOZH | about |
|
VOOZH | about |
This document describes the Argon2IdHasher implementation, which provides password hashing using the Argon2id algorithm variant. Argon2id combines the security benefits of both Argon2i (data-independent memory access) and Argon2d (data-dependent memory access), making it the recommended Argon2 variant for most use cases.
The Argon2IdHasher class extends ArgonHasher and inherits most of its functionality, changing only the underlying algorithm constant. For detailed information about Argon2i configuration and parameters, see Argon2i Hasher. For general architecture patterns, see Architecture.
Sources: src/Argon2IdHasher.php1-36
The Argon2IdHasher is part of a three-level inheritance chain that provides increasing specialization:
Sources: src/Argon2IdHasher.php9 src/ArgonHasher.php10
The Argon2IdHasher class is minimal by design, containing only 36 lines of code. It leverages inheritance to reuse the entire Argon2 implementation from its parent class, overriding only two methods to change the algorithm variant.
| Aspect | Implementation |
|---|---|
| File Location | src/Argon2IdHasher.php |
| Parent Class | ArgonHasher |
| Algorithm Constant | PASSWORD_ARGON2ID |
| Inherited Properties | $memory, $time, $threads, $verifyAlgorithm |
| Inherited Methods | make(), needsRehash(), setMemory(), setTime(), setThreads() |
| Overridden Methods | check(), algorithm() |
Sources: src/Argon2IdHasher.php1-36
The algorithm() method is the primary differentiator between Argon2IdHasher and ArgonHasher. This protected method returns the PHP password hashing algorithm constant:
The method implementation at src/Argon2IdHasher.php32-35 simply returns PASSWORD_ARGON2ID, which instructs PHP's password_hash() and password_needs_rehash() functions to use the Argon2id variant instead of Argon2i.
Sources: src/Argon2IdHasher.php32-35 src/ArgonHasher.php66-69
The check() method verifies a plain-text password against a hashed value. The Argon2IdHasher implementation at src/Argon2IdHasher.php16-27 differs from its parent in the algorithm verification logic:
Key differences from the parent class:
'argon2id' instead of 'argon2i' at src/Argon2IdHasher.php18password_verify() directly at src/Argon2IdHasher.php26 instead of delegating to parent::check()Sources: src/Argon2IdHasher.php16-27 src/ArgonHasher.php76-83
The Argon2IdHasher inherits all configuration parameters from ArgonHasher without modification. These parameters control the computational cost of the hashing operation:
| Parameter | Default Value | Purpose | Inherited From |
|---|---|---|---|
memory | 1024 | Memory cost in KiB | src/ArgonHasher.php15 |
time | 2 | Number of iterations | src/ArgonHasher.php20 |
threads | 2 (or 1 for sodium) | Parallelism degree | src/ArgonHasher.php25 |
verifyAlgorithm | false | Enable strict algorithm checking | src/ArgonHasher.php30 |
All configuration methods are inherited and work identically:
Sources: src/ArgonHasher.php35-41 src/ArgonHasher.php102-131
The Argon2IdHasher inherits the sodium provider detection logic from ArgonHasher. When PHP is compiled with libsodium as the Argon2 provider, the threads parameter is automatically forced to 1, regardless of configuration:
This logic is implemented at src/ArgonHasher.php154-156 and ensures compatibility with the libsodium implementation, which does not support multi-threading.
Sources: src/ArgonHasher.php152-159
When verifyAlgorithm is enabled in the constructor options, the check() method performs strict algorithm verification before password validation. This security feature ensures that a hash created with one algorithm variant cannot be verified using a different variant.
The algorithm name 'argon2id' is returned by PHP's password_get_info() function when examining a hash created with PASSWORD_ARGON2ID. This differs from 'argon2i' for hashes created with PASSWORD_ARGON2I.
Sources: src/Argon2IdHasher.php18-19
The following table summarizes the differences between Argon2IdHasher and ArgonHasher:
| Aspect | ArgonHasher (Argon2i) | Argon2IdHasher |
|---|---|---|
| Algorithm Constant | PASSWORD_ARGON2I | PASSWORD_ARGON2ID |
| Algorithm Name | 'argon2i' | 'argon2id' |
| Memory Access Pattern | Data-independent | Hybrid (data-independent + data-dependent) |
| Lines of Code | 160 | 36 |
| Security Characteristics | Resistant to side-channel attacks | Resistant to side-channel and GPU attacks |
| Recommended Use | Environments requiring maximum side-channel resistance | General-purpose password hashing |
| check() Implementation | Calls parent::check() after verification | Calls password_verify() directly |
Sources: src/ArgonHasher.php1-161 src/Argon2IdHasher.php1-36
The Argon2IdHasher is instantiated by the HashManager factory when the 'argon2id' driver is configured:
The factory method passes configuration options from the hashing.php configuration file to the constructor, including memory, time, threads, and verification settings. For details on the factory pattern, see Hash Manager.
Sources: Based on patterns in the codebase architecture
Since make() is inherited from ArgonHasher, creating an Argon2id hash follows the same pattern as Argon2i:
The make() method at src/ArgonHasher.php48-61 calls password_hash() with the algorithm returned by the overridden algorithm() method, which returns PASSWORD_ARGON2ID.
The check() method at src/Argon2IdHasher.php16-27 performs algorithm verification (if enabled) and then validates the password.
The needsRehash() method at src/ArgonHasher.php88-95 uses PHP's password_needs_rehash() with the Argon2id algorithm constant to determine if parameters have changed.
Sources: src/ArgonHasher.php48-95 src/Argon2IdHasher.php16-27
The Argon2IdHasher inherits error handling from ArgonHasher and adds algorithm-specific validation:
| Scenario | Exception/Result | Location |
|---|---|---|
| Argon2 not supported by PHP | RuntimeException: 'Argon2 hashing not supported.' | Inherited from src/ArgonHasher.php57 |
Algorithm mismatch (when verifyAlgorithm=true) | RuntimeException: 'This password does not use the Argon2id algorithm.' | src/Argon2IdHasher.php19 |
| Null or empty hash | Returns false | src/Argon2IdHasher.php22-24 |
Sources: src/Argon2IdHasher.php19 src/Argon2IdHasher.php22-24 src/ArgonHasher.php57
The Argon2IdHasher requires PHP to be compiled with Argon2 support. The availability of PASSWORD_ARGON2ID depends on the PHP version and compilation options:
--with-password-argon2The make() method checks if hashing succeeded and throws a RuntimeException if the algorithm is unavailable, which occurs when password_hash() returns false at src/ArgonHasher.php56
Sources: src/ArgonHasher.php50-58
Argon2id combines the benefits of both Argon2i and Argon2d:
This hybrid approach makes Argon2id the recommended choice for password hashing in most applications, as documented in the Argon2 RFC.
Enabling verifyAlgorithm prevents algorithm confusion attacks where an attacker might attempt to verify an Argon2i hash using the Argon2id verifier. The check at src/Argon2IdHasher.php18 ensures strict algorithm matching.
Sources: src/Argon2IdHasher.php18
Refresh this wiki