Class 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 setValidationKey ValidationKey. The key used to encrypt data is specified by setEncryptionKey EncryptionKey. If the above keys are not explicitly set, random keys will be generated and used.

To protected data with HMAC, call CSecurityManager::hashData(); and to check if the data is tampered, call CSecurityManager::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 CSecurityManager::encrypt() and CSecurityManager::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().

CComponent

CApplicationComponent implements IApplicationComponent

CSecurityManager

Package: system\base
Copyright: 2008-2013 Yii Software LLC
License: http://www.yiiframework.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 1.0
Located at x2engine/framework/base/CSecurityManager.php

Methods summary
`public`	# `init( )` Initializes the application component. This method is required by `IApplicationComponent` and is invoked by application. If you override this method, make sure to call the parent implementation so that the application component can be marked as initialized. Initializes the application component. This method is required by `IApplicationComponent` and is invoked by application. If you override this method, make sure to call the parent implementation so that the application component can be marked as initialized. Overrides `CApplicationComponent::init()`
`public string`	# `getValidationKey( )` Returns `string` the private key used to generate HMAC. If the key is not explicitly set, a random one is generated and returned. Throws `CException` in case random string cannot be generated.
`public`	# `setValidationKey( string $value )` Parameters `$value` `string` $value the key used to generate HMAC Throws `CException` if the key is empty
`public string`	# `getEncryptionKey( )` Returns `string` the private key used to encrypt/decrypt data. If the key is not explicitly set, a random one is generated and returned. Throws `CException` in case random string cannot be generated.
`public`	# `setEncryptionKey( string $value )` Parameters `$value` `string` $value the key used to encrypt/decrypt data. Throws `CException` if the key is empty
`public string`	# `encrypt( string $data, string $key = null )` Encrypts data. Encrypts data. Parameters `$data` `string` $data data to be encrypted. `$key` `string` $key the decryption key. This defaults to null, meaning using getEncryptionKey EncryptionKey. Returns `string` the encrypted data Throws `CException` if PHP Mcrypt extension is not loaded or key is invalid
`public string`	# `decrypt( string $data, string $key = null )` Decrypts data Decrypts data Parameters `$data` `string` $data data to be decrypted. `$key` `string` $key the decryption key. This defaults to null, meaning using getEncryptionKey EncryptionKey. Returns `string` the decrypted data Throws `CException` if PHP Mcrypt extension is not loaded or key is invalid
`protected resource`	# `openCryptModule( )` Opens the mcrypt module with the configuration specified in `CSecurityManager::$cryptAlgorithm`. Opens the mcrypt module with the configuration specified in `CSecurityManager::$cryptAlgorithm`. Returns `resource` the mycrypt module handle. Throws `CException` if failed to initialize the mcrypt module or PHP mcrypt extension Since 1.1.3
`public string`	# `hashData( string $data, string $key = null )` Prefixes data with an HMAC. Prefixes data with an HMAC. Parameters `$data` `string` $data data to be hashed. `$key` `string` $key the private key to be used for generating HMAC. Defaults to null, meaning using validationKey. Returns `string` data prefixed with HMAC
`public string`	# `validateData( string $data, string $key = null )` Validates if data is tampered. Validates if data is tampered. Parameters `$data` `string` $data data to be validated. The data must be previously generated using `CSecurityManager::hashData()`. `$key` `string` $key the private key to be used for generating HMAC. Defaults to null, meaning using validationKey. Returns `string` the real data with HMAC stripped off. False if the data is tampered.
`public string`	# `computeHMAC( string $data, string\|null $key = null, string\|null $hashAlgorithm = null )` Computes the HMAC for the data with getValidationKey validationKey. This method has been made public since 1.1.14. Computes the HMAC for the data with getValidationKey validationKey. This method has been made public since 1.1.14. Parameters `$data` `string` $data data to be generated HMAC. `$key` `string\|null` $key the private key to be used for generating HMAC. Defaults to null, meaning using validationKey value. `$hashAlgorithm` `string\|null` $hashAlgorithm 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 `CSecurityManager::$hashAlgorithm` value. Returns `string` the HMAC for the data. Throws `CException` on unsupported hash algorithm given.
`public string\|boolean`	# `generateRandomString( integer $length, boolean $cryptographicallyStrong = true )` Generate a random ASCII string. Generates only [0-9a-zA-z_~] characters which are all transparent in raw URL encoding. Generate a random ASCII string. Generates only [0-9a-zA-z_~] characters which are all transparent in raw URL encoding. Parameters `$length` `integer` $length length of the generated string in characters. `$cryptographicallyStrong` `boolean` $cryptographicallyStrong set this to require cryptographically strong randomness. Returns `string\|boolean` random string or false in case it cannot be generated. Since 1.1.14
`public boolean\|string`	# `generateRandomBytes( integer $length, boolean $cryptographicallyStrong = true )` Generates a string of random bytes. Generates a string of random bytes. Parameters `$length` `integer` $length number of random bytes to be generated. `$cryptographicallyStrong` `boolean` $cryptographicallyStrong 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 `CSecurityManager::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. Returns `boolean\|string` generated random binary string or false on failure. Since 1.1.14
`public string`	# `generatePseudoRandomBlock( )` 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. 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. Returns `string` of 64 pseudo random bytes. Since 1.1.14
`public boolean\|string`	# `generateSessionRandomBlock( )` Get random bytes from the system entropy source via PHP session manager. Get random bytes from the system entropy source via PHP session manager. Returns `boolean\|string` 20-byte random binary string or false on error. Since 1.1.14
`protected boolean`	# `validateEncryptionKey( string $key )` Checks if a key is valid for `CSecurityManager::$cryptAlgorithm`. Checks if a key is valid for `CSecurityManager::$cryptAlgorithm`. Parameters `$key` `string` $key the key to check Returns `boolean` the validation result Throws `CException` if the supported key lengths of the cipher are unknown
`public boolean`	# `compareString( string $expected, string $actual )` Performs string comparison using timing attack resistant approach. Performs string comparison using timing attack resistant approach. Parameters `$expected` `string` $expected string to compare. `$actual` `string` $actual user-supplied string. Returns `boolean` whether strings are equal. See http://codereview.stackexchange.com/questions/13512

Methods inherited from CApplicationComponent
`getIsInitialized()`

Methods inherited from CComponent
`__call(), __get(), __isset(), __set(), __unset(), asa(), attachBehavior(), attachBehaviors(), attachEventHandler(), canGetProperty(), canSetProperty(), detachBehavior(), detachBehaviors(), detachEventHandler(), disableBehavior(), disableBehaviors(), enableBehavior(), enableBehaviors(), evaluateExpression(), getEventHandlers(), hasEvent(), hasEventHandler(), hasProperty(), raiseEvent()`

Constants summary
`string`	`STATE_VALIDATION_KEY`	`'Yii.CSecurityManager.validationkey'`	#
`string`	`STATE_ENCRYPTION_KEY`	`'Yii.CSecurityManager.encryptionkey'`	#

Properties summary
`protected static array`	`$encryptionKeyMinimumLengths`	`array( 'blowfish'=>4, 'arcfour'=>5, 'rc2'=>5, )`	# known minimum lengths per encryption algorithm known minimum lengths per encryption algorithm
`public boolean`	`$validateEncryptionKey`	`true`	# if encryption key should be validated if encryption key should be validated
`public string`	`$hashAlgorithm`	`'sha1'`	# the name of the hashing algorithm to be used by `CSecurityManager::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. the name of the hashing algorithm to be used by `CSecurityManager::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. Since 1.1.3
`public mixed`	`$cryptAlgorithm`	`'rijndael-128'`	# the name of the crypt algorithm to be used by `CSecurityManager::encrypt()` and `CSecurityManager::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, `<span class="php-keyword1">array</span>(<span class="php-quote">'rijndael-128'</span>, <span class="php-quote">''</span>, <span class="php-quote">'ofb'</span>, <span class="php-quote">''</span>)`. Defaults to AES Note: MCRYPT_RIJNDAEL₁₉₂ and MCRYPT_RIJNDAEL₂₅₆ 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₁₂₈ 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. the name of the crypt algorithm to be used by `CSecurityManager::encrypt()` and `CSecurityManager::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, `<span class="php-keyword1">array</span>(<span class="php-quote">'rijndael-128'</span>, <span class="php-quote">''</span>, <span class="php-quote">'ofb'</span>, <span class="php-quote">''</span>)`. Defaults to AES Note: MCRYPT_RIJNDAEL₁₉₂ and MCRYPT_RIJNDAEL₂₅₆ 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₁₂₈ 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. Since 1.1.3

Properties inherited from CApplicationComponent
`$behaviors`

Magic properties summary
`public string`	`$validationKey`	# The private key used to generate HMAC. If the key is not explicitly set, a random one is generated and returned. The private key used to generate HMAC. If the key is not explicitly set, a random one is generated and returned.
`public string`	`$encryptionKey`	# The private key used to encrypt/decrypt data. If the key is not explicitly set, a random one is generated and returned. The private key used to encrypt/decrypt data. If the key is not explicitly set, a random one is generated and returned.
`public string`	`$validation`	#

Magic properties inherited from CApplicationComponent
`$isInitialized`

Packages

Classes

Interfaces

Exceptions

Class CSecurityManager

Overrides

Returns

Throws

Parameters

Throws

Returns

Throws

Parameters

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Returns

Throws

Since

Parameters

Returns

Parameters

Returns

Parameters

Returns

Throws

Parameters

Returns

Since

Parameters

Returns

Since

Returns

Since

Returns

Since

Parameters

Returns

Throws

Parameters

Returns

See

Since

Since