rfc:argon2_password_hash
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
rfc:argon2_password_hash [2016/08/01 15:56] – charlesportwoodii | rfc:argon2_password_hash [2017/09/22 13:28] – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== PHP RFC: Argon2 Password Hash ====== | ====== PHP RFC: Argon2 Password Hash ====== | ||
- | * Version: 0.4 | + | * 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 ===== | ||
- | The existing password_* functions provided a forward compatible, simplified interface for hashing passwords. This RFC proposes the implementation | + | The existing password_* functions provided a forward compatible, simplified interface for hashing passwords. This RFC proposes the implementation |
==== Proposed PHP Version(s) ==== | ==== Proposed PHP Version(s) ==== | ||
- | Add Argon2 | + | Add Argon2i |
==== New Constants ==== | ==== New Constants ==== | ||
- | This change introduces | + | This change introduces |
<code php> | <code php> | ||
PASSWORD_ARGON2I | PASSWORD_ARGON2I | ||
- | PASSWORD_ARGON2D | ||
- | </ | ||
- | |||
- | Similar to how PASSWORD_DEFAULT is an alias to PASSWORD_BCRYPT, | ||
- | <code php> | ||
- | PASSWORD_ARGON2 | ||
</ | </ | ||
Line 45: | 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 | + | The password_hash() function is altered to accept |
<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(' |
- | + | ||
- | // Argon2d by name with custom cost factors | + | |
- | password_hash(' | + | |
</ | </ | ||
Line 68: | 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 97: | Line 92: | ||
[" | [" | ||
array(3) { | array(3) { | ||
- | ["m_cost" | + | ["memory_cost" |
int(65536) | int(65536) | ||
- | ["t_cost" | + | ["time_cost" |
int(3) | int(3) | ||
[" | [" | ||
Line 108: | 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, |
</ | </ | ||
==== Configure Flag ==== | ==== Configure Flag ==== | ||
- | Argon2 support is provided by passing --with-argon2[=DIR] to the configure script. A directory to the Argon2 build directory may be provided. If not provided, the library will search the OS for libargon2. If --with-argon2 is provided, configuration will fail if Argon2 cannot be found. | + | Argon2 support is provided by passing --with-password-argon2[=DIR] to the configure script. A directory to the Argon2 build directory may be provided. If not provided, the library will search the OS for libargon2. If --with-password-argon2 is provided, configuration will fail if Argon2 cannot be found. |
Windows deps should be updated to include a statically compile Argon2Ref.lib from the Argon2 reference library for proper linking. | Windows deps should be updated to include a statically compile Argon2Ref.lib from the Argon2 reference library for proper linking. | ||
Line 124: | Line 119: | ||
None. | None. | ||
- | ===== Open Issues ===== | + | ===== Discussion |
+ | |||
+ | 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: | ||
+ | |||
+ | < | ||
+ | memory_cost = 1 MiB | ||
+ | time_cost = 2 | ||
+ | threads = 2 | ||
+ | </ | ||
+ | |||
+ | 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, | ||
+ | |||
+ | - 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 ==== | ||
+ | |||
+ | 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, | ||
+ | |||
+ | PASSWORD_ARGON2I is the only algorithm necessary for implementation purposes. | ||
+ | |||
+ | ==== [Resolved] Inclusion of Argon2d ==== | ||
+ | |||
+ | Argon2i is suitable for password hashing. While Argon2d has other uses, it is not suitable for password hashing. A recommendation is to remove Argon2d to keep the feature in line with the intent of password_hash being a simple hashing function. | ||
+ | |||
+ | The password_* functions should be strictly related to password hashing behaviors, and their scope should not extend to general hashing. Consequently this RFC now only proposes the implementation of Argon2i within password_*. Argon2d will not be implemented as it is not suitable for password hashing, despite how simple it would be to include it within the password_* functions. | ||
+ | |||
+ | ==== [Resolved] Configure Flag ==== | ||
+ | |||
+ | A discussion on internals proposes --with-password-argon2 is more suitable than --with-argon2 as this is a sub-feature rather than a full feature implementation of the entire Argon2 library. | ||
+ | |||
+ | --with-argon2 implies full inclusion of the Argon2 library. Since only Argon2i is implemented within password_*, the configure argument should reflect that. | ||
+ | |||
+ | ==== [Resolved] Inclusion on 7.4 ==== | ||
+ | |||
+ | Per discussion on the internals mailing list during an initial vote, this RFC no longer proposes changes to PASSWORD_DEFAULT in 7.4. | ||
==== [Resolved] Availability of libargon2 ==== | ==== [Resolved] Availability of libargon2 ==== | ||
Line 130: | Line 177: | ||
libargon2 is not yet wildly available in package managers yet. Any implementation in PHP will require manual compilation of the library. Per the discussion on https:// | libargon2 is not yet wildly available in package managers yet. Any implementation in PHP will require manual compilation of the library. Per the discussion on https:// | ||
- | If PHP is not compiled with --with-argon2, | + | If PHP is not compiled with --with-password-argon2, use of the features outlined in this RFC will not be available. |
===== Proposed Voting Choices ===== | ===== Proposed Voting Choices ===== | ||
- | Vote YES to include Argon2 as an alternative to Bcrypt within the password_* functions in 7.2, and to make PASSWORD_ARGON2 the default password hashing algorithm in 7.4. A 50%+1 majority should be sufficient. | ||
- | Voting will be open for 1 week. | + | Vote YES to include Argon2 as an alternative to Bcrypt within the password_* functions in 7.2. A 50%+1 majority should be sufficient. |
- | <doodle title=" | + | Voting will be open for 2 weeks. |
+ | |||
+ | <doodle title=" | ||
* Yes | * Yes | ||
* No | * No | ||
Line 144: | 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 169: | Line 216: | ||
- 2016-07-18: 0.3 Discussion opened | - 2016-07-18: 0.3 Discussion opened | ||
- 2016-08-01: 0.4 Voting opened | - 2016-08-01: 0.4 Voting opened | ||
+ | - 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-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.txt · Last modified: 2018/03/01 23:27 by carusogabriel