DEFAULT_EXCEPTION_MESSAGE
DEFAULT_EXCEPTION_MESSAGE = 'The request has been black-holed'
Default message used for exceptions thrown
The Security Component creates an easy way to integrate tighter security in your application. It provides methods for various tasks like:
$request : \Cake\Http\ServerRequest
Request object
$response : \Cake\Http\Response
Response object
$session : \Cake\Http\Session
The Session object
$_registry : \Cake\Controller\ComponentRegistry
Component registry class used to lazy load components.
$_defaultConfig : 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.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.__construct(\Cake\Controller\ComponentRegistry $registry, array $config = array())
Constructor
| \Cake\Controller\ComponentRegistry | $registry | A ComponentRegistry this component can use to lazy load its components |
| array | $config | Array of configuration settings. |
getController() : \Cake\Controller\Controller
Get the controller this component is bound to.
The bound controller.
implementedEvents() : array
Events supported by this component.
Uses Conventions to map controller events to standard component callback method names. By defining one of the callback methods a component is assumed to be interested in the related event.
Override this method if you need to add non-conventional event listeners. Or if you want components to listen to non-standard events.
setConfig(string|array $key, mixed|null $value = null, boolean $merge = true) : $this
Sets the config.
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']);| string|array | $key | The key to set, or a complete array of configs. |
| mixed|null | $value | The value to set. |
| boolean | $merge | Whether to recursively merge or overwrite existing config, defaults to true. |
When trying to set a key that is invalid.
getConfig(string|null $key = null, mixed $default = null) : mixed
Returns the config.
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');| string|null | $key | The key to get or null for the whole config. |
| mixed | $default | The return value when the key does not exist. |
Config value being read.
config(string|array|null $key = null, mixed|null $value = null, boolean $merge = true) : mixed
Gets/Sets the config.
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']);| string|array|null | $key | The key to get/set, or a complete array of configs. |
| mixed|null | $value | The value to set. |
| boolean | $merge | Whether to recursively merge or overwrite existing config, defaults to true. |
When trying to set a key that is invalid.
Config value being read, or the object itself on write operations.
configShallow(string|array $key, mixed|null $value = null) : $this
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']);| string|array | $key | The key to set, or a complete array of configs. |
| mixed|null | $value | The value to set. |
log(mixed $msg, integer|string $level = \Psr\Log\LogLevel::ERROR, string|array $context = array()) : boolean
Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
| mixed | $msg | Log message. |
| integer|string | $level | Error level. |
| string|array | $context | Additional log data relevant to this message. |
Success of log write.
startup(\Cake\Event\Event $event) : mixed
Component startup. All security checking happens here.
| \Cake\Event\Event | $event | An Event instance |
requireAuth(string|array $actions) : void
Sets the actions that require whitelisted form submissions.
Adding actions with this method will enforce the restrictions set in SecurityComponent::$allowedControllers and SecurityComponent::$allowedActions.
| string|array | $actions | Actions list |
blackHole(\Cake\Controller\Controller $controller, string $error = '', \Cake\Controller\Exception\SecurityException|null $exception = null) : mixed
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
| \Cake\Controller\Controller | $controller | Instantiating controller |
| string | $error | Error method |
| \Cake\Controller\Exception\SecurityException|null | $exception | Additional debug info describing the cause |
If specified, controller blackHoleCallback's response, or no return otherwise
generateToken(\Cake\Http\ServerRequest $request) : \Cake\Http\ServerRequest
Manually add form tampering prevention token information into the provided request object.
| \Cake\Http\ServerRequest | $request | The request object to add into. |
The modified request.
_configWrite(string|array $key, mixed $value, boolean|string $merge = false) : void
Writes a config key.
| string|array | $key | Key to write to. |
| mixed | $value | Value to write. |
| boolean|string | $merge | True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false. |
if attempting to clobber existing config
_throwException(\Cake\Controller\Exception\SecurityException|null $exception = null) : void
Check debug status and throw an Exception based on the existing one
| \Cake\Controller\Exception\SecurityException|null | $exception | Additional debug info describing the cause |
_requireMethod(string $method, array $actions = array()) : void
Sets the actions that require a $method HTTP request, or empty for all actions
| string | $method | The HTTP method to assign controller actions to |
| array | $actions | Controller actions to set the required HTTP method to. |
_secureRequired(\Cake\Controller\Controller $controller) : boolean
Check if access requires secure connection
| \Cake\Controller\Controller | $controller | Instantiating controller |
true if secure connection required
_authRequired(\Cake\Controller\Controller $controller) : boolean
Check if authentication is required
| \Cake\Controller\Controller | $controller | Instantiating controller |
true if authentication required
_validatePost(\Cake\Controller\Controller $controller) : boolean
Validate submitted form
| \Cake\Controller\Controller | $controller | Instantiating controller |
true if submitted form is valid
_validToken(\Cake\Controller\Controller $controller) : string
Check if token is valid
| \Cake\Controller\Controller | $controller | Instantiating controller |
fields token
_hashParts(\Cake\Controller\Controller $controller) : array
Return hash parts for the Token generation
| \Cake\Controller\Controller | $controller | Instantiating controller |
_debugPostTokenNotMatching(\Cake\Controller\Controller $controller, array $hashParts) : string
Create a message for humans to understand why Security token is not matching
| \Cake\Controller\Controller | $controller | Instantiating controller |
| array | $hashParts | Elements used to generate the Token hash |
Message explaining why the tokens are not matching
_debugCheckFields(array $dataFields, array $expectedFields = array(), string $intKeyMessage = '', string $stringKeyMessage = '', string $missingMessage = '') : array
Iterates data array to check against expected
| 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) |
| string | $missingMessage | Message string if missing field |
Messages
_callback(\Cake\Controller\Controller $controller, string $method, array $params = array()) : mixed
Calls a controller callback method
| \Cake\Controller\Controller | $controller | Instantiating controller |
| string | $method | Method to execute |
| array | $params | Parameters to send to method |
When a the blackholeCallback is not callable.
Controller callback method's response
_matchExistingFields(array $dataFields, array $expectedFields, string $intKeyMessage, string $stringKeyMessage) : array
Generate array of messages for the existing fields in POST data, matching dataFields in $expectedFields will be unset
| 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) |
Error messages
_debugExpectedFields(array $expectedFields = array(), string $missingMessage = '') : string|null
Generate debug message for the expected fields
| array | $expectedFields | Expected fields |
| string | $missingMessage | Message template |
Error message about expected fields