Securely store WordPress user passwords in database with Argon2i hashing and Blake2b using PHP + libsodium.
- Goal
- Magic Moments
- Requirements
- Installation
- Usage
- Uninstallation
- 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?
- Alternatives
- Support!
- Developing
- Feedback
- Change Log
- Security
- Credits
- License
Replace WordPress' phpass hasher with Argon2i hashing and Blake2b.
Adopted from Mozilla secure coding guidelines:
- Passwords stored in a database should using the blake2b+argon2i function.
- Blake2b hash is generated using function from libsodium
The purpose of Blake2b 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 Blake2b 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 Blake2b 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
WP_PASSWORD_ARGON_TWO_FALLBACK_PEPPERS
User passwords will be rehashed during the next login.
Don't blindly trust any random security guide/plugin on the scary internet - including this one!
Do your research:
- Read the whole readme
- Read the source code
- Compare with other alternatives
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 --with-password-argon2 or:
- Ubuntu
➜ sudo add-apt-repository ppa:ondrej/php ➜ sudo apt-get update ➜ sudo apt-get install php7.2
- macOS
➜ brew update ➜ brew install php
To check wheter libsodium is installed in current PHP installation:
# Good: Libsodium is installed
➜ php -r 'print_r(get_loaded_extensions());' | grep -i sodium
[..] => sodium
# (or if you're using Windows for some reason)
➜ php -r 'print_r(get_loaded_extensions());' | findstr /i "sodium"
[..] => sodiumIf you don't get the above output,
- Add libsodium:
- Ubuntu
➜ sudo apt-get install -y php-libsodium
- Arch
➜ sudo pacman -Sy php-libsodium
- Change php.ini; inside php.ini, uncomment line below:
extension=sodium
Read the whole readme and the source code before going any further.
This plugin should not be installed as a normal WordPress plugin.
(Composer installation is WIP)
Manually copy wp-password-argon-two.php and the whole src directory into mu-plugins folder.
# 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.phpAdd these constants into wp-config.php:
define('WP_PASSWORD_ARGON_TWO_PEPPER', 'your-long-and-random-pepper');
define('WP_PASSWORD_ARGON_TWO_FALLBACK_PEPPERS', []);
define('WP_PASSWORD_ARGON_TWO_OPTIONS', []);Note: Each pepper must have length >= 16 bytes.
Defining the required constants in application code violates 12-factor principle. The typisttech/wp-password-argon-two-env package allows you to configure with 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 new-pepper.
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 WP_PASSWORD_ARGON_TWO_OPTIONS:
// Example
define('WP_PASSWORD_ARGON_TWO_OPTIONS', [
'memory_cost' => 1<<17, // 128 Mb
'time_cost' => 4,
'threads' => 3,
]);Learn more about available options and picking appropriate options.
You have to regenerate all user passwords after uninstallation because we can't rehash without knowing the passwords in plain text.
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!
No website is unhackable.
To have a secure WordPress site, you have to keep all these up-to-date:
- WordPress core
- PHP
- this plugin
- all other WordPress themes and plugins
- everything on the server
- other security practices
- your mindset
Of course not! This plugin use PHP's native functions.
Repeat: Read the source code!
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.
- Remove that pepper from
WP_PASSWORD_ARGON_TWO_PEPPERandWP_PASSWORD_ARGON_TWO_FALLBACK_PEPPERS - Regenerate all user passwords
No! Read paragonie's explaination.
For those who can't stand with the drawbacks, use one of the alternatives instead.
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.
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
No. Read the test.
- 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
Thanks!
Consider writing a blog post, submitting pull requests, donating or hiring me instead.
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.
Ready to take freelance WordPress jobs. Contact me via the contact form here or, via email [email protected]
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 installTo run the tests:
$ composer testPlease 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 [email protected] instead of using the issue tracker.
WP Password Argon Two is a Typist Tech project and maintained by Tang Rufus, freelance developer for hire.
Full list of contributors can be found here.
The MIT License (MIT). Please see License File for more information.