CSecurityManager

All Packages | Properties | Methods

Package	system.base
Inheritance	class CSecurityManager » CApplicationComponent » CComponent
Implements	IApplicationComponent
Since	1.0
Version	$Id: CSecurityManager.php 3555 2012-02-09 10:29:44Z mdomba $
Source Code	framework/base/CSecurityManager.php

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().

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
behaviors	array	the behaviors that should be attached to this component.	CApplicationComponent
cryptAlgorithm	mixed	the name of the crypt algorithm to be used by encrypt and decrypt.	CSecurityManager
encryptionKey	string	the private key used to encrypt/decrypt data.	CSecurityManager
hashAlgorithm	string	the name of the hashing algorithm to be used by computeHMAC.	CSecurityManager
isInitialized	boolean	Checks if this application component bas been initialized.	CApplicationComponent
validation	string	This method has been deprecated since version 1.1.3.	CSecurityManager
validationKey	string	the private key used to generate HMAC.	CSecurityManager

Public Methods

Hide inherited methods

Method	Description	Defined By
__call()	Calls the named method which is not a class method.	CComponent
__get()	Returns a property value, an event handler list or a behavior based on its name.	CComponent
__isset()	Checks if a property value is null.	CComponent
__set()	Sets value of a component property.	CComponent
__unset()	Sets a component property to be null.	CComponent
asa()	Returns the named behavior object.	CComponent
attachBehavior()	Attaches a behavior to this component.	CComponent
attachBehaviors()	Attaches a list of behaviors to the component.	CComponent
attachEventHandler()	Attaches an event handler to an event.	CComponent
canGetProperty()	Determines whether a property can be read.	CComponent
canSetProperty()	Determines whether a property can be set.	CComponent
decrypt()	Decrypts data	CSecurityManager
detachBehavior()	Detaches a behavior from the component.	CComponent
detachBehaviors()	Detaches all behaviors from the component.	CComponent
detachEventHandler()	Detaches an existing event handler.	CComponent
disableBehavior()	Disables an attached behavior.	CComponent
disableBehaviors()	Disables all behaviors attached to this component.	CComponent
enableBehavior()	Enables an attached behavior.	CComponent
enableBehaviors()	Enables all behaviors attached to this component.	CComponent
encrypt()	Encrypts data.	CSecurityManager
evaluateExpression()	Evaluates a PHP expression or callback under the context of this component.	CComponent
getEncryptionKey()	Returns the private key used to encrypt/decrypt data. If the key is not explicitly set, a random one is generated and returned.	CSecurityManager
getEventHandlers()	Returns the list of attached event handlers for an event.	CComponent
getIsInitialized()	Checks if this application component bas been initialized.	CApplicationComponent
getValidation()	This method has been deprecated since version 1.1.3.	CSecurityManager
getValidationKey()	Returns the private key used to generate HMAC. If the key is not explicitly set, a random one is generated and returned.	CSecurityManager
hasEvent()	Determines whether an event is defined.	CComponent
hasEventHandler()	Checks whether the named event has attached handlers.	CComponent
hasProperty()	Determines whether a property is defined.	CComponent
hashData()	Prefixes data with an HMAC.	CSecurityManager
init()		CSecurityManager
raiseEvent()	Raises an event.	CComponent
setEncryptionKey()	Sets the key used to encrypt/decrypt data.	CSecurityManager
setValidation()	This method has been deprecated since version 1.1.3.	CSecurityManager
setValidationKey()	Sets the key used to generate HMAC	CSecurityManager
validateData()	Validates if data is tampered.	CSecurityManager

Protected Methods

Hide inherited methods

Method	Description	Defined By
computeHMAC()	Computes the HMAC for the data with ValidationKey.	CSecurityManager
generateRandomKey()		CSecurityManager
openCryptModule()	Opens the mcrypt module with the configuration specified in cryptAlgorithm.	CSecurityManager

Property Details

cryptAlgorithm property (available since v1.1.3)

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-256', '', 'ofb', '').

Defaults to 'des', meaning using DES crypt algorithm.

encryptionKey property

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.

hashAlgorithm property (available since v1.1.3)

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.

validation property

public string getValidation()
public void setValidation(string $value)

This method has been deprecated since version 1.1.3. Please use hashAlgorithm instead.

validationKey property

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

computeHMAC() method

protected string computeHMAC(string $data, string $key=NULL)
$data	string	data to be generated HMAC
$key	string	the private key to be used for generating HMAC. Defaults to null, meaning using validationKey.
{return}	string	the HMAC for the data

Source Code: framework/base/CSecurityManager.php#280 (show)


protected function computeHMAC($data,$key=null)
{
    if($key===null)
        $key=$this->getValidationKey();

    if(function_exists('hash_hmac'))
        return hash_hmac($this->hashAlgorithm, $data, $key);

    if(!strcasecmp($this->hashAlgorithm,'sha1'))
    {
        $pack='H40';
        $func='sha1';
    }
    else
    {
        $pack='H32';
        $func='md5';
    }
    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.

decrypt() method

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#206 (show)


public function decrypt($data,$key=null)
{
    $module=$this->openCryptModule();
    $key=$this->substr($key===null ? md5($this->getEncryptionKey()) : $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,$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

encrypt() method

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#186 (show)


public function encrypt($data,$key=null)
{
    $module=$this->openCryptModule();
    $key=$this->substr($key===null ? md5($this->getEncryptionKey()) : $key,0,mcrypt_enc_get_key_size($module));
    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.

generateRandomKey() method

protected string generateRandomKey()
{return}	string	a randomly generated private key

Source Code: framework/base/CSecurityManager.php#86 (show)


protected function generateRandomKey()
{
    return sprintf('%08x%08x%08x%08x',mt_rand(),mt_rand(),mt_rand(),mt_rand());
}

getEncryptionKey() method

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#129 (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
        {
            $key=$this->generateRandomKey();
            $this->setEncryptionKey($key);
            Yii::app()->setGlobalState(self::STATE_ENCRYPTION_KEY,$key);
        }
        return $this->_encryptionKey;
    }
}

getValidation() method

public string getValidation()
{return}	string

Source Code: framework/base/CSecurityManager.php#164 (show)


public function getValidation()
{
    return $this->hashAlgorithm;
}

This method has been deprecated since version 1.1.3. Please use hashAlgorithm instead.

getValidationKey() method

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#95 (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
        {
            $key=$this->generateRandomKey();
            $this->setValidationKey($key);
            Yii::app()->setGlobalState(self::STATE_VALIDATION_KEY,$key);
        }
        return $this->_validationKey;
    }
}

hashData() method

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

Source Code: framework/base/CSecurityManager.php#248 (show)


public function hashData($data,$key=null)
{
    return $this->computeHMAC($data,$key).$data;
}

Prefixes data with an HMAC.

init() method

public void init()

Source Code: framework/base/CSecurityManager.php#77 (show)


public function init()
{
    parent::init();
    $this->_mbstring=extension_loaded('mbstring');
}

openCryptModule() method (available since v1.1.3)

protected resource openCryptModule()
{return}	resource	the mycrypt module handle.

Source Code: framework/base/CSecurityManager.php#224 (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.

setEncryptionKey() method

public void setEncryptionKey(string $value)
$value	string	the key used to encrypt/decrypt data.

Source Code: framework/base/CSecurityManager.php#151 (show)


public function setEncryptionKey($value)
{
    if(!empty($value))
        $this->_encryptionKey=$value;
    else
        throw new CException(Yii::t('yii','CSecurityManager.encryptionKey cannot be empty.'));
}

setValidation() method

public void setValidation(string $value)
$value	string	-

Source Code: framework/base/CSecurityManager.php#174 (show)


public function setValidation($value)
{
    $this->hashAlgorithm=$value;
}

This method has been deprecated since version 1.1.3. Please use hashAlgorithm instead.

setValidationKey() method

public void setValidationKey(string $value)
$value	string	the key used to generate HMAC

Source Code: framework/base/CSecurityManager.php#117 (show)


public function setValidationKey($value)
{
    if(!empty($value))
        $this->_validationKey=$value;
    else
        throw new CException(Yii::t('yii','CSecurityManager.validationKey cannot be empty.'));
}

validateData() method

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#261 (show)


public function validateData($data,$key=null)
{
    $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 $hmac===$this->computeHMAC($data2,$key)?$data2:false;
    }
    else
        return false;
}

Validates if data is tampered.