system system.base system.caching system.caching.dependencies system.collections system.console system.db system.db.ar system.db.schema system.db.schema.cubrid system.db.schema.mssql system.db.schema.mysql system.db.schema.oci system.db.schema.pgsql system.db.schema.sqlite system.gii system.i18n system.i18n.gettext system.logging system.test system.utils system.validators system.web system.web.actions system.web.auth system.web.filters system.web.form system.web.helpers system.web.renderers system.web.services system.web.widgets system.web.widgets.captcha system.web.widgets.pagers zii.behaviors zii.widgets zii.widgets.grid zii.widgets.jui

CPasswordHelper

system.utils
继承 class CPasswordHelper
可用自 1.1.14
源码 framework/utils/CPasswordHelper.php
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 when run in an environment that does not have crypt() with its Blowfish option and $2y hash fix. Compatible system is:

(1) Most *nix systems since PHP 4 (the algorithm is part of the library function crypt(3)); (2) Any PHP since 5.3.7 or PHP with the Suhosin patch including $2y fix backported. Note that Debian's 5.3.3 is not supported.

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

公共方法

隐藏继承的方法

方法描述被定义在
generateSalt() Generates a salt that can be used to generate a password hash. CPasswordHelper
hashPassword() Generate a secure hash from a password and a random salt. CPasswordHelper
same() Check for sameness of two strings using an algorithm with timing CPasswordHelper
verifyPassword() Verify a password against a hash. CPasswordHelper

受保护的方法

隐藏继承的方法

方法描述被定义在
checkBlowfish() Check for availability of PHP crypt() with the Blowfish hash option. CPasswordHelper

方法详情

checkBlowfish() 方法
protected static void checkBlowfish()
源码: framework/utils/CPasswordHelper.php#61 (显示)
protected static function checkBlowfish()
{
    if(!
function_exists('crypt'))
        throw new 
CException(Yii::t('yii','{class} requires the PHP crypt() function. This system does not have it.',
            array(
'{class}'=>__CLASS__)));

    if(!
defined('CRYPT_BLOWFISH') || !CRYPT_BLOWFISH)
        throw new 
CException(Yii::t('yii',
            
'{class} requires the Blowfish option of the PHP crypt() function. This system does not have it.',
            array(
'{class}'=>__CLASS__)));
}

Check for availability of PHP crypt() with the Blowfish hash option.

generateSalt() 方法
public static string generateSalt(int $cost=13)
$cost int Cost parameter used by the Blowfish hash algorithm.
{return} string the random salt value.
源码: framework/utils/CPasswordHelper.php#181 (显示)
public static function generateSalt($cost=13)
{
    if(!
is_numeric($cost))
        throw new 
CException(Yii::t('yii','{class}::$cost must be a number.',array('{class}'=>__CLASS__)));

    
$cost=(int)$cost;
    if(
$cost<|| $cost>31)
        throw new 
CException(Yii::t('yii','{class}::$cost must be between 4 and 31.',array('{class}'=>__CLASS__)));

    if((
$random=Yii::app()->getSecurityManager()->generateRandomString(22,true))===false)
        if((
$random=Yii::app()->getSecurityManager()->generateRandomString(22,false))===false)
            throw new 
CException(Yii::t('yii','Unable to generate random string.'));
    return 
sprintf('$2y$%02d$',$cost).strtr($random,array('_'=>'.','~'=>'/'));
}

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".

hashPassword() 方法
public static string hashPassword(string $password, int $cost=13)
$password string The password to be hashed.
$cost int 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.
{return} string The password hash string, always 60 ASCII characters.
源码: framework/utils/CPasswordHelper.php#92 (显示)
public static function hashPassword($password,$cost=13)
{
    
self::checkBlowfish();
    
$salt=self::generateSalt($cost);
    
$hash=crypt($password,$salt);

    if(!
is_string($hash) || (function_exists('mb_strlen') ? mb_strlen($hash'8bit') : strlen($hash))<32)
        throw new 
CException(Yii::t('yii','Internal error while generating hash.'));

    return 
$hash;
}

Generate a secure hash from a password and a random salt.

Uses the PHP crypt() built-in function with the Blowfish hash option.

same() 方法
public static bool same(string $a, string $b)
$a string First subject string to compare.
$b string Second subject string to compare.
{return} bool true if the strings are the same, false if they are different or if either is not a string.
源码: framework/utils/CPasswordHelper.php#150 (显示)
public static function same($a,$b)
{
    if(!
is_string($a) || !is_string($b))
        return 
false;

    
$mb=function_exists('mb_strlen');
    
$length=$mb mb_strlen($a,'8bit') : strlen($a);
    if(
$length!==($mb mb_strlen($b,'8bit') : strlen($b)))
        return 
false;

    
$check=0;
    for(
$i=0;$i<$length;$i+=1)
        
$check|=(ord($a[$i])^ord($b[$i]));

    return 
$check===0;
}

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.

verifyPassword() 方法
public static bool verifyPassword(string $password, string $hash)
$password string The password to verify. If password is empty or not a string, method will return false.
$hash string The hash to verify the password against.
{return} bool True if the password matches the hash.
源码: framework/utils/CPasswordHelper.php#112 (显示)
public static function verifyPassword($password$hash)
{
    
self::checkBlowfish();
    if(!
is_string($password) || $password==='')
        return 
false;

    if (!
$password || !preg_match('{^\$2[axy]\$(\d\d)\$[\./0-9A-Za-z]{22}}',$hash,$matches) ||
        
$matches[1]<|| $matches[1]>31)
        return 
false;

    
$test=crypt($password,$hash);
    if(!
is_string($test) || strlen($test)<32)
        return 
false;

    return 
self::same($test$hash);
}

Verify a password against a hash.