CSecurityManager
CSecurityManager provides private keys, hashing and encryption functions.
CSecurityManager is used by Yii components and applications for security-related purpose. For example, it is used in cookie validation feature to prevent cookie data from being tampered.
CSecurityManager is mainly used to protect data from being tampered and viewed. It can generate HMAC and encrypt the data. The private key used to generate HMAC is set by
ValidationKey. The key used to encrypt data is specified by
EncryptionKey. If the above keys are not explicitly set, random keys will be generated and used.
To protected data with HMAC, call
hashData(); and to check if the data is tampered, call
validateData(), which will return the real data if it is not tampered. The algorithm used to generated HMAC is specified by
validation.
To encrypt and decrypt data, call
encrypt() and
decrypt() respectively, which uses 3DES encryption algorithm. Note, the PHP Mcrypt extension must be installed and loaded.
CSecurityManager is a core application component that can be accessed via
CApplication::getSecurityManager().
Property Details
public mixed $cryptAlgorithm;
the name of the crypt algorithm to be used by encrypt and decrypt. This will be passed as the first parameter to mcrypt_module_open.
This property can also be configured as an array. In this case, the array elements will be passed in order as parameters to mcrypt_module_open. For example, array('rijndael-128', '', 'ofb', '')
.
Defaults to AES
Note: MCRYPT_RIJNDAEL_192 and MCRYPT_RIJNDAEL_256 are *not* AES-192 and AES-256. The numbers of the MCRYPT_RIJNDAEL constants refer to the block size, whereas the numbers of the AES variants refer to the key length. AES is Rijndael with a block size of 128 bits and a key length of 128 bits, 192 bits or 256 bits. So to use AES in Mcrypt, you need MCRYPT_RIJNDAEL_128 and a key with 16 bytes (AES-128), 24 bytes (AES-192) or 32 bytes (AES-256). The other two Rijndael variants in Mcrypt should be avoided, because they're not standardized and have been analyzed much less than AES.
public string getEncryptionKey()
public void setEncryptionKey(string $value)
the private key used to encrypt/decrypt data. If the key is not explicitly set, a random one is generated and returned.
protected static array $encryptionKeyMinimumLengths;
known minimum lengths per encryption algorithm
public string $hashAlgorithm;
the name of the hashing algorithm to be used by computeHMAC. See hash-algos for the list of possible hash algorithms. Note that if you are using PHP 5.1.1 or below, you can only use 'sha1' or 'md5'.
Defaults to 'sha1', meaning using SHA1 hash algorithm.
public boolean $validateEncryptionKey;
if encryption key should be validated
public string getValidation()
public void setValidation(string $value)
This method has been deprecated since version 1.1.3. Please use hashAlgorithm instead.
public string getValidationKey()
public void setValidationKey(string $value)
the private key used to generate HMAC. If the key is not explicitly set, a random one is generated and returned.
Method Details
public boolean compareString(string $expected, string $actual) |
$expected | string | string to compare. |
$actual | string | user-supplied string. |
{return} | boolean | whether strings are equal. |
Source Code: framework/base/CSecurityManager.php#606 (
show)
public function compareString($expected,$actual)
{
$expected.="\0";
$actual.="\0";
$expectedLength=$this->strlen($expected);
$actualLength=$this->strlen($actual);
$diff=$expectedLength-$actualLength;
for($i=0;$i<$actualLength;$i++)
$diff|=(ord($actual[$i])^ord($expected[$i%$expectedLength]));
return $diff===0;
}
Performs string comparison using timing attack resistant approach.
public string computeHMAC(string $data, string|null $key=NULL, string|null $hashAlgorithm=NULL) |
$data | string | data to be generated HMAC. |
$key | string|null | the private key to be used for generating HMAC. Defaults to null, meaning using validationKey value. |
$hashAlgorithm | string|null | the name of the hashing algorithm to be used. See hash-algos for the list of possible hash algorithms. Note that if you are using PHP 5.1.1 or below, you can only use 'sha1' or 'md5'. Defaults to null, meaning using hashAlgorithm value. |
{return} | string | the HMAC for the data. |
Source Code: framework/base/CSecurityManager.php#327 (
show)
public function computeHMAC($data,$key=null,$hashAlgorithm=null)
{
if($key===null)
$key=$this->getValidationKey();
if($hashAlgorithm===null)
$hashAlgorithm=$this->hashAlgorithm;
if(function_exists('hash_hmac'))
return hash_hmac($hashAlgorithm,$data,$key);
if(0===strcasecmp($hashAlgorithm,'sha1'))
{
$pack='H40';
$func='sha1';
}
elseif(0===strcasecmp($hashAlgorithm,'md5'))
{
$pack='H32';
$func='md5';
}
else
{
throw new CException(Yii::t('yii','Only SHA1 and MD5 hashing algorithms are supported when using PHP 5.1.1 or below.'));
}
if($this->strlen($key)>64)
$key=pack($pack,$func($key));
if($this->strlen($key)<64)
$key=str_pad($key,64,chr(0));
$key=$this->substr($key,0,64);
return $func((str_repeat(chr(0x5C), 64) ^ $key) . pack($pack, $func((str_repeat(chr(0x36), 64) ^ $key) . $data)));
}
Computes the HMAC for the data with validationKey. This method has been made public since 1.1.14.
public string decrypt(string $data, string $key=NULL) |
$data | string | data to be decrypted. |
$key | string | the decryption key. This defaults to null, meaning using EncryptionKey. |
{return} | string | the decrypted data |
Source Code: framework/base/CSecurityManager.php#240 (
show)
public function decrypt($data,$key=null)
{
if($key===null)
$key=$this->getEncryptionKey();
$this->validateEncryptionKey($key);
$module=$this->openCryptModule();
$ivSize=@mcrypt_enc_get_iv_size($module);
$iv=$this->substr($data,0,$ivSize);
@mcrypt_generic_init($module,$key,$iv);
$decrypted=@mdecrypt_generic($module,$this->substr($data,$ivSize,$this->strlen($data)));
@mcrypt_generic_deinit($module);
@mcrypt_module_close($module);
return rtrim($decrypted,"\0");
}
Decrypts data
public string encrypt(string $data, string $key=NULL) |
$data | string | data to be encrypted. |
$key | string | the decryption key. This defaults to null, meaning using EncryptionKey. |
{return} | string | the encrypted data |
Source Code: framework/base/CSecurityManager.php#218 (
show)
public function encrypt($data,$key=null)
{
if($key===null)
$key=$this->getEncryptionKey();
$this->validateEncryptionKey($key);
$module=$this->openCryptModule();
srand();
$iv=@mcrypt_create_iv(mcrypt_enc_get_iv_size($module), MCRYPT_RAND);
@mcrypt_generic_init($module,$key,$iv);
$encrypted=$iv.@mcrypt_generic($module,$data);
@mcrypt_generic_deinit($module);
@mcrypt_module_close($module);
return $encrypted;
}
Encrypts data.
generatePseudoRandomBlock()
public string generatePseudoRandomBlock() |
{return} | string | of 64 pseudo random bytes. |
Source Code: framework/base/CSecurityManager.php#440 (
show)
public function generatePseudoRandomBlock()
{
$bytes='';
if (function_exists('openssl_random_pseudo_bytes')
&& ($bytes=openssl_random_pseudo_bytes(512))!==false
&& $this->strlen($bytes)>=512)
{
return $this->substr($bytes,0,512);
}
for($i=0;$i<32;++$i)
$bytes.=pack('S',mt_rand(0,0xffff));
// On UNIX and UNIX-like operating systems the numerical values in `ps`, `uptime` and `iostat`
// ought to be fairly unpredictable. Gather the non-zero digits from those.
foreach(array('ps','uptime','iostat') as $command) {
@exec($command,$commandResult,$retVal);
if(is_array($commandResult) && !empty($commandResult) && $retVal==0)
$bytes.=preg_replace('/[^1-9]/','',implode('',$commandResult));
}
// Gather the current time's microsecond part. Note: this is only a source of entropy on
// the first call! If multiple calls are made, the entropy is only as much as the
// randomness in the time between calls.
$bytes.=$this->substr(microtime(),2,6);
// Concatenate everything gathered, mix it with sha512. hash() is part of PHP core and
// enabled by default but it can be disabled at compile time but we ignore that possibility here.
return hash('sha512',$bytes,true);
}
Generate a pseudo random block of data using several sources. On some systems this may be a bit better than PHP's mt_rand built-in function, which is not really random.
generateRandomBytes()
public boolean|string generateRandomBytes(integer $length, boolean $cryptographicallyStrong=true) |
$length | integer | number of random bytes to be generated. |
$cryptographicallyStrong | boolean | whether to fail if a cryptographically strong result cannot be generated. The method attempts to read from a cryptographically strong pseudorandom number generator (CS-PRNG), see Wikipedia. However, in some runtime environments, PHP has no access to a CS-PRNG, in which case the method returns false if $cryptographicallyStrong is true. When $cryptographicallyStrong is false, the method always returns a pseudorandom result but may fall back to using generatePseudoRandomBlock. This method does not guarantee that entropy, from sources external to the CS-PRNG, was mixed into the CS-PRNG state between each successive call. The caller can therefore expect non-blocking behavior, unlike, for example, reading from /dev/random on Linux, see Gutterman et al 2006. |
{return} | boolean|string | generated random binary string or false on failure. |
Source Code: framework/base/CSecurityManager.php#391 (
show)
public function generateRandomBytes($length,$cryptographicallyStrong=true)
{
$bytes='';
if(function_exists('openssl_random_pseudo_bytes'))
{
$bytes=openssl_random_pseudo_bytes($length,$strong);
if($this->strlen($bytes)>=$length && ($strong || !$cryptographicallyStrong))
return $this->substr($bytes,0,$length);
}
if(function_exists('mcrypt_create_iv') &&
($bytes=@mcrypt_create_iv($length, MCRYPT_DEV_URANDOM))!==false &&
$this->strlen($bytes)>=$length)
{
return $this->substr($bytes,0,$length);
}
if(($file=@fopen('/dev/urandom','rb'))!==false &&
($bytes=@fread($file,$length))!==false &&
(fclose($file) || true) &&
$this->strlen($bytes)>=$length)
{
return $this->substr($bytes,0,$length);
}
$i=0;
while($this->strlen($bytes)<$length &&
($byte=$this->generateSessionRandomBlock())!==false &&
++$i<3)
{
$bytes.=$byte;
}
if($this->strlen($bytes)>=$length)
return $this->substr($bytes,0,$length);
if ($cryptographicallyStrong)
return false;
while($this->strlen($bytes)<$length)
$bytes.=$this->generatePseudoRandomBlock();
return $this->substr($bytes,0,$length);
}
Generates a string of random bytes.
generateRandomKey()
protected string generateRandomKey() |
{return} | string | a randomly generated private key. |
generateRandomString()
public string|boolean generateRandomString(integer $length, boolean $cryptographicallyStrong=true) |
$length | integer | length of the generated string in characters. |
$cryptographicallyStrong | boolean | set this to require cryptographically strong randomness. |
{return} | string|boolean | random string or false in case it cannot be generated. |
Source Code: framework/base/CSecurityManager.php#367 (
show)
public function generateRandomString($length,$cryptographicallyStrong=true)
{
if(($randomBytes=$this->generateRandomBytes($length+2,$cryptographicallyStrong))!==false)
return strtr($this->substr(base64_encode($randomBytes),0,$length),array('+'=>'_','/'=>'~'));
return false;
}
Generate a random ASCII string. Generates only [0-9a-zA-z_~] characters which are all transparent in raw URL encoding.
generateSessionRandomBlock()
public boolean|string generateSessionRandomBlock() |
{return} | boolean|string | 20-byte random binary string or false on error. |
Source Code: framework/base/CSecurityManager.php#477 (
show)
public function generateSessionRandomBlock()
{
ini_set('session.entropy_length',20);
if(ini_get('session.entropy_length')!=20)
return false;
// These calls are (supposed to be, according to PHP manual) safe even if
// there is already an active session for the calling script.
@session_start();
@session_regenerate_id();
$bytes=session_id();
if(!$bytes)
return false;
// $bytes has 20 bytes of entropy but the session manager converts the binary
// random bytes into something readable. We have to convert that back.
// SHA-1 should do it without losing entropy.
return sha1($bytes,true);
}
Get random bytes from the system entropy source via PHP session manager.
public string getEncryptionKey() |
{return} | string | the private key used to encrypt/decrypt data. If the key is not explicitly set, a random one is generated and returned. |
Source Code: framework/base/CSecurityManager.php#158 (
show)
public function getEncryptionKey()
{
if($this->_encryptionKey!==null)
return $this->_encryptionKey;
else
{
if(($key=Yii::app()->getGlobalState(self::STATE_ENCRYPTION_KEY))!==null)
$this->setEncryptionKey($key);
else
{
if(($key=$this->generateRandomString(32,true))===false)
if(($key=$this->generateRandomString(32,false))===false)
throw new CException(Yii::t('yii',
'CSecurityManager::generateRandomString() cannot generate random string in the current environment.'));
$this->setEncryptionKey($key);
Yii::app()->setGlobalState(self::STATE_ENCRYPTION_KEY,$key);
}
return $this->_encryptionKey;
}
}
public string getValidation() |
{return} | string | - |
This method has been deprecated since version 1.1.3. Please use hashAlgorithm instead.
public string getValidationKey() |
{return} | string | the private key used to generate HMAC. If the key is not explicitly set, a random one is generated and returned. |
Source Code: framework/base/CSecurityManager.php#120 (
show)
public function getValidationKey()
{
if($this->_validationKey!==null)
return $this->_validationKey;
else
{
if(($key=Yii::app()->getGlobalState(self::STATE_VALIDATION_KEY))!==null)
$this->setValidationKey($key);
else
{
if(($key=$this->generateRandomString(32,true))===false)
if(($key=$this->generateRandomString(32,false))===false)
throw new CException(Yii::t('yii',
'CSecurityManager::generateRandomString() cannot generate random string in the current environment.'));
$this->setValidationKey($key);
Yii::app()->setGlobalState(self::STATE_VALIDATION_KEY,$key);
}
return $this->_validationKey;
}
}
public string hashData(string $data, string $key=NULL) |
$data | string | data to be hashed. |
$key | string | the private key to be used for generating HMAC. Defaults to null, meaning using validationKey. |
{return} | string | data prefixed with HMAC |
Prefixes data with an HMAC.
public string legacyDecrypt(string $data, string $key=NULL, string|array $cipher='des') |
$data | string | data to be decrypted. |
$key | string | the decryption key. This defaults to null, meaning the key should be loaded from persistent storage. |
$cipher | string|array | the algorithm to be used |
{return} | string | the decrypted data |
Source Code: framework/base/CSecurityManager.php#566 (
show)
public function legacyDecrypt($data,$key=null,$cipher='des')
{
if (!$key)
{
$key=Yii::app()->getGlobalState(self::STATE_ENCRYPTION_KEY);
if(!$key)
throw new CException(Yii::t('yii','No encryption key specified.'));
$key = md5($key);
}
if(extension_loaded('mcrypt'))
{
if(is_array($cipher))
$module=@call_user_func_array('mcrypt_module_open',$cipher);
else
$module=@mcrypt_module_open($cipher,'', MCRYPT_MODE_CBC,'');
if($module===false)
throw new CException(Yii::t('yii','Failed to initialize the mcrypt module.'));
}
else
throw new CException(Yii::t('yii','CSecurityManager requires PHP mcrypt extension to be loaded in order to use data encryption feature.'));
$derivedKey=$this->substr($key,0,@mcrypt_enc_get_key_size($module));
$ivSize=@mcrypt_enc_get_iv_size($module);
$iv=$this->substr($data,0,$ivSize);
@mcrypt_generic_init($module,$derivedKey,$iv);
$decrypted=@mdecrypt_generic($module,$this->substr($data,$ivSize,$this->strlen($data)));
@mcrypt_generic_deinit($module);
@mcrypt_module_close($module);
return rtrim($decrypted,"\0");
}
Decrypts legacy ciphertext which was produced by the old, broken implementation of encrypt().
public string maskToken(string $token) |
$token | string | An unmasked token. |
{return} | string | A masked token. |
Source Code: framework/base/CSecurityManager.php#626 (
show)
public function maskToken($token)
{
// The number of bytes in a mask is always equal to the number of bytes in a token.
$mask=$this->generateRandomString($this->strlen($token));
return strtr(base64_encode($mask.($mask^$token)),'+/','-_');
}
Masks a token to make it uncompressible. Applies a random mask to the token and prepends the mask used to the result making the string always unique. Used to mitigate BREACH attack by randomizing how token is outputted on each request.
protected resource openCryptModule() |
{return} | resource | the mycrypt module handle. |
Source Code: framework/base/CSecurityManager.php#261 (
show)
protected function openCryptModule()
{
if(extension_loaded('mcrypt'))
{
if(is_array($this->cryptAlgorithm))
$module=@call_user_func_array('mcrypt_module_open',$this->cryptAlgorithm);
else
$module=@mcrypt_module_open($this->cryptAlgorithm,'', MCRYPT_MODE_CBC,'');
if($module===false)
throw new CException(Yii::t('yii','Failed to initialize the mcrypt module.'));
return $module;
}
else
throw new CException(Yii::t('yii','CSecurityManager requires PHP mcrypt extension to be loaded in order to use data encryption feature.'));
}
Opens the mcrypt module with the configuration specified in cryptAlgorithm.
public void setEncryptionKey(string $value) |
$value | string | the key used to encrypt/decrypt data. |
public void setValidation(string $value) |
$value | string | - |
This method has been deprecated since version 1.1.3. Please use hashAlgorithm instead.
public void setValidationKey(string $value) |
$value | string | the key used to generate HMAC |
Source Code: framework/base/CSecurityManager.php#145 (
show)
public function setValidationKey($value)
{
if(!empty($value))
$this->_validationKey=$value;
else
throw new CException(Yii::t('yii','CSecurityManager.validationKey cannot be empty.'));
}
public string unmaskToken(string $maskedToken) |
$maskedToken | string | A masked token. |
{return} | string | An unmasked token, or an empty string in case of token format is invalid. |
Source Code: framework/base/CSecurityManager.php#639 (
show)
public function unmaskToken($maskedToken)
{
$decoded=base64_decode(strtr($maskedToken,'-_','+/'));
$length=$this->strlen($decoded)/2;
// Check if the masked token has an even length.
if(!is_int($length))
return '';
return $this->substr($decoded,$length,$length)^$this->substr($decoded,0,$length);
}
Unmasks a token previously masked by `maskToken`.
public string validateData(string $data, string $key=NULL) |
$data | string | data to be validated. The data must be previously generated using hashData(). |
$key | string | the private key to be used for generating HMAC. Defaults to null, meaning using validationKey. |
{return} | string | the real data with HMAC stripped off. False if the data is tampered. |
Source Code: framework/base/CSecurityManager.php#298 (
show)
public function validateData($data,$key=null)
{
if (!is_string($data))
return false;
$len=$this->strlen($this->computeHMAC('test'));
if($this->strlen($data)>=$len)
{
$hmac=$this->substr($data,0,$len);
$data2=$this->substr($data,$len,$this->strlen($data));
return $this->compareString($hmac,$this->computeHMAC($data2,$key))?$data2:false;
}
else
return false;
}
Validates if data is tampered.
protected boolean validateEncryptionKey(string $key) |
$key | string | the key to check |
{return} | boolean | the validation result |
Source Code: framework/base/CSecurityManager.php#528 (
show)
protected function validateEncryptionKey($key)
{
if(is_string($key))
{
$cryptAlgorithm = is_array($this->cryptAlgorithm) ? $this->cryptAlgorithm[0] : $this->cryptAlgorithm;
$supportedKeyLengths=@mcrypt_module_get_supported_key_sizes($cryptAlgorithm);
if($supportedKeyLengths)
{
if(!in_array($this->strlen($key),$supportedKeyLengths)) {
throw new CException(Yii::t('yii','Encryption key length can be {keyLengths}.',array('{keyLengths}'=>implode(',',$supportedKeyLengths))));
}
}
elseif(isset(self::$encryptionKeyMinimumLengths[$cryptAlgorithm]))
{
$minLength=self::$encryptionKeyMinimumLengths[$cryptAlgorithm];
$maxLength=@mcrypt_module_get_algo_key_size($cryptAlgorithm);
if($this->strlen($key)<$minLength || $this->strlen($key)>$maxLength)
throw new CException(Yii::t('yii','Encryption key length must be between {minLength} and {maxLength}.',array('{minLength}'=>$minLength,'{maxLength}'=>$maxLength)));
}
else
throw new CException(Yii::t('yii','Failed to validate key. Supported key lengths of cipher not known.'));
}
else
throw new CException(Yii::t('yii','Encryption key should be a string.'));
}
Checks if a key is valid for cryptAlgorithm.