README

Enhance WordPress security by replacing outdated MD5 password hashing with modern Argon2i encryption

The Problem

WordPress still uses MD5-based password hashing (via PHPass), an algorithm from 2001 that's considered weak by modern security standards. While adequate for its time, MD5 is vulnerable to:

⚠️ Brute force attacks (fast to compute)
⚠️ Rainbow table attacks
⚠️ GPU-accelerated cracking

The Solution

This must-use plugin replaces WordPress's password hashing system with:

✅ Argon2i - Winner of Password Hashing Competition (2015)
✅ SHA-512 HMAC - Additional layer of protection
✅ Automatic migration - Rehashes old passwords on login
✅ Zero configuration - Drop in and forget
✅ Backward compatible - Works with existing WordPress user system

Key Features

🔐 Modern Cryptography

Argon2i algorithm - Memory-hard hashing designed to resist GPU attacks
SHA-512 HMAC - Adds salt-based message authentication
Native PHP functions - No external dependencies, uses PHP's password_hash()

🔄 Seamless Migration

Automatically detects old MD5 hashes
Rehashes passwords when users login
No manual migration needed
Maintains backward compatibility during transition

🎯 Drop-in Replacement

Overrides core WordPress functions: wp_hash_password(), wp_check_password(), wp_set_password()
Works as must-use plugin (loads before regular plugins)
Supports Application Passwords (WordPress 5.6+)
No configuration required

⚡ Performance

Minimal overhead compared to MD5
Argon2i parameters can be customized via filter
Efficient rehashing on authentication

Installation

Via Composer (Recommended)

composer require jazzman/wp-password-argon

The package installs automatically to wp-content/mu-plugins/wp-password-argon/ via Composer Installers.

Manual Installation

Download the latest release
Upload to wp-content/mu-plugins/wp-password-argon/
That's it! No activation needed (must-use plugins auto-load)

How It Works

Password Hashing Flow

User enters password
    ↓
SHA-512 HMAC with WordPress salt
    ↓
Argon2i hashing with memory cost
    ↓
Stored in database

Authentication Flow

User login attempt
    ↓
Check if password uses Argon2i
    ↓
├─ Yes → Verify with password_verify()
└─ No (old MD5) → Verify with PHPass
                 → Rehash with Argon2i
                 → Update database

Configuration

The plugin works out-of-the-box with secure defaults. To customize Argon2i parameters:

add_filter('wp_hash_password_options', function() {
    return [
        'memory_cost' => PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
        'time_cost'   => PASSWORD_ARGON2_DEFAULT_TIME_COST,
        'threads'     => PASSWORD_ARGON2_DEFAULT_THREADS,
    ];
});

Security Benefits

Aspect	MD5 (WordPress default)	Argon2i (This plugin)
Algorithm Age	1992 (33 years old)	2015 (10 years old, current best practice)
Cracking Speed	Very fast	Slow (memory-hard)
GPU Resistance	❌ Weak	✅ Strong
Rainbow Tables	❌ Vulnerable	✅ Resistant
OWASP Recommended	❌ No	✅ Yes

Requirements

PHP: 7.4+ or 8.1+ (PHP 8+ recommended)
WordPress: 5.2+
PHP Extensions:
- sodium (usually bundled with PHP 7.2+)
- No additional extensions needed

Under The Hood

Quality Tooling

This package maintains high code quality standards:

# Static Analysis
composer phpstan        # PHPStan max level
composer psalm          # Psalm strict mode

# Code Style
composer cs-check       # Check PSR-12 compliance
composer cs-fix         # Auto-fix code style

# Baseline Management
composer update-baseline # Update analysis baselines

Tech Stack

Static Analysis: PHPStan (max level), Psalm
Code Style: PHP CS Fixer with custom rules (jazzman/php-cs-fixer-rules)
Security Auditing: Roave Security Advisories
Type Safety: WordPress stubs for IDE support

Package Configuration

Type: wordpress-muplugin (auto-installs to mu-plugins)
License: MIT
Optimizations: APCu autoloader, optimized autoloader, authoritative classmap

FAQ

Q: Will this break my existing WordPress site?
A: No. The plugin is backward compatible. Old passwords work during the transition period and are automatically upgraded on user login.

Q: What happens if I remove the plugin?
A: Users with Argon2i passwords won't be able to login. Recommendation: Keep the plugin installed once deployed.

Q: Does this work with multisite?
A: Yes. Install as network-wide must-use plugin.

Q: Performance impact?
A: Minimal. Argon2i is slightly slower than MD5, but this is intentional (security vs. speed trade-off). Typical impact: <100ms per authentication.

Q: Can I migrate back to MD5?
A: Technically possible but strongly discouraged for security reasons. Once passwords are hashed with Argon2i, they should stay that way.

Why This Matters

Real-world impact:

WordPress powers 43% of the web
Over 455 million websites use WordPress
Default MD5 hashing leaves millions of sites vulnerable
This plugin provides enterprise-grade security with zero effort

Recommended by:

✅ OWASP (Open Web Application Security Project)
✅ NIST (National Institute of Standards and Technology)
✅ PHP Security Best Practices

Related Packages

Part of the jazzman WordPress ecosystem:

jazzman/wp-performance - Performance & security optimizations
jazzman/wp-object-cache - PSR-16 object caching
jazzman/wp-nav-menu-cache - Navigation menu caching

License

MIT License - see LICENSE file for details.

Author

Vasyl Sokolyk

GitHub: @Jazz-Man
LinkedIn: vasyl5

Support & Contributing

Found a bug? Have a feature request? Open an issue on GitHub.

Security vulnerabilities: Please email vsokolyk@gmail.com directly rather than opening a public issue.

⭐ If this plugin improved your WordPress security, please star the repo!

jazzman / wp-password-argon

Maintainers

Details