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

1. Download the latest release
2. Upload to wp-content/mu-plugins/wp-password-argon/
3. 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

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!