CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 3.10 Red Velvet API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 3.10
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Command
    • Console
    • Controller
      • Component
      • Exception
    • Core
    • Database
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • Http
    • I18n
    • Log
    • Mailer
    • Network
    • ORM
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

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.
Namespace: Cake\Controller\Component
Link: https://book.cakephp.org/3/en/controllers/components/security.html

Constants

  • string
    DEFAULT_EXCEPTION_MESSAGE ¶
    'The request has been black-holed'

    Default message used for exceptions thrown

Property Summary

  • $_action protected
    string

    Holds the current action of the controller

  • $_componentMap protected
    array

    A component lookup table used to lazy load component objects.

  • $_config protected
    array

    Runtime config

  • $_configInitialized protected
    bool

    Whether the config property has already been configured with defaults

  • $_defaultConfig protected
    array

    Default config

  • $_registry protected
    Cake\Controller\ComponentRegistry

    Component registry class used to lazy load components.

  • $components public
    array

    Other Components this component uses.

  • $request public deprecated
    Cake\Http\ServerRequest

    Request object

  • $response public deprecated
    Cake\Http\Response

    Response object

  • $session public
    Cake\Http\Session

    The Session object

Method Summary

  • __construct() public

    Constructor

  • __debugInfo() public

    Returns an array that can be used to describe the internal state of this object.

  • __get() public

    Magic method for lazy loading $components.

  • _authRequired() protected deprecated

    Check if authentication is required

  • _callback() protected

    Calls a controller callback method

  • _configDelete() protected

    Deletes a single config key.

  • _configRead() protected

    Reads a config key.

  • _configWrite() protected

    Writes a config key.

  • _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

  • config() public deprecated

    Gets/Sets the config.

  • configShallow() public

    Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

  • generateToken() public

    Manually add form tampering prevention token information into the provided request object.

  • getConfig() public

    Returns the config.

  • getConfigOrFail() public

    Returns the config for this specific key.

  • getController() public

    Get the controller this component is bound to.

  • implementedEvents() public

    Events supported by this component.

  • initialize() public

    Constructor hook method.

  • log() public

    Convenience method to write a message to Log. See Log::write() for more information on writing to logs.

  • 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

  • setConfig() public

    Sets the config.

  • startup() public

    Component startup. All security checking happens here.

Method Detail

__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(): array

Returns an array that can be used to describe the internal state of this object.

Returns
array

__get() ¶ public

__get(string $name): Cake\Controller\Component|null

Magic method for lazy loading $components.

Parameters
string $name

Name of component to get.

Returns
Cake\Controller\Component|null

_authRequired() ¶ protected

_authRequired(Cake\Controller\Controller $controller): bool

Check if authentication is required

Parameters
Cake\Controller\Controller $controller

Instantiating controller

Returns
bool

_callback() ¶ protected

_callback(Cake\Controller\Controller $controller, string $method, array $params = []): mixed

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
mixed
Throws
Cake\Http\Exception\BadRequestException
When a the blackholeCallback is not callable.

_configDelete() ¶ protected

_configDelete(string $key): void

Deletes a single config key.

Parameters
string $key

Key to delete.

Returns
void
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() ¶ protected

_configRead(string|null $key): mixed

Reads a config key.

Parameters
string|null $key

Key to read.

Returns
mixed

_configWrite() ¶ protected

_configWrite(string|array $key, mixed $value, bool|string $merge = false): void

Writes a config key.

Parameters
string|array $key

Key to write to.

mixed $value

Value to write.

bool|string $merge optional

True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Returns
void
Throws
Cake\Core\Exception\Exception
if attempting to clobber existing config

_debugCheckFields() ¶ protected

_debugCheckFields(array $dataFields, array $expectedFields = [], string $intKeyMessage = '', string $stringKeyMessage = '', string $missingMessage = ''): array

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
array

_debugExpectedFields() ¶ protected

_debugExpectedFields(array $expectedFields = [], string $missingMessage = ''): string|null

Generate debug message for the expected fields

Parameters
array $expectedFields optional

Expected fields

string $missingMessage optional

Message template

Returns
string|null

_debugPostTokenNotMatching() ¶ protected

_debugPostTokenNotMatching(Cake\Controller\Controller $controller, array $hashParts): string

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
string

_fieldsList() ¶ protected

_fieldsList(array $check): array

Return the fields list for the hash calculation

Parameters
array $check

Data array

Returns
array

_hashParts() ¶ protected

_hashParts(Cake\Controller\Controller $controller): array

Return hash parts for the Token generation

Parameters
Cake\Controller\Controller $controller

Instantiating controller

Returns
array

_matchExistingFields() ¶ protected

_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

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
array

_requireMethod() ¶ protected

_requireMethod(string $method, array $actions = []): void

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.

Returns
void

_secureRequired() ¶ protected

_secureRequired(Cake\Controller\Controller $controller): bool

Check if access requires secure connection

Parameters
Cake\Controller\Controller $controller

Instantiating controller

Returns
bool

_sortedUnlocked() ¶ protected

_sortedUnlocked(array $data): string

Get the sorted unlocked string

Parameters
array $data

Data array

Returns
string

_throwException() ¶ protected

_throwException(Cake\Controller\Exception\SecurityException|null $exception = null): void

Check debug status and throw an Exception based on the existing one

Parameters
Cake\Controller\Exception\SecurityException|null $exception optional

Additional debug info describing the cause

Returns
void
Throws
Cake\Http\Exception\BadRequestException

_unlocked() ¶ protected

_unlocked(array $data): string

Get the unlocked string

Parameters
array $data

Data array

Returns
string

_validToken() ¶ protected

_validToken(Cake\Controller\Controller $controller): string

Check if token is valid

Parameters
Cake\Controller\Controller $controller

Instantiating controller

Returns
string
Throws
Cake\Controller\Exception\SecurityException

_validatePost() ¶ protected

_validatePost(Cake\Controller\Controller $controller): bool

Validate submitted form

Parameters
Cake\Controller\Controller $controller

Instantiating controller

Returns
bool
Throws
Cake\Controller\Exception\AuthSecurityException

blackHole() ¶ public

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

Parameters
Cake\Controller\Controller $controller

Instantiating controller

string $error optional

Error method

Cake\Controller\Exception\SecurityException|null $exception optional

Additional debug info describing the cause

Returns
mixed
Throws
Cake\Http\Exception\BadRequestException
See Also
\Cake\Controller\Component\SecurityComponent::$blackHoleCallback
Links
https://book.cakephp.org/3/en/controllers/components/security.html#handling-blackhole-callbacks

config() ¶ public

config(string|array|null $key = null, mixed|null $value = null, bool $merge = true): mixed

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']);
Parameters
string|array|null $key optional

The key to get/set, or a complete array of configs.

mixed|null $value optional

The value to set.

bool $merge optional

Whether to recursively merge or overwrite existing config, defaults to true.

Returns
mixed
Throws
Cake\Core\Exception\Exception
When trying to set a key that is invalid.

configShallow() ¶ public

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']);
Parameters
string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

Returns
$this

generateToken() ¶ public

generateToken(Cake\Http\ServerRequest $request): Cake\Http\ServerRequest

Manually add form tampering prevention token information into the provided request object.

Parameters
Cake\Http\ServerRequest $request

The request object to add into.

Returns
Cake\Http\ServerRequest

getConfig() ¶ public

getConfig(string|null $key = null, mixed|null $default = null): mixed|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

The key to get or null for the whole config.

mixed|null $default optional

The return value when the key does not exist.

Returns
mixed|null

getConfigOrFail() ¶ public

getConfigOrFail(string|null $key): mixed

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters
string|null $key

The key to get.

Returns
mixed
Throws
InvalidArgumentException

getController() ¶ public

getController(): Cake\Controller\Controller

Get the controller this component is bound to.

Returns
Cake\Controller\Controller

implementedEvents() ¶ public

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.

Returns
array

initialize() ¶ public

initialize(array $config): void

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.

Returns
void

log() ¶ public

log(mixed $message, int|string $level = LogLevel::ERROR, string|array $context = []): bool

Convenience method to write a message to Log. See Log::write() for more information on writing to logs.

Parameters
mixed $message

Log message.

int|string $level optional

Error level.

string|array $context optional

Additional log data relevant to this message.

Returns
bool

requireAuth() ¶ public

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.

Parameters
string|array $actions

Actions list

Returns
void

requireSecure() ¶ public

requireSecure(string|array|null $actions = null): void

Sets the actions that require a request that is SSL-secured, or empty for all actions

Parameters
string|array|null $actions optional

Actions list

Returns
void

setConfig() ¶ public

setConfig(string|array $key, mixed|null $value = null, bool $merge = true): $this

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

The value to set.

bool $merge optional

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.

startup() ¶ public

startup(Cake\Event\Event $event): mixed

Component startup. All security checking happens here.

Parameters
Cake\Event\Event $event

An Event instance

Returns
mixed

Property Detail

$_action ¶ protected

Holds the current action of the controller

Type
string

$_componentMap ¶ protected

A component lookup table used to lazy load component objects.

Type
array

$_config ¶ protected

Runtime config

Type
array

$_configInitialized ¶ protected

Whether the config property has already been configured with defaults

Type
bool

$_defaultConfig ¶ protected

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.
Type
array

$_registry ¶ protected

Component registry class used to lazy load components.

Type
Cake\Controller\ComponentRegistry

$components ¶ public

Other Components this component uses.

Type
array

$request ¶ public deprecated

Request object

Type
Cake\Http\ServerRequest

$response ¶ public deprecated

Response object

Type
Cake\Http\Response

$session ¶ public

The Session object

Type
Cake\Http\Session
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs