README

=== PHP Native Password Hash ===
Contributors: ayeshrajans
Tags: password, password hashing, password_hash, bcrypt, argon2, argon2i, argon2id, sodium, password security, security
Requires at least: 5.2
Tested up to: 6.5
Stable tag: 3.0
Requires PHP: 7.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Makes WordPress use PHP's native password_hash() functions for portable, stronger, and time-attack safe bcrypt and Argon2 hashes.

== Description ==

This plugin swaps out WordPress core's password hashing mechanism with PHP 5.5's `password_hash()` and its accompanying functions. By default, PHP uses bcrypt to hash the passwords. If available, this plugin will use modern Argon2 algorithm. The transition will be transparent.

*  A password salt will be generated using a Cryptographically Secure Pseudo-Random Number Generator (`CSPRNG`)
*  Password hashes are safe from dictionary attacks with rainbow tables or any other precomputed hash lists, because a secure salt is generated for each password.
*  The password hashing is iterated multiple times to provide a good resistance against brute-force attacks.
*  Password checks are made in a way that it mitigates time-attacks.
*  You do not have to reset passwords of all users. Passwords already hashed in the database will be rehashed automatically and transparently the next time the user logs in.
*  PHP might come up with newer password hashing algorithms, and they will be automatically supported without having to reset all the passwords.

This plugin was made initially because one of our applications used WordPress for authentication, but we needed to use an external system
to verify the passwords directly from the database too. Since WordPress has its own password hashing algorithm, we decided to make this plugin to address that problem.
With this plugin, passwords generated by both WordPress and other custom applications now use the PHP's default `password_hash()` functions without compromising any of the applications' security.

This plugin is designed to be as minimal and fast as possible, and can be considered a must-use for EVERY WordPress application given the minimal footprint of this plugin, and considering the importance of using a secure hashing algorithm for passwords.

== Installation ==

1. Upload the plugin files to the `/wp-content/plugins/password-hash` directory, or install the plugin through the WordPress plugins screen directly.
1. Activate the plugin through the 'Plugins' screen in WordPress.
1. You are all set! There is nothing to configure. All existing users passwords will be rehashed on their next successful login. There is no configuration UI; it just works.


== Frequently Asked Questions ==

= Do I have to reset all existing passwords?  =

Nope! This plugin is smart enough to identify an old password hash, capable to seamlessly validate it using the old algorithm, and update the hash with the new version automatically. Your users wouldn't notice a thing.

= What happens if I uninstall this plugin? =

Password hashing is a one-way operation, and it's near impossible to extract the original password from the hash. This
means we cannot undo the effect of this plugin. Your existing users will need to reset their passwords. However, your
password hashes will remain safe. This plugin is does one specific thing and does it well. There should be no significant
impact on using this plugin.

= How do I confirm the new hashing algorithm is in use? =

The easiest way would be to check your database from PHPMyAdmin or any other software in its line. Check if the password
hash field in your users table has the format `$2y$10...`. Those who have not updated their hashes will have a different
format. However, if the plugin is unable to override the password hashing algorithm from WordPress core, you will see a
notification in your dashboard. If you do not see anything, you are golden.

= How to use `Argon2I` and `Argon2ID` hashing algorithms? =

To keep the plugin size minimal, this plugin does not offer a UI configuration page. You can set the password hashing
algorithm with a configuration value set in `wp-config.php` file.

Open your `wp-config.php` file at the root of your WordPress site, and find the line that says `That's all, stop editing! Happy publishing`.
Above this line, you can configure the hashing algorithm you want this plugin to use. Note that a wrong configuration value
means your users will not be able to log in until you fix this configuration option. It's not recommended that you set
this configuration value unless you know what you are doing.

`define( 'WP_PASSWORD_HASH_ALGO', PASSWORD_ARGON2ID );`

You can use the following values depending on your PHP version:
 - **PHP 7.2 or later**: `PASSWORD_ARGON2I`
 - **PHP 7.3 or later**: `PASSWORD_ARGON2ID` (recommended)

= How do I configure options for the specified hashing algorithm? =

Alrighty folks, read carefully: This plugin can listen to a configuration option you specify and pass it along to the hashing
process. Please make sure you are absolutely sure about the values you set here. If you set a value too easy to crack,
you will open up a security vulnerability in your site. If you set a value too high, your server will take too much resources.

This plugin does not make any effort to *validate* the configuration you set. If you do not configure a value, plugin will
use the default value your PHP version comes with.

If you would still like to configure these options, similar to the way you set the hashing algorithm, open the `wp-config.php`
file for your WordPress site (at root of your WordPress installation), and right below the line that you configure hashing
algorithm (see FAQ above), set your configuration values as well. Here is an example (not necessarily a recommendation):

`define( 'WP_PASSWORD_HASH_OPTIONS', ['memory_cost' => 2<<16, 'time_cost' => \PASSWORD_ARGON2_DEFAULT_TIME_COST, 'threads' => \PASSWORD_ARGON2_DEFAULT_THREADS]] );`

The values you set here will be different based on the algorithm you set. You *must* set the `WP_PASSWORD_HASH_ALGO`
configuration in order for this to be effective.

See https://www.php.net/manual/en/password.constants.php for more examples and information.

**Existing password hashes will be updated the next time the user logs in. Existing hashes will be checked using the existing algorithm regardless of this configuration.**

= How did pirates collaborate before computers? =

Pier to pier networking.

== Changelog ==

= 1.0 =
* Initial release.

= 1.1 =
* Fixed a bug for PHP 5.5 users whose PHP core lacks the time-safe hash_equals function, resulting in a fatal error. This version introduces a polyfill to add that functionality for PHP 5.5 users. Users with newer PHP versions will use PHP-provided hash_equals() function.

= 1.2 =
* This plugin now requires WordPress minimum version 3.9.2 the least, and uses the hash_equals() function polyfill provided by WordPress core.

= 1.4 =
* Skipped 1.3 version because a WIP Argon2i support conflicted with the bug fix (#2). Argon2i support will be added in a future release.
* Fixes an error with password validation when the PasswordHash class from WordPress core is not loaded. See #2

= 1.5 =
* Fix a security issue with the password verification when updating from a password_hash()-compatible hashing algorithm to another. Thanks to Steve Thomas (Sc00bz on GitHub).

= 2.0 =
This is a major rewrite of the plugin. This version still requires PHP 5.5, but WordPress 5.2+ now requires PHP version 5.6 to function, and this is enforced at plugin level as well.

Core functionality of the plugin is extracted to a separate class. This plugin aims to be as light-weight as possible, and this version cuts the main plugin file size to less than half the v1.x size.

There is a new namespaced PasswordHash class that is cleaner and well-structured compared to our v1 code base.

* Fixes a bug that the hook-provided hash cost changes did not trigger a password rehash. Thanks to Steve Thomas (Sc00bz on GitHub).
* Adds support for Argon2I, Argon2ID and any future hashing algorithms PHP will introduce. See the updated FAQ item on how to use the new hashing algorithms.
* Removed a helper function used to trigger an admin warning if the plugin cannot properly work. The notices are now shown with help of lambda functions (which further reduces the code bloat and load).

= 2.1 =
* Adds support for "WP_PASSWORD_HASH_OPTIONS" configuration option that can be set in `wp-config.php` to configure password hashing options.
* Update WordPress core "Tested up to" field to WordPress 5.6.

= 3.0 =
* Drops support for PHP < 7.0
* Class methods and functions have return types where applicable.
* Tested upto WordPress 6.3
* Uses FQFN/FQCN where available as a micro-optimization