Security

Type: Class
Namespace: craft\services
Inherits: craft\services\Security » yii\base\Security (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)
Implements: yii\base\Configurable (opens new window)
Since: 3.0.0

Security service.

An instance of the service is available via Craft::$app->security (opens new window).

# Public Properties

Property	Description
allowedCiphers (opens new window)	array (opens new window)[] – Look-up table of block sizes and key sizes for each supported OpenSSL cipher.
authKeyInfo (opens new window)	string (opens new window) – HKDF info value for derivation of message authentication key.
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
cipher (opens new window)	string (opens new window) – The cipher to use for encryption and decryption.
derivationIterations (opens new window)	integer (opens new window) – Derivation iterations count.
kdfHash (opens new window)	string (opens new window) – Hash algorithm for key derivation.
macHash (opens new window)	string (opens new window) – Hash algorithm for message authentication.
minimumPasswordLength	integer (opens new window)
passwordHashCost (opens new window)	integer (opens new window) – Default cost used for password hashing.
passwordHashStrategy (opens new window)	string (opens new window) – Strategy, which should be used to generate password hash.
sensitiveKeywords	string (opens new window)[] – Keywords used to reference sensitive data

# `minimumPasswordLength`

Type: integer (opens new window)
Default value: null
Access: Read-only

View source (opens new window)

# `sensitiveKeywords`

Type: string (opens new window)[]
Default value: []

Keywords used to reference sensitive data

# Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone() (opens new window)	This method is called after the object is created by cloning an existing one.
__construct() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__unset() (opens new window)	Sets a component property to be null.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
behaviors() (opens new window)	Returns a list of behaviors that this component should behave as.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
className() (opens new window)	Returns the fully qualified name of this class.
compareString() (opens new window)	Performs string comparison using timing attack resistant approach.
decryptByKey()	Verifies and decrypts data encrypted with encryptByKey().
decryptByPassword() (opens new window)	Verifies and decrypts data encrypted with encryptByPassword() (opens new window).
detachBehavior() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
encryptByKey()	Encrypts data using a cryptographic key.
encryptByPassword() (opens new window)	Encrypts data using a password.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
generatePasswordHash() (opens new window)	Generates a secure hash from a password and a random salt.
generateRandomKey() (opens new window)	Generates specified number of random bytes.
generateRandomString() (opens new window)	Generates a random string of specified length.
getBehavior() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	Returns all behaviors attached to this component.
getMinimumPasswordLength()
hasEventHandlers() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
hashData()	Prefixes data with a keyed hash value so that it can later be detected if it is tampered.
hashPassword()	Hashes a given password with the bcrypt blowfish encryption algorithm.
hkdf() (opens new window)	Derives a key from the given input key using the standard HKDF algorithm.
init()	Initializes the object.
isSensitive()	Returns whether the given key appears to be sensitive.
maskToken() (opens new window)	Masks a token to make it uncompressible.
off() (opens new window)	Detaches an existing event handler from this component.
on() (opens new window)	Attaches an event handler to an event.
pbkdf2() (opens new window)	Derives a key from the given password using the standard PBKDF2 algorithm.
redactIfSensitive()	Checks the given key to see if it looks like it contains sensitive info, and if so, redacts the given value.
trigger() (opens new window)	Triggers an event.
unmaskToken() (opens new window)	Unmasks a token previously masked by `maskToken`.
validateData()	Validates if the given data is tampered.
validatePassword() (opens new window)	Verifies a password against a hash.

# `decryptByKey()`

Verifies and decrypts data encrypted with encryptByKey().

Arguments

$data (string (opens new window)) – The encrypted data to decrypt
$inputKey (string (opens new window), null (opens new window)) – The input to use for encryption and authentication
$info (string (opens new window)) – Optional context and application specific information, see hkdf() (opens new window)

Returns

string (opens new window), false (opens new window) – The decrypted data or false on authentication failure

Throws

yii\base\InvalidConfigException (opens new window)
on OpenSSL not loaded
yii\base\Exception (opens new window)
on OpenSSL error

# `encryptByKey()`

Encrypts data using a cryptographic key.

Derives keys for encryption and authentication from the input key using HKDF and a random salt, which is very fast relative to encryptByPassword() (opens new window). The input key must be properly random -- use generateRandomKey() (opens new window) to generate keys. The encrypted data includes a keyed message authentication code (MAC) so there is no need to hash input or output data.

Arguments

$data (string (opens new window)) – The data to encrypt
$inputKey (string (opens new window), null (opens new window)) – The input to use for encryption and authentication
$info (string (opens new window)) – Optional context and application specific information, see hkdf() (opens new window)

# `hashData()`

Prefixes data with a keyed hash value so that it can later be detected if it is tampered.

There is no need to hash inputs or outputs of encryptByKey() or encryptByPassword() (opens new window) as those methods perform the task.

Arguments

$data (string (opens new window)) – The data to be protected
$key (string (opens new window), null (opens new window)) – The secret key to be used for generating hash. Should be a secure cryptographic key.
$rawHash (boolean (opens new window)) – Whether the generated hash value is in raw binary format. If false, lowercase hex digits will be generated.

Returns

string (opens new window) – The data prefixed with the keyed hash

Throws

yii\base\Exception (opens new window)
if the validation key could not be written
yii\base\InvalidConfigException (opens new window)
when HMAC generation fails.

# `hashPassword()`

Hashes a given password with the bcrypt blowfish encryption algorithm.

View source (opens new window)

Arguments

$password (string (opens new window)) – The string to hash
$validateHash (boolean (opens new window)) – If you want to validate the just generated hash. Will throw an exception if validation fails.

Returns

string (opens new window) – The hash.

# `init()`

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

View source (opens new window)

# `isSensitive()`

Since: 3.7.24

Returns whether the given key appears to be sensitive.

View source (opens new window)

Arguments

$key (string (opens new window))

Returns

boolean (opens new window)

# `redactIfSensitive()`

Checks the given key to see if it looks like it contains sensitive info, and if so, redacts the given value.

View source (opens new window)

Arguments

$key (string (opens new window))
$value (mixed)

Returns

mixed – The possibly-redacted value

# `validateData()`

Validates if the given data is tampered.

Arguments

$data (string (opens new window)) – The data to be validated. The data must be previously generated by hashData().
$key (string (opens new window), null (opens new window)) – The secret key that was previously used to generate the hash for the data in hashData(). function to see the supported hashing algorithms on your system. This must be the same as the value passed to hashData() when generating the hash for the data.
$rawHash (boolean (opens new window)) – This should take the same value as when you generate the data using hashData(). It indicates whether the hash value in the data is in binary format. If false, it means the hash value consists of lowercase hex digits only. hex digits will be generated.

Returns

string (opens new window), false (opens new window) – The real data with the hash stripped off. False if the data is tampered.

Throws

yii\base\Exception (opens new window)
if the validation key could not be written
yii\base\InvalidConfigException (opens new window)
when HMAC generation fails.

# Protected Methods

Method	Description
decrypt() (opens new window)	Decrypts data.
encrypt() (opens new window)	Encrypts data.
generateSalt() (opens new window)	Generates a salt that can be used to generate a password hash.
shouldUseLibreSSL() (opens new window)

← Sections Sites →

Security

# Public Properties

# minimumPasswordLength

# sensitiveKeywords

# Public Methods

# decryptByKey()

Arguments

Returns

Throws

# encryptByKey()

Arguments

Returns

Throws

# getMinimumPasswordLength()

Returns

# hashData()

Arguments

Returns

Throws

# hashPassword()

Arguments

Returns

# init()

# isSensitive()

Arguments

Returns

# redactIfSensitive()

Arguments

Returns

# validateData()

Arguments

Returns

Throws

# Protected Methods

# `minimumPasswordLength`

# `sensitiveKeywords`

# `decryptByKey()`

# `encryptByKey()`

# `getMinimumPasswordLength()`

# `hashData()`

# `hashPassword()`

# `init()`

# `isSensitive()`

# `redactIfSensitive()`

# `validateData()`