This is an old revision of the document!

PHP RFC: Argon2 Password Hash Enhancements


This RFC seeks to enhance the functionality initially introduced in http://wiki.php.net/rfc/argon2_password_hash through the addition of Argon2id as a hashing algorithm to supersede Argon2i, and other enhancements.

Overview of Argon2 and Argon2id specific algorithm

Argon2 has one primary variant: Argon2id, and two supplementary variants: Argon2d and Argon2i. Argon2d uses data-depending memory access, which makes it suitable for cryptocurrencies and proof-of-work applications with no threats from side-channel timing attacks. Argon2i uses data-independent memory access, which is preferred for password hashing and password-based key derivation. Argon2id works as Argon2i for the first half of the first iteration over the memory, and as Argon2d for the rest, thus providing both side-channel attack protection and brute-force cost savings due to time-memory tradeoffs. Argon2i makes more passes over the memory to protect from tradeoff attacks.

Argon2id is now the recommended Argon2 variant to use in the ITEF draft spec.


The existing password_* functions provided a forward compatible, simplified interface for hashing passwords. This RFC proposes the implementation of Argon2id within the password_* functions for use as a secure alternative to the originally proposed Argon2i.

Proposed PHP Version(s)

PHP NEXT (PHP 7.x ⇒ 7.3)

New Constants

This change introduces a new hashing algorithm constant:


Changes to password_hash()

The password_hash() function is altered to accept either PASSWORD_ARGON2ID as the algorithm.

// Argon2id with default cost factors
password_hash('password', PASSWORD_ARGON2ID);

Behaviorally, this implementation will act identical to the Argon2i implementation in that it will accept the same cost variables introduces in the Argon2i RFC.

// Argon2id by name with custom cost factors
password_hash('password', PASSWORD_ARGON2ID, ['memory_cost' => 1<<17, 'time_cost' => 4, 'threads' => 2]);

No additional changes to this method are anticipated.

Changes to password_verify()

The password_verify() function is altered return true or false if an Argon2id hash is specified. There are no API level changes to this function.

Changes to password_get_info()

The password_get_info() function is altered to accept Argon2id hashes, and to return information about a given Argon2 hash.

array(3) {
  string(7) "argon2id"
  array(3) {

Changes to password_needs_rehash()

The password_needs_rehash() function is altered to accept Argon2id hashes. If any of the cost factors are changed for an Argon2id hash, this function will return true.

$hash = password_hash('password', PASSWORD_ARGON2ID);
password_needs_rehash($hash, PASSWORD_ARGON2ID); // false
password_needs_rehash($hash, PASSWORD_ARGON2ID, ['memory_cost' => 1<<17]); // true

Backward Incompatible Changes


Discussion Issues

Why was Argon2id not included in the original RFC?

The original Argon2i password_hash RFC https://wiki.php.net/rfc/argon2_password_hash was created before Argon2id draft spec was complete or made available. Argon2id was not introduced into the reference library until after the original RFC was voted on, approved, and merged into PHP 7.2 (20161029). To avoid a re-vote and re-implementation of the merge request Argon2id was not included in the original RFC.

That being said, a late addition to the implementation include support for reference library 20161029 since to changed the argon2_encoded() method. This change was made due to uncertainty about what reference library implementation would land in Debian/RHEL, and to ensure forward compatibility with the 20161029 library version if that was the version that would land in Debian/RHEL.

Proposed Voting Choices

Vote YES to include Argon2id as an alternative to Argon2i within the password_* functions in 7.3. A 50%+1 majority should be sufficient.

Voting will be open for 2 weeks.

Patches and Tests




  1. 2018-01-11: 0.1 Initial RFC draft
rfc/argon2_password_hash_enhancements.1515686731.txt.gz · Last modified: 2018/01/11 16:05 by charlesportwoodii