0 follower

CSecurityManager

Package system.base
Inheritance class CSecurityManager » CApplicationComponent » CComponent
Implements IApplicationComponent
Since 1.0
Version $Id$
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

PropertyTypeDescriptionDefined By
behaviors array the behaviors that should be attached to this component. CApplicationComponent
encryptionKey string the private key used to encrypt/decrypt data. CSecurityManager
isInitialized boolean whether this application component has been initialized (i.e., init() is invoked. CApplicationComponent
validation string hashing algorithm used to generate HMAC. CSecurityManager
validationKey string the private key used to generate HMAC. CSecurityManager

Public Methods

Hide inherited methods

MethodDescriptionDefined 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 with EncryptionKey. 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 with EncryptionKey. CSecurityManager
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 whether this application component has been initialized (i.e., init() is invoked.) CApplicationComponent
getValidation() Returns hashing algorithm used to generate HMAC. Defaults to 'SHA1'. 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() Initializes the application component. CApplicationComponent
raiseEvent() Raises an event. CComponent
setEncryptionKey() Sets the key used to encrypt/decrypt data. CSecurityManager
setValidation() Sets hashing algorithm used to generate HMAC. It must be either 'MD5' or 'SHA1'. CSecurityManager
setValidationKey() Sets the key used to generate HMAC CSecurityManager
validateData() Validates if data is tampered. CSecurityManager

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
computeHMAC() Computes the HMAC for the data with ValidationKey. CSecurityManager
generateRandomKey() CSecurityManager

Property Details

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.

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

hashing algorithm used to generate HMAC. Defaults to 'SHA1'.

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)
$data string data to be generated HMAC
{return} string the HMAC for the data
Source Code: framework/base/CSecurityManager.php#229 (show)
protected function computeHMAC($data)
{
    if(
$this->_validation==='SHA1')
    {
        
$pack='H40';
        
$func='sha1';
    }
    else
    {
        
$pack='H32';
        
$func='md5';
    }
    
$key=$this->getValidationKey();
    
$key=str_pad($func($key), 64chr(0));
    return 
$func((str_repeat(chr(0x5C), 64) ^ substr($key064)) . pack($pack$func((str_repeat(chr(0x36), 64) ^ substr($key064)) . $data)));
}

Computes the HMAC for the data with ValidationKey.

decrypt() method
public string decrypt(string $data)
$data string data to be decrypted.
{return} string the decrypted data
Source Code: framework/base/CSecurityManager.php#175 (show)
public function decrypt($data)
{
    if(
extension_loaded('mcrypt'))
    {
        
$module=mcrypt_module_open(MCRYPT_3DES''MCRYPT_MODE_CBC'');
        
$key=substr(md5($this->getEncryptionKey()),0,mcrypt_enc_get_key_size($module));
        
$ivSize=mcrypt_enc_get_iv_size($module);
        
$iv=substr($data,0,$ivSize);
        
mcrypt_generic_init($module,$key,$iv);
        
$decrypted=mdecrypt_generic($module,substr($data,$ivSize));
        
mcrypt_generic_deinit($module);
        
mcrypt_module_close($module);
        return 
rtrim($decrypted,"\0");
    }
    else
        throw new 
CException(Yii::t('yii','CSecurityManager requires PHP mcrypt extension to be loaded in order to use data encryption feature.'));
}

Decrypts data with EncryptionKey.

encrypt() method
public string encrypt(string $data)
$data string data to be encrypted.
{return} string the encrypted data
Source Code: framework/base/CSecurityManager.php#151 (show)
public function encrypt($data)
{
    if(
extension_loaded('mcrypt'))
    {
        
$module=mcrypt_module_open(MCRYPT_3DES''MCRYPT_MODE_CBC'');
        
$key=substr(md5($this->getEncryptionKey()),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;
    }
    else
        throw new 
CException(Yii::t('yii','CSecurityManager requires PHP mcrypt extension to be loaded in order to use data encryption feature.'));
}

Encrypts data with EncryptionKey.

generateRandomKey() method
protected string generateRandomKey()
{return} string a randomly generated key
Source Code: framework/base/CSecurityManager.php#53 (show)
protected function generateRandomKey()
{
    return 
rand().rand().rand().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#96 (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 hashing algorithm used to generate HMAC. Defaults to 'SHA1'.
Source Code: framework/base/CSecurityManager.php#129 (show)
public function getValidation()
{
    return 
$this->_validation;
}

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#62 (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)
$data string data to be hashed.
{return} string data prefixed with HMAC
Source Code: framework/base/CSecurityManager.php#198 (show)
public function hashData($data)
{
    
$hmac=$this->computeHMAC($data);
    return 
$hmac.$data;
}

Prefixes data with an HMAC.

setEncryptionKey() method
public void setEncryptionKey(string $value)
$value string the key used to encrypt/decrypt data.
Source Code: framework/base/CSecurityManager.php#118 (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 hashing algorithm used to generate HMAC. It must be either 'MD5' or 'SHA1'.
Source Code: framework/base/CSecurityManager.php#137 (show)
public function setValidation($value)
{
    if(
$value==='MD5' || $value==='SHA1')
        
$this->_validation=$value;
    else
        throw new 
CException(Yii::t('yii','CSecurityManager.validation must be either "MD5" or "SHA1".'));
}

setValidationKey() method
public void setValidationKey(string $value)
$value string the key used to generate HMAC
Source Code: framework/base/CSecurityManager.php#84 (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)
$data string data to be validated. The data must be previously generated using hashData().
{return} string the real data with HMAC stripped off. False if the data is tampered.
Source Code: framework/base/CSecurityManager.php#211 (show)
public function validateData($data)
{
    
$len=$this->_validation==='SHA1'?40:32;
    if(
strlen($data)>=$len)
    {
        
$hmac=substr($data,0,$len);
        
$data2=substr($data,$len);
        return 
$hmac===$this->computeHMAC($data2)?$data2:false;
    }
    else
        return 
false;
}

Validates if data is tampered.