Security Best Practices

Purpose and Scope

This document covers security considerations when using the Hypervel/Hashing package. It provides guidance on algorithm selection, parameter tuning for security vs performance tradeoffs, enabling algorithm verification, and implementing rehashing strategies. For practical usage examples, see Usage Guide. For algorithm-specific implementation details, see Hashing Algorithms.

---

Algorithm Selection

Supported Algorithms Comparison

The package provides three hashing algorithms through distinct implementations:

Algorithm	Class	PHP Constant	Security Level	Use Case
Bcrypt	BcryptHasher	PASSWORD_BCRYPT	Strong	General purpose, legacy compatibility
Argon2i	ArgonHasher	PASSWORD_ARGON2I	Very Strong	Side-channel attack resistance
Argon2id	Argon2IdHasher	PASSWORD_ARGON2ID	Very Strong	Balanced security (recommended)

Sources: src/BcryptHasher.php38 src/ArgonHasher.php68 src/Argon2IdHasher.php34

Algorithm Selection Decision Flow

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

Selection Guidelines

Use Argon2IdHasher (Argon2id) when:

• Starting a new project on PHP 8.2+ (default choice)
• Maximum security is required
• No specific side-channel attack mitigation needed beyond standard protections

Use ArgonHasher (Argon2i) when:

• Specific resistance to side-channel attacks is required
• The environment cannot support Argon2id

Use BcryptHasher when:

• Maintaining compatibility with existing Bcrypt hashes
• Platform limitations prevent Argon2 usage
• Established security requirements mandate Bcrypt

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

---

Parameter Configuration

Bcrypt Rounds Parameter

The BcryptHasher uses a work factor called "rounds" (also referred to as "cost"). This parameter is configurable in the constructor via the rounds option.

Sources: src/BcryptHasher.php15 src/BcryptHasher.php27 src/BcryptHasher.php38-40

Rounds	Approximate Time	Security Level	Recommendation
10	~100ms	Moderate	Minimum for production
12	~400ms	Strong	Recommended default
14	~1.6s	Very Strong	High-security applications
16+	6s+	Maximum	Critical systems only

The rounds parameter is accessible through:

• Constructor: new BcryptHasher(['rounds' => 12])
• Setter method: setRounds(int $rounds) at src/BcryptHasher.php78-83
• Per-hash override: make($value, ['rounds' => 14]) at src/BcryptHasher.php88-91

Sources: src/BcryptHasher.php25-29 src/BcryptHasher.php36-47 src/BcryptHasher.php78-91

Argon2 Parameters

The ArgonHasher and Argon2IdHasher implementations expose three tunable parameters:

Sources: src/ArgonHasher.php15 src/ArgonHasher.php20 src/ArgonHasher.php25 src/ArgonHasher.php50-54 src/ArgonHasher.php152-159

Argon2 Parameter Guidelines

Parameter	Minimum	Recommended	High Security	Maximum Practical
memory	1024 KB	65536 KB (64 MB)	262144 KB (256 MB)	1048576 KB (1 GB)
time	1	4	6	10
threads	1	2	4	8

Memory Cost Considerations:

• Higher values resist GPU/ASIC attacks by requiring more RAM
• Must not exceed server available memory
• Consider concurrent user load

Time Cost Considerations:

• Increases iterations through the algorithm
• Directly impacts hash computation time
• Balance against user experience (target: 250ms-500ms)

Thread Count Considerations:

• Utilizes CPU parallelization
• Limited to 1 when using sodium provider (see src/ArgonHasher.php154-156)
• Should not exceed available CPU cores

Sources: src/ArgonHasher.php14-25 src/ArgonHasher.php35-41 src/ArgonHasher.php136-159

Security vs Performance Tradeoff Analysis

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

Recommended Baseline Configuration:

For production systems with moderate security requirements:

• Bcrypt: rounds = 12
• Argon2: memory = 65536 KB, time = 4, threads = 2

For high-security systems (authentication, financial):

• Bcrypt: rounds = 14
• Argon2: memory = 262144 KB, time = 6, threads = 4

Sources: src/BcryptHasher.php15 src/ArgonHasher.php14-25

---

Algorithm Verification

Both BcryptHasher and ArgonHasher (including Argon2IdHasher) support algorithm verification through the verifyAlgorithm option.

Verification Mechanism

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

Enabling Verification

Algorithm verification is configured through the constructor's verify option:

Sources: src/BcryptHasher.php28 src/ArgonHasher.php40

Verification Behavior

Hasher Class	Expected algoName	Exception Message
BcryptHasher	'bcrypt'	"This password does not use the Bcrypt algorithm."
ArgonHasher	'argon2i'	"This password does not use the Argon2i algorithm."
Argon2IdHasher	'argon2id'	"This password does not use the Argon2id algorithm."

Sources: src/BcryptHasher.php56-57 src/ArgonHasher.php78-79 src/Argon2IdHasher.php18-19

When to Enable Verification

Enable verifyAlgorithm when:

• Migrating between algorithms (prevent acceptance of old algorithm)
• Regulatory compliance requires specific algorithm enforcement
• Multi-tenant systems with per-tenant algorithm policies
• Detecting hash corruption or database attacks

Do not enable when:

• Performing algorithm migration (prevents checking old hashes)
• Supporting multiple algorithms concurrently
• Performance is critical (adds overhead of password_get_info() call)

Sources: src/BcryptHasher.php19-20 src/ArgonHasher.php29-30 src/BcryptHasher.php54-61

---

Rehashing Strategies

The needsRehash() method determines if a hash should be regenerated due to parameter changes.

Rehashing Workflow

Sources: src/BcryptHasher.php66-71 src/ArgonHasher.php88-95

needsRehash() Implementation Details

The needsRehash() method delegates to PHP's password_needs_rehash() function, comparing the stored hash against current configuration:

BcryptHasher:

ArgonHasher/Argon2IdHasher:

Sources: src/BcryptHasher.php66-71 src/ArgonHasher.php88-95

Rehashing Triggers

Trigger	Bcrypt	Argon2i	Argon2id
Algorithm change	Yes	Yes	Yes
Parameter increase	rounds increased	memory, time, or threads increased	memory, time, or threads increased
Parameter decrease	rounds decreased	memory, time, or threads decreased	memory, time, or threads decreased

Sources: src/BcryptHasher.php66-71 src/ArgonHasher.php88-95

Rehashing Best Practices

Implement rehashing during authentication:

Gradual parameter increases:

• Increase parameters incrementally (e.g., rounds 10 → 11 → 12)
• Monitor system performance after each increase
• Allow sufficient time for user base to be rehashed (weeks/months)

Bulk rehashing considerations:

• Never rehash without the plaintext password
• Rehashing occurs naturally during user login over time
• Consider requiring password reset for inactive accounts during major upgrades

Sources: src/BcryptHasher.php66-71 src/ArgonHasher.php88-95

---

Production Security Checklist

Configuration Validation

Security Control	Implementation	References
Minimum Bcrypt Rounds	Set rounds ≥ 12	src/BcryptHasher.php15
Argon2 Memory Floor	Set memory ≥ 65536 KB	src/ArgonHasher.php15
Argon2 Time Floor	Set time ≥ 4	src/ArgonHasher.php20
Algorithm Selection	Use Argon2IdHasher for new projects	src/Argon2IdHasher.php1-36
Enable Verification	Set verify = true when enforcing specific algorithm	src/BcryptHasher.php28 src/ArgonHasher.php40
Rehashing Strategy	Implement needsRehash() checks during authentication	src/BcryptHasher.php66-71 src/ArgonHasher.php88-95

Sources: src/BcryptHasher.php15 src/BcryptHasher.php28 src/ArgonHasher.php15 src/ArgonHasher.php20 src/ArgonHasher.php40

Runtime Security Considerations

Sources: src/BcryptHasher.php36-47 src/ArgonHasher.php48-61 src/Argon2IdHasher.php16-27

Common Security Pitfalls

Pitfall	Risk	Mitigation
Using default rounds = 10 for Bcrypt	Insufficient work factor for modern hardware	Set rounds ≥ 12 in configuration
Disabling verifyAlgorithm during migration	Accepting weaker legacy hashes indefinitely	Implement time-limited migration window
Not implementing needsRehash()	Hashes remain at outdated security level	Add rehashing logic to authentication flow
Synchronous hashing in request path	Request timeout, DoS vulnerability	Consider async processing for bulk operations
Storing hashes in VARCHAR(60)	Truncation when migrating to Argon2	Use VARCHAR(255) for hash column

Sources: src/BcryptHasher.php15 src/BcryptHasher.php54-61 src/BcryptHasher.php66-71 src/ArgonHasher.php76-83 src/ArgonHasher.php88-95

Security Update Process

Regular parameter review schedule:

1. Quarterly: Monitor average hash computation times
2. Annually: Evaluate parameter increases based on hardware improvements
3. After incidents: Review and strengthen parameters if compromise suspected

Algorithm migration procedure:

1. Deploy code supporting both old and new algorithms
2. Disable verifyAlgorithm temporarily
3. Implement needsRehash() checking during authentication
4. Monitor migration progress via metrics
5. After 90%+ migration, optionally enable verifyAlgorithm for new algorithm
6. Force password resets for remaining inactive accounts

Sources: src/BcryptHasher.php19-20 src/BcryptHasher.php54-61 src/BcryptHasher.php66-71 src/ArgonHasher.php29-30 src/ArgonHasher.php76-83 src/ArgonHasher.php88-95