Hashing Algorithms

Purpose and Scope

This document provides an overview of the three cryptographic hashing algorithms supported by the Hypervel/Hashing library. It covers their implementation classes, security characteristics, configuration parameters, and selection criteria. For detailed implementation specifics of each algorithm, see the child pages: Bcrypt Hasher, Argon2i Hasher, and Argon2id Hasher. For configuration details, see Configuration. For usage examples, see Usage Guide.

Sources: src/BcryptHasher.php1-92 src/ArgonHasher.php1-160 src/Argon2IdHasher.php1-36

Supported Algorithms

The library provides three password hashing algorithm implementations, each wrapping PHP's native password_* functions with additional configuration and validation logic:

Algorithm	Implementation Class	PHP Constant	Importance Score
Bcrypt	BcryptHasher	PASSWORD_BCRYPT	⭐ 10.68
Argon2i	ArgonHasher	PASSWORD_ARGON2I	⭐ 11.12
Argon2id	Argon2IdHasher	PASSWORD_ARGON2ID	⭐ 4.42

All three implementations extend AbstractHasher and implement the Hasher contract, providing consistent methods: make(), check(), needsRehash(), and info().

Sources: src/BcryptHasher.php10 src/ArgonHasher.php10 src/Argon2IdHasher.php9

Implementation Hierarchy

Diagram: Algorithm Implementation Class Hierarchy

The Argon2IdHasher extends ArgonHasher rather than AbstractHasher directly, inheriting all Argon2i configuration logic and only overriding the algorithm() method and check() method for algorithm-specific verification.

Sources: src/BcryptHasher.php10 src/ArgonHasher.php10 src/Argon2IdHasher.php9-36

Algorithm Characteristics

Bcrypt

Bcrypt is a widely-supported, CPU-intensive hashing algorithm based on the Blowfish cipher. The BcryptHasher implementation configures hashing through a single parameter:

Parameter	Property	Default	Range	Description
rounds / cost	$rounds	10	4-31	Logarithmic cost factor controlling iterations

The algorithm uses the PASSWORD_BCRYPT constant and delegates to PHP's password_hash() function with the cost parameter src/BcryptHasher.php38-40 The implementation includes optional algorithm verification via the $verifyAlgorithm property src/BcryptHasher.php20 which throws a RuntimeException if a hash was created with a different algorithm src/BcryptHasher.php56-58

Sources: src/BcryptHasher.php14-15 src/BcryptHasher.php36-47 src/BcryptHasher.php54-61

Argon2i

Argon2i is a memory-hard hashing algorithm designed to resist GPU and ASIC attacks through high memory usage. The ArgonHasher implementation provides three configuration parameters:

Parameter	Property	Default	Description
memory	$memory	1024	Memory cost in KiB
time	$time	2	Time cost (iterations)
threads	$threads	2	Parallelism factor

The threads parameter has special handling: when PHP uses the Sodium provider (PASSWORD_ARGON2_PROVIDER === 'sodium'), threads are forced to 1 src/ArgonHasher.php154-156 This accounts for the Sodium library's single-threaded implementation.

The make() method uses the PASSWORD_ARGON2I constant and passes all three parameters to password_hash() src/ArgonHasher.php50-54 Algorithm verification is available via the $verifyAlgorithm property, checking for the 'argon2i' algorithm name src/ArgonHasher.php78-80

Sources: src/ArgonHasher.php14-25 src/ArgonHasher.php48-61 src/ArgonHasher.php152-159

Argon2id

Argon2id is a hybrid variant combining Argon2i's resistance to side-channel attacks with Argon2d's resistance to GPU attacks. The Argon2IdHasher extends ArgonHasher, inheriting all configuration parameters (memory, time, threads) while using the PASSWORD_ARGON2ID constant src/Argon2IdHasher.php32-35

The implementation overrides two methods:

• algorithm(): Returns PASSWORD_ARGON2ID instead of PASSWORD_ARGON2I src/Argon2IdHasher.php32-35
• check(): Verifies the hash uses the 'argon2id' algorithm name when verification is enabled src/Argon2IdHasher.php16-27

Sources: src/Argon2IdHasher.php9-36

Configuration Parameters by Algorithm

Diagram: Configuration Parameters Across Algorithm Implementations

All parameters are set via the constructor's $options array src/BcryptHasher.php25-29 src/ArgonHasher.php35-41 and can be overridden per-operation by passing options to make(), check(), or needsRehash().

Sources: src/BcryptHasher.php25-29 src/ArgonHasher.php35-41 src/BcryptHasher.php86-91 src/ArgonHasher.php134-159

Algorithm Selection Guidance

Security Properties

Property	Bcrypt	Argon2i	Argon2id
Resistance to:
Brute-force (CPU)	✓ High	✓ High	✓ High
GPU/ASIC attacks	✓ Moderate	✓ High	✓ Very High
Side-channel attacks	✗ Limited	✓ Optimized	✓ Hybrid
Resource usage:
Memory	Low (~4 KiB)	Configurable (KiB)	Configurable (KiB)
CPU	Configurable	Configurable	Configurable
Standard:	Widely adopted	Modern (2015)	Modern (2015)

Sources: src/BcryptHasher.php38-40 src/ArgonHasher.php50-54 src/Argon2IdHasher.php32-35

When to Use Each Algorithm

Use Bcrypt when:

• Maximum compatibility across PHP environments is required
• Memory constraints are strict (shared hosting, containers)
• Legacy systems require migration compatibility
• The PASSWORD_BCRYPT constant is guaranteed available

Use Argon2i when:

• Side-channel attack resistance is a priority
• Data-dependent access patterns must be avoided
• The PHP installation includes Argon2 support

Use Argon2id when:

• Maximum security against diverse attack vectors is required
• Both side-channel and GPU resistance are needed
• Modern PHP environment (7.3+) with Argon2id support
• This is the recommended default for new applications

The HashManager selects the algorithm based on the driver configuration key see Configuration. The default driver can be overridden per-operation using driver-specific methods.

Sources: src/ArgonHasher.php66-69 src/Argon2IdHasher.php32-35

Algorithm Verification

All three implementations support optional algorithm verification through the verifyAlgorithm constructor option src/BcryptHasher.php20 src/ArgonHasher.php30 When enabled:

• BcryptHasher::check() throws RuntimeException if the hash algorithm name is not 'bcrypt' src/BcryptHasher.php56-58
• ArgonHasher::check() throws RuntimeException if the hash algorithm name is not 'argon2i' src/ArgonHasher.php78-80
• Argon2IdHasher::check() throws RuntimeException if the hash algorithm name is not 'argon2id' src/Argon2IdHasher.php18-20

This feature prevents accepting hashes created with weaker algorithms during authentication, enforcing algorithm-specific policies. The algorithm name is extracted using PHP's password_get_info() function via AbstractHasher::info().

Diagram: Algorithm Verification Flow in check() Method

Sources: src/BcryptHasher.php54-61 src/ArgonHasher.php76-83 src/Argon2IdHasher.php16-27

Runtime Algorithm Detection

Each hasher exposes its algorithm constant through a protected algorithm() method:

• BcryptHasher::algorithm() returns PASSWORD_BCRYPT (implicitly, not shown in code)
• ArgonHasher::algorithm() returns PASSWORD_ARGON2I src/ArgonHasher.php66-69
• Argon2IdHasher::algorithm() returns PASSWORD_ARGON2ID src/Argon2IdHasher.php32-35

These constants are passed to password_hash() during hash creation and password_needs_rehash() during rehash checking, ensuring consistent algorithm usage across operations.

Sources: src/ArgonHasher.php66-69 src/Argon2IdHasher.php32-35