rfc:argon2_password_hash_enhancements

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
rfc:argon2_password_hash_enhancements [2018/01/17 17:30] charlesportwoodiirfc:argon2_password_hash_enhancements [2018/10/10 11:17] (current) – typo: IETF neufeind
Line 1: Line 1:
 ====== PHP RFC: Argon2 Password Hash Enhancements ====== ====== PHP RFC: Argon2 Password Hash Enhancements ======
-  * Version: 0.1+  * Version: 0.2
   * Date: 2018-01-11   * Date: 2018-01-11
   * Author: Charles R. Portwood II <charlesportwoodii@erianna.com>   * Author: Charles R. Portwood II <charlesportwoodii@erianna.com>
-  * Status: Draft+  * Status: Implemented (PHP 7.3)
   * First Published at: http://wiki.php.net/rfc/argon2_password_hash_enhancements   * First Published at: http://wiki.php.net/rfc/argon2_password_hash_enhancements
  
Line 14: Line 14:
  
  
-Argon2id is now the recommended Argon2 variant to use in the ITEF draft spec.+Argon2id is now the recommended Argon2 variant to use in the IETF draft spec.
  
 ===== Proposal ===== ===== Proposal =====
Line 81: Line 81:
 password_needs_rehash($hash, PASSWORD_ARGON2ID, ['memory_cost' => 1<<17]); // true password_needs_rehash($hash, PASSWORD_ARGON2ID, ['memory_cost' => 1<<17]); // true
 </code> </code>
 +
 +===== Configure/m4 Changes =====
 +
 +Argon2id is only available in reference library >= 20161029. As a result of this change, the --with-password-argon2[=dir] option will include support for both Argon2i and Argon2id. Configure will fail if libargon2 is < 20161029.
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 87: Line 91:
 ===== Discussion Issues ===== ===== Discussion Issues =====
  
-==== Why was Argon2id not included in the original RFC? ====+==== Why was Argon2id not included in the original RFC? [CLOSED] ====
  
 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. When the original RFC was introduced, only Argon2i and Argon2d existed. 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. When the original RFC was introduced, only Argon2i and Argon2d existed.
Line 95: Line 99:
 That being said, a late addition to the implementation include support for reference library 20161029 since it changed the argon2_encoded() method. This change was made due to uncertainty about what reference library implementation would land in Debian Stretch/RHEL, and to ensure forward compatibility with the 20161029 library version if that was the version that would land in Debian/RHEL. That being said, a late addition to the implementation include support for reference library 20161029 since it changed the argon2_encoded() method. This change was made due to uncertainty about what reference library implementation would land in Debian Stretch/RHEL, and to ensure forward compatibility with the 20161029 library version if that was the version that would land in Debian/RHEL.
  
-==== Should we deprecate Argon2i? ====+==== Should we deprecate Argon2i? [RESOLVED] ====
  
 No, I do not believe we should deprecate Argon2i from password_*. Argon2i remains a perfectly secure and reasonable choice for password hashing. Argon2id simply provides better resistance to some form of attacks at the cost of time-memory tradeoffs. Argon2id is recommended at this point simply because it provides a blend of Argon2i and Argon2d. The existence of Argon2id does not negate the benefits of Argon2i. No, I do not believe we should deprecate Argon2i from password_*. Argon2i remains a perfectly secure and reasonable choice for password hashing. Argon2id simply provides better resistance to some form of attacks at the cost of time-memory tradeoffs. Argon2id is recommended at this point simply because it provides a blend of Argon2i and Argon2d. The existence of Argon2id does not negate the benefits of Argon2i.
  
-==== Add Secret Parameter? ====+==== Add Secret Parameter? [RESOLVED] ====
  
 Argon2 exposes via the _ctx API (which currently isn't used by this implementation) a way to inject a separate secret key, which can be used to further strength the resulting Argon2 hashes. Argon2 exposes via the _ctx API (which currently isn't used by this implementation) a way to inject a separate secret key, which can be used to further strength the resulting Argon2 hashes.
  
-There has been some discussion of this both within bugs.php.net (https://bugs.php.net/bug.php?id=753880) and within the reference library (https://github.com/P-H-C/phc-winner-argon2/issues/222).+There has been some discussion of this both within bugs.php.net (https://bugs.php.net/bug.php?id=75388) and within the reference library (https://github.com/P-H-C/phc-winner-argon2/issues/222).
  
 I do not feel including the secret parameter within the password_hashing API is appropriate for the following reasons: I do not feel including the secret parameter within the password_hashing API is appropriate for the following reasons:
Line 110: Line 114:
   - More complex behaviors are available in Libsodium (which is now a core PHP extension).   - More complex behaviors are available in Libsodium (which is now a core PHP extension).
  
-==== Custom Salt Value? ====+==== Custom Salt Value? [RESOLVED] ====
  
 The salt option was deprecated from password_hash in 7.0. I do not feel it is appropriate to re-introduce it again. Moreover, the addition of a custom salt attribute was rejected in the original Argon2i RFC. The salt option was deprecated from password_hash in 7.0. I do not feel it is appropriate to re-introduce it again. Moreover, the addition of a custom salt attribute was rejected in the original Argon2i RFC.
  
-==== Configuring // Support for Argon2 >= 20161029 ====+==== Configuring // Support for Argon2 >= 20161029 [RESOLVED] ====
  
 Argon2id is only available in reference library >= 20161029.  Argon2id is only available in reference library >= 20161029. 
Line 122: Line 126:
 PHP already knows if Argon2id is available when compiling PHP. As Argon2id is a //new// algorithm however, we need to decide how --with-password-argon2[=DIR] should behave. Should it include both Argon2i and Argon2id? Should we force a minimum reference library version? Or should we introduce a new configure flag for this new function? PHP already knows if Argon2id is available when compiling PHP. As Argon2id is a //new// algorithm however, we need to decide how --with-password-argon2[=DIR] should behave. Should it include both Argon2i and Argon2id? Should we force a minimum reference library version? Or should we introduce a new configure flag for this new function?
  
-=== Force lib >= 20161029, making --with-password-argon2 flag is inclusive of both Argon2i and Argon2id ===+This RFC proposes the first option, of forcing lib >= 20161029 during the configure stage making the --with-password-argon2 flag inclusive of both Argon2i and Argon2id. 
 + 
 +=== Force lib >= 20161029, making the --with-password-argon2 flag inclusive of both Argon2i and Argon2id [RESOLVED] ===
  
 In this scenario we would force the library version to be >= 20161029. From configure, –with-password-argon2[=DIR] m4 would fail if Argon2id wasn't available, and prompt the user to upgrade their library version. The existing implementation already performs a check for the availability of Argon2id due to ABI differences with argon2_encoded() in different library version. In this scenario we would force the library version to be >= 20161029. From configure, –with-password-argon2[=DIR] m4 would fail if Argon2id wasn't available, and prompt the user to upgrade their library version. The existing implementation already performs a check for the availability of Argon2id due to ABI differences with argon2_encoded() in different library version.
  
-This change would be the easiest, and most forward thinking since Argon2id is the recommended ietf algorithm. Additionally it would ensure that PHP stays up to date with the reference library. +This change would be the easiest, and most forward thinking since Argon2id is the recommended ITEF algorithm. Additionally it would ensure that PHP stays up to date with the reference library. 
  
 This would require users on Stretch however to manually compile and upgrade to lib >= 20161029. The affect on Windows users is minimal as we're already providing ref/lib's for Windows compilation. Buster (testing) and Sid (unstable) are scheduled with 20161029. This would require users on Stretch however to manually compile and upgrade to lib >= 20161029. The affect on Windows users is minimal as we're already providing ref/lib's for Windows compilation. Buster (testing) and Sid (unstable) are scheduled with 20161029.
Line 134: Line 140:
 This is my recommended approach as it forces us to be conscious to changes in the Argon2 reference library. This is my recommended approach as it forces us to be conscious to changes in the Argon2 reference library.
  
-=== Allow --with-password-argon2[=DIR] to conditionally enable Argon2id based upon what's available in the library version. ===+=== Allow --with-password-argon2[=DIR] to conditionally enable Argon2id based upon what's available in the library version. [RESOLVED] ===
  
 As m4 already knows if Argon2id is available in the lib, the functionality in PHP would be enabled for Argon2id if and only if Argon2id was available in the library.  As m4 already knows if Argon2id is available in the lib, the functionality in PHP would be enabled for Argon2id if and only if Argon2id was available in the library. 
  
-This approach is offered as a fallback incase option (1) is not selected. The greatest failings with this option are that userland checks would need to be performed for PASSWORD_ARGON2I and PASSWORD_ARGON2ID to determine what is actually available. Disabling certain features based upon a library version muddles what was actually available since phpinfo() doesn't report the compiled library version. Between the userland checks and the inability to easily identify what features are actually available likely disqualify this option.+This approach is offered as a fallback in case option (1) is not selected. The greatest failings with this option are that user land checks would need to be performed for PASSWORD_ARGON2I and PASSWORD_ARGON2ID to determine what is actually available. Disabling certain features based upon a library version muddles what was actually available since phpinfo() doesn't report the compiled library version. Between the user land checks and the inability to easily identify what features are actually available likely disqualify this option.
  
-=== Introduce a new configure argument --with-password-argon2id ===+This RFC does not propose this option.
  
-A third, less desirable solution would be to explicitly use a new configure flag --with-password-argon2id, and run the Argon2id checks only if this flag is declared. This flag would be in addition to --with-password-argon2. This behavior is award however. As a end user I would expected --with-password-argon2 is inclusive of any valid Argon2 algorithm. Moreover as the --with-password-argon2 check already determines if Argon2id is available, it may introduce more complexity than desired in the implementation. This is more visible than option (2) but still suffers from the same core problems.+=== Introduce a new configure argument --with-password-argon2id [RESOLVED] ===
  
 +A third, less desirable solution would be to explicitly use a new configure flag --with-password-argon2id, and run the Argon2id checks only if this flag is declared. This flag would be in addition to --with-password-argon2.  As a end user I would expected --with-password-argon2 to be inclusive of any Argon2 algorithm. Moreover as the --with-password-argon2 check already determines if Argon2id is available, it may introduce more complexity than desired in the implementation. This is more visible than option (2) but still suffers from the same core problems.
 +
 +This RFC does not propose this option.
  
 ===== Proposed Voting Choices ===== ===== 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.+Vote YES to include Argon2id as an alternative to Argon2i within the password_* functions in 7.3.
  
-Voting will be open for 2 weeks.+A 50%+1 majority should be sufficient. 
 + 
 +<doodle title="argon2_password_hash_enhancements" auth="charlesportwoodii" voteType="single" closed="true"> 
 +   * Yes 
 +   * No 
 +</doodle> 
 + 
 + 
 +Voting will be from 6/6/2018 to 6/18/2018.
  
 ===== Implementation ===== ===== Implementation =====
Line 157: Line 174:
   - https://github.com/php/php-src/compare/master...charlesportwoodii:argon2_password_hash_enhancements?expand=1   - https://github.com/php/php-src/compare/master...charlesportwoodii:argon2_password_hash_enhancements?expand=1
  
 +===== Implementation =====
 +
 +  - Github Merge Request: https://github.com/php/php-src/pull/3311
 +  - Merged into PHP: https://github.com/php/php-src/commit/55277a668409b9d62ac42695934aca64e354869f
 + 
 ===== References ===== ===== References =====
  
Line 169: Line 191:
  
   - 2018-01-11: 0.1 Initial RFC draft   - 2018-01-11: 0.1 Initial RFC draft
 +  - 2018-02-01: Opened discussion to internals
 +  - 2018-05-22: Re-submitted to internals for discussion
 +  - 2018-06-06: Opened for Vote
 +  - 2018-06-19: Accepted
 +  - 2018-06-21: Implemented
rfc/argon2_password_hash_enhancements.1516210215.txt.gz · Last modified: 2018/01/17 17:30 by charlesportwoodii