Skip to content

Commit

Permalink
Cleanup and standardize hash module documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@rchouinard
rchouinard committed Jul 20, 2012
1 parent 83a0501 commit 4ae5628
Show file tree
Hide file tree
Showing 6 changed files with 86 additions and 149 deletions.
69 changes: 4 additions & 65 deletions src/PHPassLib/Hash.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,21 +65,6 @@ interface Hash
/**
* Generate a config string suitable for use with module hashes.
*
* <code>
* &lt;?php
* use PHPassLib\Hash\BCrypt;
*
* // Generate a config string using the default settings.
* $config = BCrypt::genConfig();
*
* // Generate a config string with custom options.
* $config = BCrypt::genConfig(array (
* 'rounds' => 16, // Use 16 rounds instead of the default 12.
* ));
* </code>
*
* @see Hash::genHash()
* @see Hash::hash()
* @param array $config Array of configuration options.
* @return string Configuration string.
* @throws InvalidArgumentException Throws an InvalidArgumentException if
Expand All @@ -90,74 +75,28 @@ public static function genConfig(array $config = array ());
/**
* Generate a hash using a pre-defined config string.
*
* <code>
* &lt;?php
* use PHPassLib\Hash\BCrypt;
*
* // Calculate the hash value of the string "password."
* $config = BCrypt::genConfig();
* $hash = BCrypt::genHash('password', $config);
* </code>
*
* @see Hash::genConfig()
* @see Hash::hash()
* @param string $password Password string.
* @param string $config Configuration string.
* @return string Returns a hashed string on success, otherwise an error
* string (either *0 or *1) is returned.
* @return string Returns the hash string on success. On failure, one of
* *0 or *1 is returned.
*/
public static function genHash($password, $config);

/**
* Generate a hash using either a pre-defined config string or an array.
*
* <code>
* &lt;?php
* use PHPassLib\Hash\BCrypt;
*
* // Calculate a hash using the default options.
* $hash = BCrypt::hash('password');
*
* // Calculate a hash using custom options.
* $hash = BCrypt::hash('password', array (
* 'rounds' => 16, // Use 16 rounds instead of the default 12.
* ));
*
* // Calculate a hash using a pre-defined config string.
* $config = BCrypt::genconfig();
* $hash = BCrypt::hash('password', $config);
* </code>
*
* @see Hash::genConfig()
* @see Hash::genHash()
* @param string $password Password string.
* @param string|array $config Optional config string or array of options.
* @return string Returns a hashed string on success, otherwise an error
* string (either *0 or *1) is returned.
* @return string Returns the hash string on success. On failure, one of
* *0 or *1 is returned.
*/
public static function hash($password, $config = array ());

/**
* Verify a password against a hash string.
*
* <code>
* &lt;?php
* use PHPassLib\Hash\BCrypt;
*
* // Assume password comes from a login form.
* $password = $_POST['password'];
*
* // Hash should really come from your persistent storage.
* $hash = BCrypt::hash('password');
*
* // Check if the user's password matches the stored hash.
* if (BCrypt::verify($password, $hash)) {
* // Password matches! Authenticate the user...
* } else {
* // Password is wrong! Log the attempt and continue...
* }
* </code>
*
* @param string $password Password string.
* @param string $hash Hash string.
* @return boolean Returns true if the password matches, false otherwise.
Expand Down
21 changes: 6 additions & 15 deletions src/PHPassLib/Hash/BCrypt.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,22 +46,10 @@ class BCrypt implements Hash
{

/**
* Generate a config string suitable for use with bcrypt hashes.
*
* Available options:
* - ident: Hash identifier to use. PHP versions <5.3.7 must use 2a,
* while versions >=5.3.8 may use 2a, 2y, or 2x. Defaults to 2a.
* - rounds: Cost parameter which will be encoded as a zero-padded
* two-digit number. This value is logarithmic, so the number of
* iterations will be determined as 2^<rounds>. Must be between 4 and
* 31, defaults to 12.
* - salt: If provided, must be a 22-character string containing only
* characters from ./0-9A-Za-z. It is recommended to omit this option
* and let the class generate one for you.
* Generate a config string suitable for use with module hashes.
*
* @param array $config Array of configuration options.
* @return string Configuration string in the format
* "$<ident>$<rounds>$<salt>".
* @return string Configuration string.
* @throws InvalidArgumentException Throws an InvalidArgumentException if
* any passed-in configuration options are invalid.
*/
Expand Down Expand Up @@ -102,9 +90,12 @@ public static function genHash($password, $config)
/**
* Generate a hash using either a pre-defined config string or an array.
*
* @see Hash::genConfig()
* @see Hash::genHash()
* @param string $password Password string.
* @param string|array $config Optional config string or array of options.
* @return string Encoded password hash.
* @return string Returns the hash string on success. On failure, one of
* *0 or *1 is returned.
*/
public static function hash($password, $config = array ())
{
Expand Down
19 changes: 9 additions & 10 deletions src/PHPassLib/Hash/BSDiCrypt.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,15 +44,8 @@ class BSDiCrypt implements Hash
/**
* Generate a config string suitable for use with module hashes.
*
* Available options:
* - rounds: Must be between 1 and 16777215. Defaults to 5001.
* - salt: If provided, must be a 2-character string containing only
* characters from ./0-9A-Za-z. It is recommended to omit this option
* and let the class generate one for you.
*
* @param array $config Array of configuration options.
* @return string Configuration string in the format
* "_<rounds><salt><checksum>".
* @return string Configuration string.
* @throws InvalidArgumentException Throws an InvalidArgumentException if
* any passed-in configuration options are invalid.
*/
Expand All @@ -65,13 +58,16 @@ public static function genConfig(array $config = array ())
$config = array_merge($defaults, array_change_key_case($config, CASE_LOWER));

$string = '*1';
if (self::validateOptions($config)) {
try {
self::validateOptions($config);
// Rounds needs to be odd in order to avoid exposing wek DES keys
if (($config['rounds'] % 2) == 0) {
--$config['rounds'];
}

$string = sprintf('_%s%s', Utilities::encodeInt24($config['rounds']), $config['salt']);
} catch (InvalidArgumentException $e) {
trigger_error($e->getMessage(), E_USER_WARNING);
}

return $string;
Expand All @@ -98,9 +94,12 @@ public static function genHash($password, $config)
/**
* Generate a hash using either a pre-defined config string or an array.
*
* @see Hash::genConfig()
* @see Hash::genHash()
* @param string $password Password string.
* @param string|array $config Optional config string or array of options.
* @return string Encoded password hash.
* @return string Returns the hash string on success. On failure, one of
* *0 or *1 is returned.
*/
public static function hash($password, $config = array ())
{
Expand Down
24 changes: 12 additions & 12 deletions src/PHPassLib/Hash/DESCrypt.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,14 +43,8 @@ class DESCrypt implements Hash
/**
* Generate a config string suitable for use with module hashes.
*
* Available options:
* - salt: If provided, must be a 2-character string containing only
* characters from ./0-9A-Za-z. It is recommended to omit this option
* and let the class generate one for you.
*
* @param array $config Array of configuration options.
* @return string Configuration string in the format
* "<salt><checksum>".
* @return string Configuration string.
* @throws InvalidArgumentException Throws an InvalidArgumentException if
* any passed-in configuration options are invalid.
*/
Expand All @@ -61,12 +55,15 @@ public static function genConfig(array $config = array ())
);
$config = array_merge($defaults, array_change_key_case($config, CASE_LOWER));

$value = '*1';
if (self::validateOptions($config)) {
$value = $config['salt'];
$string = '*1';
try {
self::validateOptions($config);
$string = $config['salt'];
} catch (InvalidArgumentException $e) {
trigger_error($e->getMessage(), E_USER_WARNING);
}

return $value;
return $string;
}

/**
Expand All @@ -90,9 +87,12 @@ public static function genHash($password, $config)
/**
* Generate a hash using either a pre-defined config string or an array.
*
* @see Hash::genConfig()
* @see Hash::genHash()
* @param string $password Password string.
* @param string|array $config Optional config string or array of options.
* @return string Encoded password hash.
* @return string Returns the hash string on success. On failure, one of
* *0 or *1 is returned.
*/
public static function hash($password, $config = array ())
{
Expand Down
27 changes: 14 additions & 13 deletions src/PHPassLib/Hash/MD5Crypt.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,16 +47,10 @@ class MD5Crypt implements Hash
{

/**
* Generate a config string suitable for use with md5crypt hashes.
*
* Available options:
* - salt: Salt string which must be between 0 and 8 characters
* in length, using characters in the range ./0-9A-Za-z. If none is
* given, a valid salt value will be generated.
* Generate a config string suitable for use with module hashes.
*
* @param array $config Array of configuration options.
* @return string Configuration string in the format
* "$1$<salt>$".
* @return string Configuration string.
* @throws InvalidArgumentException Throws an InvalidArgumentException if
* any passed-in configuration options are invalid.
*/
Expand All @@ -67,11 +61,15 @@ public static function genConfig(array $config = array ())
);
$config = array_merge($defaults, array_change_key_case($config, CASE_LOWER));

if (self::validateOptions($config)) {
return sprintf('$1$%s$', $config['salt']);
} else {
return '*1';
$string = '*1';
try {
self::validateOptions($config);
$string = sprintf('$1$%s$', $config['salt']);
} catch (InvalidArgumentException $e) {
trigger_error($e->getMessage(), E_USER_WARNING);
}

return $string;
}

/**
Expand All @@ -95,9 +93,12 @@ public static function genHash($password, $config)
/**
* Generate a hash using either a pre-defined config string or an array.
*
* @see Hash::genConfig()
* @see Hash::genHash()
* @param string $password Password string.
* @param string|array $config Optional config string or array of options.
* @return string Encoded password hash.
* @return string Returns the hash string on success. On failure, one of
* *0 or *1 is returned.
*/
public static function hash($password, $config = array ())
{
Expand Down
Loading

0 comments on commit 4ae5628

Please sign in to comment.