WP Password Argon Two
Securely store WordPress user passwords in database with Argon2i hashing and SHA-512 HMAC using PHP's native functions.
- Magic Moments
- Frequently Asked Questions
- What have you done with the passwords?
- I have installed this plugin. Does it mean my WordPress site is unhackable?
- Did you reinvent the cryptographic functions?
- Pepper migration look great. Does it mean that I can keep as many pepper keys as I want?
- What if my pepper is compromised?
- Is pepper-ing perfect?
- Is WordPress' phpass hasher or Bcrypt insecure?
- Why use Argon2i over the others?
- Does this plugin has 72-character limit like Bcrypt?
- It looks awesome. Where can I find some more goodies like this?
- This plugin isn't on wp.org. Where can I give a
⭐️ ⭐️ ⭐️ ⭐️ ⭐️review?
- This plugin isn't on wp.org. Where can I make a complaint?
- Change Log
Replace WordPress' phpass hasher with Argon2i hashing and SHA-512 HMAC.
Adopted from Mozilla secure coding guidelines:
- Passwords stored in a database should using the hmac+argon2i function.
The purpose of HMAC and Argon2i storage is as follows:
- Argon2i provides a hashing mechanism which can be configured to consume sufficient time to prevent brute forcing of hash values even with many computers
- Argon2i can be easily adjusted at any time to increase the amount of work and thus provide protection against more powerful systems
- The nonce(pepper) for the HMAC value is designed to be stored on the file system and not in the databases storing the password hashes. In the event of a compromise of hash values due to SQL injection, the nonce(pepper) will still be an unknown value since it would not be compromised from the file system. This significantly increases the complexity of brute forcing the compromised hashes considering both Argon2i and a large unknown nonce(pepper) value
- The HMAC operation is simply used as a secondary defense in the event there is a design weakness with Argon2i that could leak information about the password or aid an attacker
WP Password Argon Two just works when:
upgrading from extremely old WordPress versions
user passwords were hashed with MD5
upgrading from recent WordPress versions
user passwords were hashed with phpass hasher
upgrading from WP Password Bcrypt
user passwords were hashed with Bcrypt
changing Argon2i options
using new pepper while moving the old ones into
User passwords will be rehashed during the next login.
Do Your Homework
Don't blindly trust any random security guide/plugin on the scary internet - including this one!
Do your research:
PHP 7.2+ and compiled
To check whether PHP is compiled with Argon2:
# Good: Compiled with Argon2 ➜ php -r 'print_r(get_defined_constants());' | grep -i argon [PASSWORD_ARGON2I] => 2 [PASSWORD_ARGON2_DEFAULT_MEMORY_COST] => 1024 [PASSWORD_ARGON2_DEFAULT_TIME_COST] => 2 [PASSWORD_ARGON2_DEFAULT_THREADS] => 2 [SODIUM_CRYPTO_PWHASH_ALG_ARGON2I13] => 1 [SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13] => 2 [SODIUM_CRYPTO_PWHASH_STRPREFIX] => $argon2id$
If you don't get the above output, either re-compile PHP 7.2+ with the flag
➜ sudo add-apt-repository ppa:ondrej/php ➜ sudo apt-get update ➜ sudo apt-get install php7.2
➜ brew update ➜ brew install php
This plugin should not be installed as a normal WordPress plugin.
Option A: Via Composer Autoload (Recommended)
➜ composer require typisttech/wp-password-argon-two
Note: Files in
src will be autoloaded by composer. WP Password Argon Two won't appear in the WP admin dashboard.
Option B: As a Must-use Plugin (Last Resort)
# Example ➜ tree ./wp-content/mu-plugins ./wp-content/mu-plugins ├── src │ ├── Manager.php │ ├── ManagerFactory.php │ ├── PasswordLock.php │ ├── Validator.php │ ├── ValidatorInterface.php │ ├── WordPressValidator.php │ └── pluggable.php └── wp-password-argon-two.php
Option A - Use Constants
Add these constants into
define('WP_PASSWORD_ARGON_TWO_PEPPER', 'your-long-and-random-pepper'); define('WP_PASSWORD_ARGON_TWO_FALLBACK_PEPPERS', ); define('WP_PASSWORD_ARGON_TWO_OPTIONS', );
Option B - Use Environment Variables
Recommended for all Trellis users.
In some cases, you want to change the pepper without changing all user passwords.
define('WP_PASSWORD_ARGON_TWO_PEPPER', 'new-pepper'); define('WP_PASSWORD_ARGON_TWO_FALLBACK_PEPPERS', [ 'old-pepper-2', 'old-pepper-1', ]);
During the next user login, his/her password will be rehashed with
Due to the variety of platforms PHP runs on, the cost factors are deliberately set low as to not accidentally exhaust system resources on shared or low resource systems when using the default cost parameters. Consequently, users should adjust the cost factors to match the system they're working on. As Argon2 doesn't have any "bad" values, however consuming more resources is considered better than consuming less. Users are encouraged to adjust the cost factors for the platform they're developing for.
-- PHP RFC
You can adjust the options via
// Example define('WP_PASSWORD_ARGON_TWO_OPTIONS', [ 'memory_cost' => 1<<17, // 128 Mb 'time_cost' => 4, 'threads' => 3, ]);
You have to regenerate all user passwords after uninstallation because we can't rehash without knowing the passwords in plain text.
Frequently Asked Questions
What have you done with the passwords?
In a nutshell:
password_hash( hash_hmac('sha512', $userPassword, WP_PASSWORD_ARGON_TWO_PEPPER), PASSWORD_ARGON2I, WP_PASSWORD_ARGON_TWO_OPTIONS );
Don't take my word for it. Read the source code!
I have installed this plugin. Does it mean my WordPress site is unhackable?
No website is unhackable.
To have a secure WordPress site, you have to keep all these up-to-date:
- WordPress core
- this plugin
- all other WordPress themes and plugins
- everything on the server
- other security practices
- your mindset
Did you reinvent the cryptographic functions?
Of course not! This plugin use PHP's native functions.
Repeat: Read the source code!
Pepper migration look great. Does it mean that I can keep as many pepper keys as I want?
In a sense, yes, you could do that. However, each pepper slows down the login process a little bit.
To test the worst case, log in with an incorrect password.
What if my pepper is compromised?
- Remove that pepper from
- Regenerate all user passwords
Is pepper-ing perfect?
No! Read paragonie's explaination.
For those who can't stand with the drawbacks, use one of the alternatives instead.
Is WordPress' phpass hasher or Bcrypt insecure?
Both WordPress' phpass hasher and Bcrypt are secure. There is no emergent reason to upgrade.
Learn more about the reasons about not using WordPress' default.
Why use Argon2i over the others?
Argon2 password-based key derivation function is the winner of the Password Hashing Competition in July 2015, ranked better than Bcrypt and PBKDF2.
Argon2 comes with 3 different modes: Argon2d, Argon2i, Argon2id. Argon2i is the one for password hashing. See: https://crypto.stackexchange.com/a/49969
Does this plugin has 72-character limit like Bcrypt?
No. Read the test.
It looks awesome. Where can I find some more goodies like this?
- Articles on Typist Tech's blog
- Tang Rufus' WordPress plugins on wp.org
- More projects on Typist Tech's GitHub profile
- Stay tuned on Typist Tech's newsletter
- Follow Tang Rufus' Twitter account
- Hire Tang Rufus to build your next awesome site
This plugin isn't on wp.org. Where can I give a
⭐️ ⭐️ ⭐️ ⭐️ ⭐️ review?
This plugin isn't on wp.org. Where can I make a complaint?
To be honest, I don't care.
If you really want to share your 1-star review, send me an email - in the first paragraph, state how many times I have told you to read the plugin source code.
Love WP Password Argon Two? Help me maintain it, a donation here can help with it.
Why don't you hire me?
Want to help in other way? Want to be a sponsor?
Contact: Tang Rufus
To setup a developer workable version you should run these commands:
$ composer create-project --keep-vcs --no-install typisttech/wp-password-argon-two:dev-master $ cd wp-password-argon-two $ composer install
To run the tests:
$ composer test
Please provide feedback! We want to make this library useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.
Please see CHANGELOG for more information on what has changed recently.
If you discover any security related issues, please email firstname.lastname@example.org instead of using the issue tracker.
Full list of contributors can be found here.
The MIT License (MIT). Please see License File for more information.