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
-
string
'The request has been black-holed'
Properties summary
-
$_action
protectedHolds the current action of the controllerstring
-
$_defaultConfig
protectedDefault configarray
-
$session
public
Inherited Properties
Method Summary
- _authRequired() protectedCheck if authentication is required
- _callback() protectedCalls a controller callback method
- _debugCheckFields() protectedIterates data array to check against expected
- _debugExpectedFields() protectedGenerate debug message for the expected fields
- _debugPostTokenNotMatching() protectedCreate a message for humans to understand why Security token is not matching
- _fieldsList() protectedReturn the fields list for the hash calculation
- _hashParts() protectedReturn 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() protectedSets the actions that require a $method HTTP request, or empty for all actions
- _secureRequired() protectedCheck if access requires secure connection
- _sortedUnlocked() protectedGet the sorted unlocked string
- _throwException() protectedCheck debug status and throw an Exception based on the existing one
- _unlocked() protectedGet the unlocked string
- _validToken() protectedCheck if token is valid
- _validatePost() protectedValidate 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() publicEvents supported by this component.
- requireAuth() publicSets the actions that require whitelisted form submissions.
- requireSecure() publicSets the actions that require a request that is SSL-secured, or empty for all actions
- startup() publicComponent startup. All security checking happens here.
Method Detail
_authRequired()source protected
_authRequired( Cake\Controller\Controller $controller )
Check if authentication is required
Deprecated
3.2.2 This feature is confusing and not useful.Parameters
-
Cake\Controller\Controller
$controller
- Instantiating controller
Returns
booleantrue if authentication required
_callback()source 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
mixedController callback method's response
Throws
Cake\Network\Exception\BadRequestException
When a the blackholeCallback is not callable.
_debugCheckFields()source 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
arrayMessages
_debugExpectedFields()source 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
string|nullError message about expected fields
_debugPostTokenNotMatching()source 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
stringMessage explaining why the tokens are not matching
_fieldsList()source protected
_fieldsList( array $check )
Return the fields list for the hash calculation
Parameters
- array
$check
- Data array
Returns
array_hashParts()source protected
_hashParts( Cake\Controller\Controller $controller )
Return hash parts for the Token generation
Parameters
-
Cake\Controller\Controller
$controller
- Instantiating controller
Returns
array_matchExistingFields()source 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
arrayError messages
_requireMethod()source 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()source protected
_secureRequired( Cake\Controller\Controller $controller )
Check if access requires secure connection
Parameters
-
Cake\Controller\Controller
$controller
- Instantiating controller
Returns
booleantrue if secure connection required
_sortedUnlocked()source protected
_sortedUnlocked( array $data )
Get the sorted unlocked string
Parameters
- array
$data
- Data array
Returns
string_throwException()source 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
Cake\Network\Exception\BadRequestException
_unlocked()source protected
_unlocked( array $data )
Get the unlocked string
Parameters
- array
$data
- Data array
Returns
string_validToken()source protected
_validToken( Cake\Controller\Controller $controller )
Check if token is valid
Parameters
-
Cake\Controller\Controller
$controller
- Instantiating controller
Returns
stringfields token
Throws
Cake\Controller\Exception\SecurityException
_validatePost()source protected
_validatePost( Cake\Controller\Controller $controller )
Validate submitted form
Parameters
-
Cake\Controller\Controller
$controller
- Instantiating controller
Returns
booleantrue if submitted form is valid
Throws
Cake\Controller\Exception\AuthSecurityException
blackHole()source 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
mixedIf specified, controller blackHoleCallback's response, or no return otherwise
Throws
Cake\Network\Exception\BadRequestException
See
\Cake\Controller\Component\SecurityComponent::$blackHoleCallbackLink
https://book.cakephp.org/3.0/en/controllers/components/security.html#handling-blackhole-callbacksgenerateToken()source 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
booleanimplementedEvents()source public
implementedEvents( )
Events supported by this component.
Returns
arrayOverrides
Cake\Controller\Component::implementedEvents()
requireAuth()source public
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
3.2.2 This feature is confusing and not useful.Parameters
- string|array
$actions
- Actions list
requireSecure()source 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()source public
startup( Cake\Event\Event $event )
Component startup. All security checking happens here.
Parameters
-
Cake\Event\Event
$event
- An Event instance
Returns
mixedMethods inherited from Cake\Controller\Component
__construct()source 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()source public
__debugInfo( )
Returns an array that can be used to describe the internal state of this object.
Returns
array__get()source public
__get( string $name )
Magic method for lazy loading $components.
Parameters
- string
$name
- Name of component to get.
Returns
mixedA Component object or null.
getController()source public
getController( )
Get the controller this component is bound to.
Returns
Cake\Controller\Controller
The bound controller.
initialize()source 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()source protected
_configDelete( string $key )
Deletes a single config key.
Parameters
- string
$key
- Key to delete.
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config
_configRead()source protected
_configRead( string|null $key )
Reads a config key.
Parameters
- string|null
$key
- Key to read.
Returns
mixed_configWrite()source 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
Cake\Core\Exception\Exception
if attempting to clobber existing config
config()source public
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
3.4.0 use setConfig()/getConfig() instead.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
mixedConfig value being read, or the object itself on write operations.
Throws
Cake\Core\Exception\Exception
When trying to set a key that is invalid.
configShallow()source 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()source 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
mixedConfig value being read.
setConfig()source 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
Cake\Core\Exception\Exception
When trying to set a key that is invalid.
Methods used from Cake\Log\LogTrait
log()source 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
booleanSuccess of log write.
Properties detail
$_defaultConfigsource
protected array
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.2 -
allowedControllers
- 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 ]
© 2005–2017 The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.4/class-Cake.Controller.Component.SecurityComponent.html