From 95f6764aef0aaf5b99cb692de6783831b2431226 Mon Sep 17 00:00:00 2001 From: Anthony Ferrara Date: Fri, 21 Jun 2013 11:57:00 +0000 Subject: [PATCH] Update more information about the options, restructuring the location and detail of the supported options. Additionally, refactor the needs rehash and get info documentation slightly. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330608 c90b9560-bf6c-de11-be94-00142212c4b1 --- language-snippets.ent | 2 +- reference/password/constants.xml | 49 +++++++++++++++++-- .../password/functions/password-get-info.xml | 27 +++++++--- .../password/functions/password-hash.xml | 20 ++++++++ .../functions/password-needs-rehash.xml | 11 ++--- 5 files changed, 90 insertions(+), 19 deletions(-) diff --git a/language-snippets.ent b/language-snippets.ent index ffae0736aa..75330fd86b 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -531,7 +531,7 @@ connAn MCVE_CONN resource returned by password_hash.'> -salt, to provide a salt to use when hashing the password, and cost, which denotes the algorithmic cost that should be used. Examples of these values can be found on the crypt page.'> +An associative array containing options. See the password algorithm constants for documentation on the supported options for each algorithm.'> diff --git a/reference/password/constants.xml b/reference/password/constants.xml index 6564fd5e43..577c51ec3a 100644 --- a/reference/password/constants.xml +++ b/reference/password/constants.xml @@ -13,10 +13,34 @@ (integer) - + PASSWORD_BCRYPT is used to create new password hashes using the CRYPT_BLOWFISH algorithm. - + + + This will always result in a hash using the "$2y$" crypt format, + which is always 60 characters wide. + + + Supported Options: + + + + + salt - to manually provide a salt to use when hashing the password. + Note that this will override and prevent a salt from being automatically generated. + + + If omitted, a random salt will be generated by password_hash for + each password hashed. This is the intended mode of operation. + + + + + cost - which denotes the algorithmic cost that should be used. Examples of these values can be found on the crypt page. + + + @@ -25,11 +49,28 @@ (integer) - + The default algorithm to use for hashing if no algorithm is provided. This may change in newer PHP releases when newer, stronger hashing algorithms are supported. - + + + It is worth noting that over time this constant can (and likely will) + change. Therefore you should be aware that the length of the resulting + hash can change. Therefore, if you use PASSWORD_DEFAULT + you should store the resulting hash in a way that can store more than 60 + characters (255 is the recomended width). + + + Values for this constant: + + + + + PHP 5.5.0 - PASSWORD_BCRYPT + + + diff --git a/reference/password/functions/password-get-info.xml b/reference/password/functions/password-get-info.xml index 57829c690b..36093e1725 100644 --- a/reference/password/functions/password-get-info.xml +++ b/reference/password/functions/password-get-info.xml @@ -37,12 +37,27 @@ &reftitle.returnvalues; - Returns an associative array with three elements: algo, - which will match a - password algorithm constant; - algoName, which has the human readable name of the - algorithm; and options, which includes the options - provided when calling password_hash. + Returns an associative array with three elements: + + + + algo, which will match a + password algorithm constant + + + + + algoName, which has the human readable name of the + algorithm + + + + + options, which includes the options + provided when calling password_hash + + + diff --git a/reference/password/functions/password-hash.xml b/reference/password/functions/password-hash.xml index 4f80989e61..b60ade8b2e 100644 --- a/reference/password/functions/password-hash.xml +++ b/reference/password/functions/password-hash.xml @@ -39,6 +39,26 @@ create the hash. This will produce a standard crypt compatible hash using the "$2y$" identifier. The result will always be a 60 character string, &return.falseforfailure;. + + Supported Options: + + + + + salt - to manually provide a salt to use when hashing the password. + Note that this will override and prevent a salt from being automatically generated. + + + If omitted, a random salt will be generated by password_hash for + each password hashed. This is the intended mode of operation. + + + + + cost - which denotes the algorithmic cost that should be used. Examples of these values can be found on the crypt page. + + + diff --git a/reference/password/functions/password-needs-rehash.xml b/reference/password/functions/password-needs-rehash.xml index 510c325197..184ba80007 100644 --- a/reference/password/functions/password-needs-rehash.xml +++ b/reference/password/functions/password-needs-rehash.xml @@ -12,8 +12,8 @@ booleanpassword_needs_rehash stringhash - integeralgo - arrayoptions + stringalgo + stringoptions This function checks to see if the supplied hash implements the algorithm @@ -44,12 +44,7 @@ options - - &password.parameter.options; - - - If omitted, the default cost will be used. - + &password.parameter.options;