rfc:password_registry

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:password_registry [2018/10/15 18:24] – Add get_info callback pollitarfc:password_registry [2018/12/25 13:07] (current) – This RFC has already been implemented cmb
Line 1: Line 1:
-====== PHP RFC: Your Title Here ====== +====== PHP RFC: Password Hashing Registry ====== 
-  * Version: 0.1+  * Version: 1.0
   * Date: 2018-10-15   * Date: 2018-10-15
   * Author: Sara Golemon, pollita@php.net   * Author: Sara Golemon, pollita@php.net
-  * Status: Draft+  * Status: Implemented (PHP 7.4)
   * First Published at: http://wiki.php.net/rfc/password_registry   * First Published at: http://wiki.php.net/rfc/password_registry
  
Line 27: Line 27:
     };     };
  
-    PHPAPI zend_long php_password_algo_register(php_password_algo* algo); +    PHPAPI int php_password_algo_register(const char* ident, const php_password_algo*); 
-    PHPAPI php_password_algo* php_password_algo_find(zend_long algo_id); +    PHPAPI void php_password_algo_unregister(const char* ident); 
-    PHPAPI zend_long php_password_algo_identify(const zend_string* hash); +    PHPAPI const php_password_algo* php_password_algo_default(); 
-    PHPAPI void php_password_algo_unregister(zend_long algo_id);+    PHPAPI zend_string *php_password_algo_extract_ident(const zend_string* hash); 
 +    PHPAPI const php_password_algo* php_password_algo_find(const zend_string* ident); 
 +    PHPAPI const php_password_algo* php_password_algo_get_named(const zend_string* name); 
 +    PHPAPI php_password_algo* php_password_algo_identify(const zend_string* hash);
          
-Extensions wishing to provide an algorithm implementation will setup a (typically global const) structure to contain the four method pointers and call **php_password_algo_register()** during MINIT to hook in.  The integer value returned by this function will be a process unique integer value which the extension may assign to a constant or leave to discovery via //password_algos()//.+Extensions wishing to provide an algorithm implementation will setup a (typically global const) structure to contain the four method pointers and call **php_password_algo_register()** during MINIT to hook in.
  
 The **hash**, **verify**, and **needs_rehash** method pointers function exactly as their PHP userspace functions describe, but don't require an algo ID, as this has already been determined by the exported functions in looking up the algorithm. The **hash**, **verify**, and **needs_rehash** method pointers function exactly as their PHP userspace functions describe, but don't require an algo ID, as this has already been determined by the exported functions in looking up the algorithm.
Line 38: Line 41:
 The **get_info** method pointer allows adding entries to an array return value for the password_get_info() userspace command.  This function must return SUCCESS or FAILURE. The **get_info** method pointer allows adding entries to an array return value for the password_get_info() userspace command.  This function must return SUCCESS or FAILURE.
  
-The **valid** method pointer is the mechanism used for determining what algorithm handler is appropriate for a given hash string.  For example, only the **bcrypt** handler should return true for a hash string beginning with "$2y$".+The **valid** method pointer is the mechanism used for determining what algorithm handler is appropriate for a given hash string.  For example, only the **bcrypt** handler should return true for a hash string beginning with "$2y$".  This callback may be NULL if the name alone is sufficient to identify an algorithm.  For example, the bcrypt algorithm has a length check in addition to its name identifier.
  
-In order to fail-closed, if more than one algorithm returns true for **valid()**, then ALL implementations must pass their corresponding verify() test in order for the password to be considered valid.  This is considered an undesirable use-caseand implementations attempting to hijack a password hashing mechanism must explicitly make the decision to disable the previous handler in order to override behavior.+Because the registry is organized as an associative arrayany attempt to re-register an already present password mechanism will result in a failure.
  
 ====== Userspace API ====== ====== Userspace API ======
  
-An additional function, password_algos(), will be added to return a complete list of all registered password hashing algorithms as a numerically indexed array.  The key of this array will be the process-unique algorithm identifier, while the value element will be the human readable name for the algo.  For example:+An additional function, password_algos(), will be added to return a complete list of all registered password hashing algorithms as a vector.  The value element will be the human hash identity which may or may not correspond to the human readable name for the algo.  For example:
  
     > print_r(password_algos());     > print_r(password_algos());
     Array (     Array (
-        [1] => "bcrypt" +        [0] => "2y" // Ident for "bcrypt" 
-        [2] => "argon2i" +        [1] => "argon2i" 
-        [3] => "argon2id"+        [2] => "argon2id"
     )     )
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
-Algorithm numeric identifiers are no longer fixed values which can't change between installations.  Applications MUST use the constant or symbolic name when specifying algorithms rather than hard code the numeric value for the algo.+Algorithm identifiers are now (nullable) strings rather than numbers.  Applications correctly using the constants such as PASSWORD_DEFAULT, PASSWORD_BCRYPT, etc... will continue to function correctly. 
 + 
 +Note that PASSWORD_DEFAULT === null. 
 + 
 +====== Minimizing impact to BC ====== 
 + 
 +In order to minimize the impact of the above BC. we could overload the **password_hash()** and **password_needs_rehash()** methods to accept integer values 0, 1, 2, and 3 to function as aliases for DEFAULT, BCRYPT, ARGIN2I, and ARGON2ID, respectively.   Using an int would therefore work, but would produce a deprecation warning.  This is being presented as a separate vote below.
  
 ===== Extension Changes ===== ===== Extension Changes =====
Line 61: Line 70:
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
 7.next 7.next
- 
-===== Open Questions ===== 
-  * Should the registry support password hashing mechanisms defined in script code? (I don't think so, but feel free to disagree) 
  
 ===== Future Scope ===== ===== Future Scope =====
-Review ext/sodium to see if there are additional password hashing algorithms it may be appropriate to enable.+  * Review ext/sodium to see if there are additional password hashing algorithms it may be appropriate to enable
 +  * Consider exposing the registry to script code for the purpose of polyfill libraries.
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
 Simple 50% +1, make the password hashing system extensible via internal-only registry. Simple 50% +1, make the password hashing system extensible via internal-only registry.
 +
 +<doodle title="Make the password hashing system extensible via internal-only registry?" auth="pollita" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
 +
 +
 +Should the above poll pass, the following 50%+1 question asks if we should additionally provide the overloaded behavior described above in "minimizing impact to BC".
 +
 +<doodle title="Support integer constants 0-3 to password_hash() et. al. for BC" auth="pollita" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
 +
 +
 +Vote Open: 2018-11-06 17:00 UTC
 +
 +Vote Closes: 2018-11-20 17:00 UTC
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
-To be written.+ 
 +Work in progress... 
 + 
 +  * https://github.com/php/php-src/pull/3609
  
 ===== Implementation ===== ===== Implementation =====
-To be written.+ 
 +  - Implementation: <http://git.php.net/?p=php-src.git;a=commit;h=534df87c9e3c28001986e70844e0ad04e5708d3d> 
 +  - Documentation: to be done.
  
rfc/password_registry.txt · Last modified: 2018/12/25 13:07 by cmb