rfc:argon2_password_hash
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
rfc:argon2_password_hash [2016/08/05 14:56] – Adding more issues open during RFC re-discussion 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 ====== | ====== PHP RFC: Argon2 Password Hash ====== | ||
- | * Version: 0.6 | + | * Version: 0.8 |
* Date: 2016-07-10 | * Date: 2016-07-10 | ||
* Author: Charles R. Portwood II < | * Author: Charles R. Portwood II < | ||
- | * Status: | + | * Status: |
* First Published at: http:// | * First Published at: http:// | ||
Line 13: | Line 13: | ||
- And a parallelism factor, which defines the number of parallel threads | - 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 comes in two distinct flavors, Argon2i and Argon2d. Argon2i which is optimized for password hashing and password based key derivation. |
===== Proposal ===== | ===== Proposal ===== | ||
Line 25: | Line 25: | ||
<code php> | <code php> | ||
PASSWORD_ARGON2I | PASSWORD_ARGON2I | ||
- | </ | ||
- | |||
- | Similar to how PASSWORD_DEFAULT is an alias to PASSWORD_BCRYPT, | ||
- | <code php> | ||
- | PASSWORD_ARGON2 | ||
</ | </ | ||
Line 44: | Line 39: | ||
< | < | ||
- | m_cost | + | memory_cost |
- | t_cost | + | time_cost |
- | threads = 1 | + | threads = 2 |
</ | </ | ||
+ | |||
+ | All three values are integers. The memory cost represents the number of KiB that should be consumed during hashing. The default value is 1<< | ||
+ | |||
+ | 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() ==== | ==== Changes to password_hash() ==== | ||
- | The password_hash() function is altered to accept either | + | 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> | <code php> | ||
// Argon2i with default cost factors | // Argon2i with default cost factors | ||
- | password_hash(' | + | password_hash(' |
// Argon2i by name with custom cost factors | // Argon2i by name with custom cost factors | ||
- | password_hash(' | + | password_hash(' |
</ | </ | ||
Line 64: | Line 63: | ||
<code php> | <code php> | ||
$options = [ | $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, |
' | ' | ||
]; | ]; | ||
Line 93: | Line 92: | ||
[" | [" | ||
array(3) { | array(3) { | ||
- | ["m_cost" | + | ["memory_cost" |
int(65536) | int(65536) | ||
- | ["t_cost" | + | ["time_cost" |
int(3) | int(3) | ||
[" | [" | ||
Line 104: | Line 103: | ||
==== Changes to password_needs_rehash() ==== | ==== 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> | <code php> | ||
- | $hash = password_hash(' | + | $hash = password_hash(' |
- | password_needs_rehash($hash, | + | password_needs_rehash($hash, |
- | password_needs_rehash($hash, | + | password_needs_rehash($hash, |
</ | </ | ||
Line 120: | Line 119: | ||
None. | None. | ||
- | ===== Open Issues ===== | + | ===== Discussion |
- | ==== Cost options ==== | + | All issues in this section have been resolved. The primary discussion points and resolutions are outlined. |
- | The current | + | ==== [Resolved] Cost factors ==== |
+ | |||
+ | This library initially proposed higher | ||
< | < | ||
- | m_cost | + | memory_cost |
- | t_cost | + | time_cost |
- | threads = 1 | + | threads = 2 |
</ | </ | ||
- | While the spec outlines there are no " | + | Due to the variety of platforms PHP runs on, the cost factors |
- | ==== Providing default options ==== | + | - 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' | ||
+ | |||
+ | ==== [Resolved] m_cost, t_costs vs memory_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 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. | 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. | ||
- | ==== PASSWORD_ARGON2 or PASSWORD_ARGON2I ==== | + | Default options must be provided to ensure compatibility with the password_* functions. |
+ | |||
+ | ==== [Resolved] | ||
The library exposes PASSWORD_ARGON2I, | The library exposes PASSWORD_ARGON2I, | ||
+ | |||
+ | PASSWORD_ARGON2I is the only algorithm necessary for implementation purposes. | ||
==== [Resolved] Inclusion of Argon2d ==== | ==== [Resolved] Inclusion of Argon2d ==== | ||
Line 168: | 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. | 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=" | + | <doodle title=" |
* Yes | * Yes | ||
* No | * No | ||
Line 177: | Line 192: | ||
===== Patches and Tests ===== | ===== Patches and Tests ===== | ||
- | A working patch is available at: https:// | + | A working patch against the latest version of the Argon2 reference library |
===== Implementation ===== | ===== Implementation ===== | ||
- | After the project is implemented, | + | - Merged in 7.2 |
- | - the version(s) it was merged to | + | - Commit: https:// |
- | | + | |
- a link to the PHP manual entry for the feature | - a link to the PHP manual entry for the feature | ||
Line 204: | 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.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-01: 0.6 Removing Argon2 from password_*, changing configure flag to --with-password-argon2 for clarity of scope | ||
+ | - 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 |
rfc/argon2_password_hash.1470408973.txt.gz · Last modified: 2017/09/22 13:28 (external edit)