Differences

This shows you the differences between two versions of the page.

--- rfc:argon2_password_hash [2016/08/05 12:29] – Re-opened for voting charlesportwoodii
+++ rfc:argon2_password_hash [2018/03/01 23:27] (current) – RFC was implemented in PHP 7.2 carusogabriel
@@ Line 1: / Line 1: @@
 ====== PHP RFC: Argon2 Password Hash ======
-  * Version: 0.6
+  * Version: 0.8
   * Date: 2016-07-10
   * Author: Charles R. Portwood II <charlesportwoodii@erianna.com>
-  * Status: Voting
+  * Status: Implemented (in PHP 7.2)
   * First Published at: http://wiki.php.net/rfc/argon2_password_hash
@@ Line 13: / Line 13: @@
   - And a parallelism factor, which defines the number of parallel threads
-Argon2 comes in two distinct flavors, Argon2i and Argon2d. Argon2i which is optimized for password hashing and password based key derivation. Argon2 is faster and uses data-dependent memory access, making it highly resistant against GPU cracking attacks and suitable for applications with no threats from side-channel timing attacks (such as cryptocurrencies).
+Argon2 comes in two distinct flavors, Argon2i and Argon2d. Argon2i which is optimized for password hashing and password based key derivation. Argon2d is faster and uses data-dependent memory access, making it highly resistant against GPU cracking attacks and suitable for applications with no threats from side-channel timing attacks (such as cryptocurrencies).
 ===== Proposal =====
@@ Line 25: / Line 25: @@
 <code php>
 PASSWORD_ARGON2I
-</code>
-Similar to how PASSWORD_DEFAULT is an alias to PASSWORD_BCRYPT, a separate alias, PASSWORD_ARGON2 is introduced as an alias to PASSWORD_ARGON2I to simplify user land selection of the Argon2 hashing algorithm.
-<code php>
-PASSWORD_ARGON2
 </code>
@@ Line 44: / Line 39: @@
 <code>
-m_cost = 64 Mib
+memory_cost = 1024 KiB
-t_cost = 3
+time_cost = 2
-threads = 1
+threads = 2
 </code>
+All three values are integers. The memory cost represents the number of KiB that should be consumed during hashing. The default value is 1<<10, or 1024 KiB, or 1 MiB. The argon2 spec recommends setting the memory cost to a power of 2 when changing.
+The time cost represents the number of times the hash algorithm will be run. And the thread parameter indicates the number of CPU threads that will be used during hashing.
 ==== Changes to password_hash() ====
-The password_hash() function is altered to accept either PASSWORD_ARGON2 or PASSWORD_ARGON2I as the algorithm, and accept the memory cost, time cost, and parallelism degree as options. When using Argon2. The following examples illustrate the new functionality.
+The password_hash() function is altered to accept either PASSWORD_ARGON2I as the algorithm, and accept the memory cost, time cost, and parallelism degree as options. When using Argon2. The following examples illustrate the new functionality.
 <code php>
 // Argon2i with default cost factors
-password_hash('password', PASSWORD_ARGON2);
+password_hash('password', PASSWORD_ARGON2I);
 // Argon2i by name with custom cost factors
-password_hash('password', PASSWORD_ARGON2I, ['m_cost' => 1<<17, 't_cost' => 4, 'threads' => 2]);
+password_hash('password', PASSWORD_ARGON2I, ['memory_cost' => 1<<17, 'time_cost' => 4, 'threads' => 2]);
 </code>
@@ Line 64: / Line 63: @@
 <code php>
 $options = [
-    'm_cost' => PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
+    'memory_cost' => PASSWORD_ARGON2_DEFAULT_MEMORY_COST,
-    't_cost' => PASSWORD_ARGON2_DEFAULT_TIME_COST,
+    'time_cost' => PASSWORD_ARGON2_DEFAULT_TIME_COST,
     'threads' => PASSWORD_ARGON2_DEFAULT_THREADS
 ];
@@ Line 93: / Line 92: @@
   ["options"]=>
   array(3) {
-    ["m_cost"]=>
+    ["memory_cost"]=>
     int(65536)
-    ["t_cost"]=>
+    ["time_cost"]=>
     int(3)
     ["threads"]=>
@@ Line 104: / Line 103: @@
 ==== Changes to password_needs_rehash() ====
-The password_get_info() function is altered to accept Argon2 hashes. If any of the cost factors are changed for an Argon2 hash, this function will return true.
+The password_needs_rehash() function is altered to accept Argon2 hashes. If any of the cost factors are changed for an Argon2 hash, this function will return true.
 <code php>
-$hash = password_hash('password', PASSWORD_ARGON2);
+$hash = password_hash('password', PASSWORD_ARGON2I);
-password_needs_rehash($hash, PASSWORD_ARGON2); // false
+password_needs_rehash($hash, PASSWORD_ARGON2I); // false
-password_needs_rehash($hash, PASSWORD_ARGON2, ['m_cost' => 1<<17]); // true
+password_needs_rehash($hash, PASSWORD_ARGON2I, ['memory_cost' => 1<<17]); // true
 </code>
@@ Line 120: / Line 119: @@
 None.
-===== Open Issues =====
+===== Discussion Issues =====
+All issues in this section have been resolved. The primary discussion points and resolutions are outlined.
+==== [Resolved] Cost factors ====
+This library initially proposed higher cost factors, but now proposes the following cost factors:
+<code>
+memory_cost = 1 MiB
+time_cost = 2
+threads = 2
+</code>
+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. The following list outlines hashing performance on various systems using these default cost values.
+  - Common Cloud Server 512 MB, 1 Core: 3-5 ms
+  - Common Cloud Server 2 GB, 2 Core, 1-3 ms
+  - 512 MB Raspberry Pi Zero: 75-85ms
+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.
+==== [Resolved] m_cost, t_costs vs memory_cost, time_cost ====
+The reference material uses m_cost and t_cost. End users might find it easier to use memory_cost and time_cost. The cost variables have been changed to the latter to simplify cost selection for the end user.
+==== [Resolved] Providing default options ====
+Providing default options allows for ease of use, and encourages use. Not providing options encourages experimentation on your system, but discourages use from people unfamiliar with the algorithm.
+Default options must be provided to ensure compatibility with the password_* functions.
+==== [Resolved] PASSWORD_ARGON2 or PASSWORD_ARGON2I ====
+The library exposes PASSWORD_ARGON2I, and PASSWORD_ARGON2 as an alias to PASSWORD_ARGON2I. As only Argon2i is made available, two constants is unnecessary.
+PASSWORD_ARGON2I is the only algorithm necessary for implementation purposes.
 ==== [Resolved] Inclusion of Argon2d ====
@@ Line 148: / Line 183: @@
 Vote YES to include Argon2 as an alternative to Bcrypt within the password_* functions in 7.2. A 50%+1 majority should be sufficient.
-Voting will be open for 1 week.
+Voting will be open for 2 weeks.
-<doodle title="argon2_password_hash_revote" auth="charlesportwoodii" voteType="single" closed="false">
+<doodle title="argon2_password_hash_revote" auth="charlesportwoodii" voteType="single" closed="true">
    * Yes
    * No
@@ Line 157: / Line 192: @@
 ===== Patches and Tests =====
-A working patch is available at: https://github.com/php/php-src/pull/1997
+A working patch against the latest version of the Argon2 reference library is available at: https://github.com/php/php-src/pull/1997
 ===== Implementation =====
-After the project is implemented, this section should contain
+  - Merged in 7.2
-  - the version(s) it was merged to
+  - Commit: https://github.com/php/php-src/commit/35a74b9e4a9b5812c0e3a5524e28ff7dec50f1dc
-  - a link to the git commit(s)
   - a link to the PHP manual entry for the feature
@@ Line 184: / Line 218: @@
   - 2016-08-01: 0.5 Voting closes due to issue with RFC, removing 7.4 and adding new issues brought up during vote
   - 2016-08-01: 0.6 Removing Argon2 from password_*, changing configure flag to --with-password-argon2 for clarity of scope
-  - 2016-08-05: 0.6 Voting re-opened
+  - 2016-08-18: 0.7 Adding clarity on new cost factors
+  - 2016-08-24: 0.8 Voting re-opened
+  - 2016-09-08: 0.8 RFC accepted, voting closed

Differences

Page Tools