PHPackages                             typisttech/wp-password-argon-two - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. typisttech/wp-password-argon-two

Abandoned → [roots/wp-password-bcrypt](/?search=roots%2Fwp-password-bcrypt)ArchivedLibrary[Security](/categories/security)

typisttech/wp-password-argon-two
================================

Securely store WordPress user passwords in database with Argon2i hashing and SHA-512 HMAC using PHP's native functions.

0.2.2(4y ago)234343[2 issues](https://github.com/typisttech/wp-password-argon-two/issues)[1 PRs](https://github.com/typisttech/wp-password-argon-two/pulls)1MITPHPPHP ^7.2 || ^8.0

Since Feb 27Pushed 1y ago1 watchersCompare

[ Source](https://github.com/typisttech/wp-password-argon-two)[ Packagist](https://packagist.org/packages/typisttech/wp-password-argon-two)[ Docs](https://github.com/TypistTech/wp-password-argon-two)[ Fund](https://typist.tech/donation/)[ RSS](/packages/typisttech-wp-password-argon-two/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (6)Used By (1)

Caution

[WP Password Argon Two](https://github.com/typisttech/wp-password-argon-two) has been **abandoned**.

If you want to maintain a fork of [WP Password Argon Two](https://github.com/typisttech/wp-password-argon-two), read this [blog post](https://blog.ircmaxell.com/2015/03/security-issue-combining-bcrypt-with.html) ([Wayback Machine snaptshot](https://web.archive.org/web/20240722115642/https://blog.ircmaxell.com/2015/03/security-issue-combining-bcrypt-with.html)). Otherwise, use [roots/wp-password-bcrypt](https://github.com/roots/wp-password-bcrypt).

WP Password Argon Two
=====================

[](#wp-password-argon-two)

[![Latest Stable Version](https://camo.githubusercontent.com/56f19081c1428bbc159ab7afdaff122d0f90aaa9c1f7f4415bc3b888845b7f6b/68747470733a2f2f706f7365722e707567782e6f72672f747970697374746563682f77702d70617373776f72642d6172676f6e2d74776f2f762f737461626c65)](https://packagist.org/packages/typisttech/wp-password-argon-two)[![Total Downloads](https://camo.githubusercontent.com/586455c96bc125167f5bc451397d84cc2d0e1b375d6fc28523d0ad51f6d9c488/68747470733a2f2f706f7365722e707567782e6f72672f747970697374746563682f77702d70617373776f72642d6172676f6e2d74776f2f646f776e6c6f616473)](https://packagist.org/packages/typisttech/wp-password-argon-two)[![Build Status](https://camo.githubusercontent.com/57ca759c71b1848a39540ce43f42eacd166e7007cc5c7a6cc022d6ad4af082eb/68747470733a2f2f7472617669732d63692e6f72672f547970697374546563682f77702d70617373776f72642d6172676f6e2d74776f2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/TypistTech/wp-password-argon-two)[![StyleCI](https://camo.githubusercontent.com/9a71903e29ad5fd614c48e8d8b540dd17db99fb525fd9778094b1ed2c8be2054/68747470733a2f2f7374796c6563692e696f2f7265706f732f3132313039333137342f736869656c643f6272616e63683d6d6173746572)](https://styleci.io/repos/121093174)[![License](https://camo.githubusercontent.com/74401a4d2bcd6f4aa6c9d45b38f99030f3fe47c58d6b3ce75c35fa72fe831dba/68747470733a2f2f706f7365722e707567782e6f72672f747970697374746563682f77702d70617373776f72642d6172676f6e2d74776f2f6c6963656e7365)](https://packagist.org/packages/typisttech/wp-password-argon-two)[![Donate via PayPal](https://camo.githubusercontent.com/b57c445af971e3e99c2d0ccdbf4fa7faa4358ba27fecc8f68459b30289f82eda/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f6e6174652d50617950616c2d626c75652e737667)](https://typist.tech/donate/wp-password-argon-two/)[![Hire Typist Tech](https://camo.githubusercontent.com/e392a964bbdc0c32d95825bbc8253027387bcb9b021176d807d22ac75d86f308/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f486972652d547970697374253230546563682d6666363962342e737667)](https://typist.tech/contact/)

Securely store WordPress user passwords in database with Argon2i hashing and SHA-512 HMAC using PHP's native functions.

- [Goal](#goal)
- [Magic Moments](#magic-moments)
- [Requirements](#requirements)
    - [Do Your Homework](#do-your-homework)
    - [PHP 7.2+ and compiled `--with-password-argon2`](#php-72-and-compiled---with-password-argon2)
- [Installation](#installation)
    - [Step 0](#step-0)
    - [Step 1](#step-1)
        - [Option A: Via Composer Autoload (Recommended)](#option-a-via-composer-autoload-recommended)
        - [Option B: As a Must-use Plugin (Last Resort)](#option-b-as-a-must-use-plugin-last-resort)
    - [Step 2](#step-2)
        - [Option A - Use Constants](#option-a---use-constants)
        - [Option B - Use Environment Variables](#option-b---use-environment-variables)
- [Usage](#usage)
    - [Pepper Migration](#pepper-migration)
    - [Argon2i Options](#argon2i-options)
- [Uninstallation](#uninstallation)
- [Frequently Asked Questions](#frequently-asked-questions)
    - [What have you done with the passwords?](#what-have-you-done-with-the-passwords)
    - [I have installed this plugin. Does it mean my WordPress site is *unhackable*?](#i-have-installed-this-plugin-does-it-mean-my-wordpress-site-is-unhackable)
    - [Did you reinvent the cryptographic functions?](#did-you-reinvent-the-cryptographic-functions)
    - [Pepper migration look great. Does it mean that I can keep as many pepper keys as I want?](#pepper-migration-look-great-does-it-mean-that-i-can-keep-as-many-pepper-keys-as-i-want)
    - [What if my pepper is compromised?](#what-if-my-pepper-is-compromised)
    - [Is pepper-ing perfect?](#is-pepper-ing-perfect)
    - [Is WordPress' phpass hasher or Bcrypt insecure?](#is-wordpress-phpass-hasher-or-bcrypt-insecure)
    - [Why use Argon2i over the others?](#why-use-argon2i-over-the-others)
    - [Does this plugin has 72-character limit like Bcrypt?](#does-this-plugin-has-72-character-limit-like-bcrypt)
    - [It looks awesome. Where can I find some more goodies like this?](#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-isnt-on-wporg-where-can-i-give-a-starstarstarstarstar-review)
    - [This plugin isn't on wp.org. Where can I make a complaint?](#this-plugin-isnt-on-wporg-where-can-i-make-a-complaint)
- [Alternatives](#alternatives)
- [Support!](#support)
    - [Donate](#donate)
    - [Why don't you hire me?](#why-dont-you-hire-me)
    - [Want to help in other way? Want to be a sponsor?](#want-to-help-in-other-way-want-to-be-a-sponsor)
- [Developing](#developing)
- [Feedback](#feedback)
- [Change Log](#change-log)
- [Security](#security)
- [Credits](#credits)
- [License](#license)

Goal
----

[](#goal)

Replace WordPress' [phpass](http://openwall.com/phpass) hasher with Argon2i hashing and SHA-512 HMAC.

Adopted from [Mozilla secure coding guidelines](https://wiki.mozilla.org/WebAppSec/Secure_Coding_Guidelines#Password_Storage):

- 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

Magic Moments
-------------

[](#magic-moments)

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](http://openwall.com/phpass) hasher
- upgrading from [WP Password Bcrypt](https://github.com/roots/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.

Requirements
------------

[](#requirements)

### Do Your Homework

[](#do-your-homework)

Don't blindly trust any random security guide/plugin on the scary internet - including this one!

Do your research:

- Read the whole [readme](./README.md)
- Read the [source code](./src)
- Compare with other [alternatives](#alternatives)

### PHP 7.2+ and compiled `--with-password-argon2`

[](#php-72-and-compiled---with-password-argon2)

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
    ```

Installation
------------

[](#installation)

### Step 0

[](#step-0)

Read the whole [readme](./README.md) and the [source code](./src) before going any further.

### Step 1

[](#step-1)

This plugin **should not** be installed as a normal WordPress plugin.

#### Option A: Via Composer Autoload (Recommended)

[](#option-a-via-composer-autoload-recommended)

```
➜ composer require typisttech/wp-password-argon-two
```

Note: Files in [`src`](./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)

[](#option-b-as-a-must-use-plugin-last-resort)

Manually copy [`wp-password-argon-two.php`](./wp-password-argon-two.php) and the whole [`src`](./src) directory into [`mu-plugins` folder](https://codex.wordpress.org/Must_Use_Plugins).

```
# 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
```

### Step 2

[](#step-2)

#### Option A - Use Constants

[](#option-a---use-constants)

Add 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', []);
```

#### Option B - Use Environment Variables

[](#option-b---use-environment-variables)

Defining the required constants in application code violates [12-factor principle](https://12factor.net/). The [`typisttech/wp-password-argon-two-env`](https://github.com/TypistTech/wp-password-argon-two-env) package allows you to configure with environment variables.

Recommended for all [Trellis](https://github.com/roots/trellis) users.

Usage
-----

[](#usage)

### Pepper Migration

[](#pepper-migration)

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`.

### Argon2i Options

[](#argon2i-options)

> 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](https://wiki.php.net/rfc/argon2_password_hash#discussion_issues)

You can adjust the options via `WP_PASSWORD_ARGON_TWO_OPTIONS`:

```
// Example
define('WP_PASSWORD_ARGON_TWO_OPTIONS', [
    'memory_cost' => 1 4,
    'threads'     => 3,
]);
```

Learn more about [available options](https://secure.php.net/manual/en/function.password-hash.php) and [picking appropriate options](https://stackoverflow.com/a/48322039).

Uninstallation
--------------

[](#uninstallation)

You have to regenerate all user passwords after uninstallation because we can't rehash without knowing the passwords in plain text.

Frequently Asked Questions
--------------------------

[](#frequently-asked-questions)

### What have you done with the passwords?

[](#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](./src)!

### I have installed this plugin. Does it mean my WordPress site is *unhackable*?

[](#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
- PHP
- this plugin
- all other WordPress themes and plugins
- everything on the server
- other security practices
- your mindset

### Did you reinvent the cryptographic functions?

[](#did-you-reinvent-the-cryptographic-functions)

Of course not! This plugin use PHP's native functions.

Repeat: Read the [source code](./src)!

### Pepper migration look great. Does it mean that I can keep as many pepper keys as I want?

[](#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?

[](#what-if-my-pepper-is-compromised)

1. Remove that pepper from `WP_PASSWORD_ARGON_TWO_PEPPER` and `WP_PASSWORD_ARGON_TWO_FALLBACK_PEPPERS`
2. Regenerate all user passwords

### Is pepper-ing perfect?

[](#is-pepper-ing-perfect)

No! Read [paragonie's explaination](https://paragonie.com/blog/2015/04/secure-authentication-php-with-long-term-persistence#pepper).

For those who can't stand with the drawbacks, use one of the [alternatives](#alternatives) instead.

### Is WordPress' phpass hasher or Bcrypt insecure?

[](#is-wordpress-phpass-hasher-or-bcrypt-insecure)

Both WordPress' [phpass](http://openwall.com/phpass) hasher and Bcrypt are secure. There is no emergent reason to upgrade.

Learn more about the [reasons](https://roots.io/wordpress-password-security-follow-up/) about not using WordPress' default.

### Why use Argon2i over the others?

[](#why-use-argon2i-over-the-others)

Argon2 password-based key derivation function is the winner of the [Password Hashing Competition](https://password-hashing.net) 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:

### Does this plugin has 72-character limit like Bcrypt?

[](#does-this-plugin-has-72-character-limit-like-bcrypt)

No. Read [the test](https://github.com/TypistTech/wp-password-argon-two/blob/6ec33700ab80e700045063895459212dd52b30b7/tests/wpunit/PasswordLockTest.php#L46-L57).

### It looks awesome. Where can I find some more goodies like this?

[](#it-looks-awesome-where-can-i-find-some-more-goodies-like-this)

- Articles on Typist Tech's [blog](https://typist.tech)
- [Tang Rufus' WordPress plugins](https://profiles.wordpress.org/tangrufus#content-plugins) on wp.org
- More projects on [Typist Tech's GitHub profile](https://github.com/TypistTech)
- Stay tuned on [Typist Tech's newsletter](https://typist.tech/go/newsletter)
- Follow [Tang Rufus' Twitter account](https://twitter.com/TangRufus)
- Hire [Tang Rufus](https://typist.tech/contact) to build your next awesome site

### This plugin isn't on wp.org. Where can I give a ⭐⭐⭐⭐⭐ review?

[](#this-plugin-isnt-on-wporg-where-can-i-give-a-starstarstarstarstar-review)

Thanks!

Consider writing a blog post, submitting pull requests, [donating](https://typist.tech/donation/) or [hiring me](https://typist.tech/contact/) instead.

### This plugin isn't on wp.org. Where can I make a complaint?

[](#this-plugin-isnt-on-wporg-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.

Alternatives
------------

[](#alternatives)

- [paragonie/halite](https://github.com/paragonie/halite/blob/55706ac843d8ee90426b455ea28673cf85e4a1e2/doc/Examples/01-passwords.php)
- [paragonie/password\_lock](https://github.com/paragonie/password_lock)
- [roots/wp-password-bcrypt](https://github.com/roots/wp-password-bcrypt)
- [PHP Native password hash](https://wordpress.org/plugins/password-hash/)

Support!
--------

[](#support)

### Donate

[](#donate)

Love WP Password Argon Two? Help me maintain it, a [donation here](https://typist.tech/donation/) can help with it.

### Why don't you hire me?

[](#why-dont-you-hire-me)

Ready to take freelance WordPress jobs. Contact me via the contact form [here](https://typist.tech/contact/) or, via email

### Want to help in other way? Want to be a sponsor?

[](#want-to-help-in-other-way-want-to-be-a-sponsor)

Contact: [Tang Rufus](mailto:tangrufus@gmail.com)

Developing
----------

[](#developing)

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
```

Feedback
--------

[](#feedback)

**Please provide feedback!** We want to make this library useful in as many projects as possible. Please submit an [issue](https://github.com/TypistTech/wp-password-argon-two/issues/new) and point out what you do and don't like, or fork the project and make suggestions. **No issue is too small.**

Change Log
----------

[](#change-log)

Please see [CHANGELOG](./CHANGELOG.md) for more information on what has changed recently.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

[WP Password Argon Two](https://github.com/TypistTech/wp-password-argon-two) is a [Typist Tech](https://typist.tech) project and maintained by [Tang Rufus](https://twitter.com/Tangrufus), freelance developer for [hire](https://typist.tech/contact/).

Full list of contributors can be found [here](https://github.com/TypistTech/wp-password-argon-two/graphs/contributors).

License
-------

[](#license)

The MIT License (MIT). Please see [License File](./LICENSE) for more information.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance25

Infrequent updates — may be unmaintained

Popularity23

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~525 days

Total

4

Last Release

1471d ago

PHP version history (2 changes)0.1.0PHP ^7.2

0.2.2PHP ^7.2 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/c1b05c8ed4ea3f68173555264d0226d5faeb7f315ed9df91890c351ef576ce72?d=identicon)[TangRufus](/maintainers/TangRufus)

---

Top Contributors

[![tangrufus](https://avatars.githubusercontent.com/u/2259834?v=4)](https://github.com/tangrufus "tangrufus (59 commits)")

---

Tags

argon2ihmac-sha512password-hashwordpresswordpress-pluginwordpresspasswordhashingwphmacargon2Argon2isha512

### Embed Badge

![Health badge](/badges/typisttech-wp-password-argon-two/health.svg)

```
[![Health](https://phpackages.com/badges/typisttech-wp-password-argon-two/health.svg)](https://phpackages.com/packages/typisttech-wp-password-argon-two)
```

###  Alternatives

[ircmaxell/password-compat

A compatibility library for the proposed simplified password hashing algorithm: https://wiki.php.net/rfc/password\_hash

2.1k58.1M129](/packages/ircmaxell-password-compat)[paragonie/halite

High-level cryptography interface powered by libsodium

1.2k10.6M84](/packages/paragonie-halite)[symfony/password-hasher

Provides password hashing utilities

817151.0M172](/packages/symfony-password-hasher)[mikemclin/laravel-wp-password

Laravel package that checks and creates WordPress password hashes

893.5M2](/packages/mikemclin-laravel-wp-password)[passwordlib/passwordlib

A Password Hashing Library

377223.2k7](/packages/passwordlib-passwordlib)[paragonie/password_lock

Wraps Bcrypt-SHA2 in Authenticated Encryption

19351.8k1](/packages/paragonie-password-lock)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)