Class CPasswordHelper
CPasswordHelper provides a simple API for secure password hashing and
verification.
CPasswordHelper uses the Blowfish hash algorithm available in many PHP
runtime environments through the PHP crypt() built-in function. As of Dec 2012 it is the strongest algorithm
available in PHP and the only algorithm without some security concerns
surrounding it. For this reason, CPasswordHelper fails to initialize when run in
and environment that does not have crypt() and its Blowfish option. Systems with
the option include: (1) Most *nix systems since PHP 4 (the algorithm is part of
the library function crypt(3)); (2) All PHP systems since 5.3.0; (3) All PHP
systems with the Suhosin patch. For more information about password hashing, crypt() and
Blowfish, please read the Yii Wiki article Use crypt() for password storage. and the PHP RFC Adding simple password hashing API.
CPasswordHelper throws an exception if the Blowfish hash algorithm is not
available in the runtime PHP's crypt() function. It can be used as follows
Generate a hash from a password:
$hash = CPasswordHelper::hashPassword($password);
This hash can be stored in a database (e.g. CHAR(60) CHARACTER SET latin1).
The hash is usually generated and saved to the database when the user enters a
new password. But it can also be useful to generate and save a hash after
validating a user's password in order to change the cost or refresh the
salt.
To verify a password, fetch the user's saved hash from the database (into
$hash) and:
if (CPasswordHelper::verifyPassword($password, $hash))
// password is good
else
// password is bad
Methods summary
protected static
|
#
checkBlowfish( )
Check for availability of PHP crypt() with the Blowfish hash option.
Check for availability of PHP crypt() with the Blowfish hash option.
Throws
CExceptionif the runtime system does not have PHP crypt() or its Blowfish hash option.
|
public static
string
|
#
hashPassword( string $password, integer $cost = 13 )
Generate a secure hash from a password and a random salt.
Generate a secure hash from a password and a random salt.
Uses the PHP crypt() built-in function with the Blowfish hash option.
Parameters
- $password
string
$password The password to be hashed.- $cost
integer
$cost Cost parameter used by the Blowfish hash algorithm. The higher the value
of cost, the longer it takes to generate the hash and to verify a password
against it. Higher cost therefore slows down a brute-force attack. For best
protection against brute for attacks, set it to the highest value that is
tolerable on production servers. The time taken to compute the hash doubles for
every increment by one of $cost. So, for example, if the hash takes 1 second to
compute when $cost is 14 then then the compute time varies as 2^($cost - 14)
seconds. Returns
string
The password hash string, always 60 ASCII characters.
Throws
CExceptionon bad password parameter or if crypt() with Blowfish hash is not available.
|
public static
boolean
|
#
verifyPassword( string $password, string $hash )
Verify a password against a hash.
Verify a password against a hash.
Parameters
- $password
string
$password The password to verify. If password is empty or not a string, method
will return false.- $hash
string
$hash The hash to verify the password against. Returns
boolean
True if the password matches the hash.
Throws
CExceptionon bad password or hash parameters or if crypt() with Blowfish hash is not
available.
|
public static
boolean
|
#
same( string $a, string $b )
Check for sameness of two strings using an algorithm with timing independent
of the string values if the subject strings are of equal length.
Check for sameness of two strings using an algorithm with timing independent
of the string values if the subject strings are of equal length.
The function can be useful to prevent timing attacks. For example, if $a and
$b are both hash values from the same algorithm, then the timing of this
function does not reveal whether or not there is a match.
NOTE: timing is affected if $a and $b are different lengths or either is not
a string. For the purpose of checking password hash this does not reveal
information useful to an attacker.
Parameters
- $a
string
$a First subject string to compare.- $b
string
$b Second subject string to compare. Returns
boolean
true if the strings are the same, false if they are different or if either is
not a string.
See
|
public static
string
|
#
generateSalt( integer $cost = 13 )
Generates a salt that can be used to generate a password hash.
Generates a salt that can be used to generate a password hash.
The PHP crypt() built-in function requires, for the Blowfish hash algorithm, a salt
string in a specific format: "$2y$" (in which the "y" may be replaced by "a" or
"y" see PHP manual for details), a two digit cost parameter, "$", 22 characters
from the alphabet "./0-9A-Za-z".
Parameters
- $cost
integer
$cost Cost parameter used by the Blowfish hash algorithm. Returns
string
the random salt value.
Throws
|