Class SecurityComponent
The Security Component creates an easy way to integrate tighter security in your application. It provides methods for various tasks like:
- Restricting which HTTP methods your application accepts.
- Form tampering protection
- Requiring that SSL be used.
- Limiting cross controller communication.
- Cake\Controller\Component implements Cake\Event\EventListenerInterface uses Cake\Core\InstanceConfigTrait , Cake\Log\LogTrait
-
Cake\Controller\Component\SecurityComponent
Link: https://book.cakephp.org/3.0/en/controllers/components/security.html
Location: Controller/Component/SecurityComponent.php
Constants summary
-
stringDEFAULT_EXCEPTION_MESSAGE¶'The request has been black-holed'
Properties summary
-
$_actionprotectedstringHolds the current action of the controller -
$_defaultConfigprotectedarrayDefault config -
$sessionpublicThe Session object
Inherited Properties
Method Summary
-
_authRequired() protected deprecated
Check if authentication is required -
_callback() protected
Calls a controller callback method -
_debugCheckFields() protected
Iterates data array to check against expected -
_debugExpectedFields() protected
Generate debug message for the expected fields -
_debugPostTokenNotMatching() protected
Create a message for humans to understand why Security token is not matching -
_fieldsList() protected
Return the fields list for the hash calculation -
_hashParts() protected
Return hash parts for the Token generation -
_matchExistingFields() protected
Generate array of messages for the existing fields in POST data, matching dataFields in $expectedFields will be unset
-
_requireMethod() protected
Sets the actions that require a $method HTTP request, or empty for all actions -
_secureRequired() protected
Check if access requires secure connection -
_sortedUnlocked() protected
Get the sorted unlocked string -
_throwException() protected
Check debug status and throw an Exception based on the existing one -
_unlocked() protected
Get the unlocked string -
_validToken() protected
Check if token is valid -
_validatePost() protected
Validate submitted form -
blackHole() public
Black-hole an invalid request with a 400 error or custom callback. If SecurityComponent::$blackHoleCallback is specified, it will use this callback by executing the method indicated in $error
-
generateToken() public
Manually add form tampering prevention token information into the provided request object.
-
implementedEvents() public
Events supported by this component. -
requireAuth() public deprecated
Sets the actions that require whitelisted form submissions. -
requireSecure() public
Sets the actions that require a request that is SSL-secured, or empty for all actions -
startup() public
Component startup. All security checking happens here.
Method Detail
_authRequired() protected deprecated ¶
_authRequired( Cake\Controller\Controller $controller )
Check if authentication is required
Deprecated
Parameters
-
Cake\Controller\Controller$controller - Instantiating controller
Returns
true if authentication required
_callback() protected ¶
_callback( Cake\Controller\Controller $controller , string $method , array $params = [] )
Calls a controller callback method
Parameters
-
Cake\Controller\Controller$controller - Instantiating controller
- string $method
- Method to execute
- array $params optional []
- Parameters to send to method
Returns
Controller callback method's response
Throws
_debugCheckFields() protected ¶
_debugCheckFields( array $dataFields , array $expectedFields = [] , string $intKeyMessage = '' , string $stringKeyMessage = '' , string $missingMessage = '' )
Iterates data array to check against expected
Parameters
- array $dataFields
- Fields array, containing the POST data fields
- array $expectedFields optional []
- Fields array, containing the expected fields we should have in POST
- string $intKeyMessage optional ''
- Message string if unexpected found in data fields indexed by int (not protected)
- string $stringKeyMessage optional ''
- Message string if tampered found in data fields indexed by string (protected)
- string $missingMessage optional ''
- Message string if missing field
Returns
Messages
_debugExpectedFields() protected ¶
_debugExpectedFields( array $expectedFields = [] , string $missingMessage = '' )
Generate debug message for the expected fields
Parameters
- array $expectedFields optional []
- Expected fields
- string $missingMessage optional ''
- Message template
Returns
Error message about expected fields
_debugPostTokenNotMatching() protected ¶
_debugPostTokenNotMatching( Cake\Controller\Controller $controller , array $hashParts )
Create a message for humans to understand why Security token is not matching
Parameters
-
Cake\Controller\Controller$controller - Instantiating controller
- array $hashParts
- Elements used to generate the Token hash
Returns
Message explaining why the tokens are not matching
_fieldsList() protected ¶
_fieldsList( array $check )
Return the fields list for the hash calculation
Parameters
- array $check
- Data array
Returns
_hashParts() protected ¶
_hashParts( Cake\Controller\Controller $controller )
Return hash parts for the Token generation
Parameters
-
Cake\Controller\Controller$controller - Instantiating controller
Returns
_matchExistingFields() protected ¶
_matchExistingFields( array $dataFields , array $expectedFields , string $intKeyMessage , string $stringKeyMessage )
Generate array of messages for the existing fields in POST data, matching dataFields in $expectedFields will be unset
Parameters
- array $dataFields
- Fields array, containing the POST data fields
- array $expectedFields
- Fields array, containing the expected fields we should have in POST
- string $intKeyMessage
- Message string if unexpected found in data fields indexed by int (not protected)
- string $stringKeyMessage
- Message string if tampered found in data fields indexed by string (protected)
Returns
Error messages
_requireMethod() protected ¶
_requireMethod( string $method , array $actions = [] )
Sets the actions that require a $method HTTP request, or empty for all actions
Parameters
- string $method
- The HTTP method to assign controller actions to
- array $actions optional []
- Controller actions to set the required HTTP method to.
_secureRequired() protected ¶
_secureRequired( Cake\Controller\Controller $controller )
Check if access requires secure connection
Parameters
-
Cake\Controller\Controller$controller - Instantiating controller
Returns
true if secure connection required
_sortedUnlocked() protected ¶
_sortedUnlocked( array $data )
Get the sorted unlocked string
Parameters
- array $data
- Data array
Returns
_throwException() protected ¶
_throwException( Cake\Controller\Exception\SecurityException|null $exception = null )
Check debug status and throw an Exception based on the existing one
Parameters
-
Cake\Controller\Exception\SecurityException|null $exception optional null - Additional debug info describing the cause
Throws
_unlocked() protected ¶
_unlocked( array $data )
Get the unlocked string
Parameters
- array $data
- Data array
Returns
_validToken() protected ¶
_validToken( Cake\Controller\Controller $controller )
Check if token is valid
Parameters
-
Cake\Controller\Controller$controller - Instantiating controller
Returns
fields token
Throws
_validatePost() protected ¶
_validatePost( Cake\Controller\Controller $controller )
Validate submitted form
Parameters
-
Cake\Controller\Controller$controller - Instantiating controller
Returns
true if submitted form is valid
Throws
blackHole() public ¶
blackHole( Cake\Controller\Controller $controller , string $error = '' , Cake\Controller\Exception\SecurityException $exception = null )
Black-hole an invalid request with a 400 error or custom callback. If SecurityComponent::$blackHoleCallback is specified, it will use this callback by executing the method indicated in $error
Parameters
-
Cake\Controller\Controller$controller - Instantiating controller
- string $error optional ''
- Error method
-
Cake\Controller\Exception\SecurityException$exception optional null - Additional debug info describing the cause
Returns
If specified, controller blackHoleCallback's response, or no return otherwise
Throws
See
Link
generateToken() public ¶
generateToken( Cake\Http\ServerRequest $request )
Manually add form tampering prevention token information into the provided request object.
Parameters
-
Cake\Http\ServerRequest$request - The request object to add into.
Returns
implementedEvents() public ¶
implementedEvents( )
Events supported by this component.
Returns
Overrides
requireAuth() public deprecated ¶
requireAuth( string|array $actions )
Sets the actions that require whitelisted form submissions.
Adding actions with this method will enforce the restrictions set in SecurityComponent::$allowedControllers and SecurityComponent::$allowedActions.
Deprecated
Parameters
- string|array $actions
- Actions list
requireSecure() public ¶
requireSecure( string|array|null $actions = null )
Sets the actions that require a request that is SSL-secured, or empty for all actions
Parameters
- string|array|null $actions optional null
- Actions list
startup() public ¶
startup( Cake\Event\Event $event )
Component startup. All security checking happens here.
Parameters
-
Cake\Event\Event$event - An Event instance
Returns
Methods inherited from Cake\Controller\Component
__construct() public ¶
__construct( Cake\Controller\ComponentRegistry $registry , array $config = [] )
Constructor
Parameters
-
Cake\Controller\ComponentRegistry$registry - A ComponentRegistry this component can use to lazy load its components
- array $config optional []
- Array of configuration settings.
__debugInfo() public ¶
__debugInfo( )
Returns an array that can be used to describe the internal state of this object.
Returns
__get() public ¶
__get( string $name )
Magic method for lazy loading $components.
Parameters
- string $name
- Name of component to get.
Returns
initialize() public ¶
initialize( array $config )
Constructor hook method.
Implement this method to avoid having to overwrite the constructor and call parent.
Parameters
- array $config
- The configuration settings provided to this component.
Methods used from Cake\Core\InstanceConfigTrait
_configDelete() protected ¶
_configDelete( string $key )
Deletes a single config key.
Parameters
- string $key
- Key to delete.
Throws
_configRead() protected ¶
_configRead( string|null $key )
Reads a config key.
Parameters
- string|null $key
- Key to read.
Returns
_configWrite() protected ¶
_configWrite( string|array $key , mixed $value , boolean|string $merge = false )
Writes a config key.
Parameters
- string|array $key
- Key to write to.
- mixed $value
- Value to write.
- boolean|string $merge optional false
True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Throws
config() public deprecated ¶
config( string|array|null $key = null , mixed|null $value = null , boolean $merge = true )
Gets/Sets the config.
Usage
Reading the whole config:
$this->config();
Reading a specific value:
$this->config('key');
Reading a nested value:
$this->config('some.nested.key');
Setting a specific value:
$this->config('key', $value);
Setting a nested value:
$this->config('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->config(['one' => 'value', 'another' => 'value']);
Deprecated
Parameters
- string|array|null $key optional null
- The key to get/set, or a complete array of configs.
- mixed|null $value optional null
- The value to set.
- boolean $merge optional true
- Whether to recursively merge or overwrite existing config, defaults to true.
Returns
Config value being read, or the object itself on write operations.
Throws
configShallow() public ¶
configShallow( string|array $key , mixed|null $value = null )
Merge provided config with existing config. Unlike config() which does
a recursive merge for nested keys, this method does a simple merge.
Setting a specific value:
$this->configShallow('key', $value);
Setting a nested value:
$this->configShallow('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->configShallow(['one' => 'value', 'another' => 'value']);
Parameters
- string|array $key
- The key to set, or a complete array of configs.
- mixed|null $value optional null
- The value to set.
Returns
$this
getConfig() public ¶
getConfig( string|null $key = null , mixed $default = null )
Returns the config.
Usage
Reading the whole config:
$this->getConfig();
Reading a specific value:
$this->getConfig('key');
Reading a nested value:
$this->getConfig('some.nested.key');
Reading with default value:
$this->getConfig('some-key', 'default-value');
Parameters
- string|null $key optional null
- The key to get or null for the whole config.
- mixed $default optional null
- The return value when the key does not exist.
Returns
Configuration data at the named key or null if the key does not exist.
setConfig() public ¶
setConfig( string|array $key , mixed|null $value = null , boolean $merge = true )
Sets the config.
Usage
Setting a specific value:
$this->setConfig('key', $value);
Setting a nested value:
$this->setConfig('some.nested.key', $value);
Updating multiple config settings at the same time:
$this->setConfig(['one' => 'value', 'another' => 'value']);
Parameters
- string|array $key
- The key to set, or a complete array of configs.
- mixed|null $value optional null
- The value to set.
- boolean $merge optional true
- Whether to recursively merge or overwrite existing config, defaults to true.
Returns
$this
Throws
Methods used from Cake\Log\LogTrait
log() public ¶
log( mixed $msg , integer|string $level = LogLevel::ERROR , string|array $context = [] )
Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
Parameters
- mixed $msg
- Log message.
- integer|string $level optional LogLevel::ERROR
- Error level.
- string|array $context optional []
- Additional log data relevant to this message.
Returns
Success of log write.
Properties detail
$_defaultConfig ¶
Default config
blackHoleCallback- The controller method that will be called if this request is black-hole'd.requireSecure- List of actions that require an SSL-secured connection.requireAuth- List of actions that require a valid authentication key. Deprecated as of 3.2.2allowedControllers- Controllers from which actions of the current controller are allowed to receive requests.allowedActions- Actions from which actions of the current controller are allowed to receive requests.unlockedFields- Form fields to exclude from POST validation. Fields can be unlocked either in the Component, or with FormHelper::unlockField(). Fields that have been unlocked are not required to be part of the POST and hidden unlocked fields do not have their values checked.unlockedActions- Actions to exclude from POST validation checks. Other checks like requireAuth(), requireSecure() etc. will still be applied.validatePost- Whether to validate POST data. Set to false to disable for data coming from 3rd party services, etc.
[
'blackHoleCallback' => null,
'requireSecure' => [],
'requireAuth' => [],
'allowedControllers' => [],
'allowedActions' => [],
'unlockedFields' => [],
'unlockedActions' => [],
'validatePost' => true
]