Security

Type

Class

Namespace

craft\services

Inherits

craft\services\Security » yii\base\Security » yii\base\Component » yii\base\BaseObject

Implements

yii\base\Configurable

Since

3.0.0

Security service.

An instance of the service is available via Craft::$app->security.

View source

Public Properties

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

minimumPasswordLength

Type

integer

Default value

null

Access

Read-only

View source

sensitiveKeywords

Type

string[]

Default value

[]

Keywords used to reference sensitive data

See also redactIfSensitive()

View source

validationKey

Type

string

Default value

null

Access

Read-only

View source

Public Methods

Method	Description
__call()	Calls the named method which is not a class method.
__clone()	This method is called after the object is created by cloning an existing one.
__construct()	Constructor.
__get()	Returns the value of a component property.
__isset()	Checks if a property is set, i.e. defined and not null.
__set()	Sets the value of a component property.
__unset()	Sets a component property to be null.
attachBehavior()	Attaches a behavior to this component.
attachBehaviors()	Attaches a list of behaviors to the component.
behaviors()	Returns a list of behaviors that this component should behave as.
canGetProperty()	Returns a value indicating whether a property can be read.
canSetProperty()	Returns a value indicating whether a property can be set.
className()	Returns the fully qualified name of this class.
compareString()	Performs string comparison using timing attack resistant approach.
decryptByKey()	Verifies and decrypts data encrypted with encryptByKey().
decryptByPassword()	Verifies and decrypts data encrypted with encryptByPassword().
detachBehavior()	Detaches a behavior from the component.
detachBehaviors()	Detaches all behaviors from the component.
encryptByKey()	Encrypts data using a cryptographic key.
encryptByPassword()	Encrypts data using a password.
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.
generatePasswordHash()	Generates a secure hash from a password and a random salt.
generateRandomKey()	Generates specified number of random bytes.
generateRandomString()	Generates a random string of specified length.
getBehavior()	Returns the named behavior object.
getBehaviors()	Returns all behaviors attached to this component.
getMinimumPasswordLength()
getValidationKey()	Deprecated wrapper for Craft::$app->config->general->securityKey.
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.
hasMethod()	Returns a value indicating whether a method is defined.
hasProperty()	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()	Derives a key from the given input key using the standard HKDF algorithm.
init()
isSensitive()	Returns whether the given key appears to be sensitive.
maskToken()	Masks a token to make it uncompressible.
off()	Detaches an existing event handler from this component.
on()	Attaches an event handler to an event.
pbkdf2()	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()	Triggers an event.
unmaskToken()	Unmasks a token previously masked by maskToken.
validateData()	Validates if the given data is tampered.
validatePassword()	Verifies a password against a hash.

decryptByKey()

Verifies and decrypts data encrypted with encryptByKey().

See also encryptByKey()View source

Arguments

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

Returns

boolean, string – The decrypted data or false on authentication failure

Throws

• yii\base\InvalidConfigException
  on OpenSSL not loaded
• yii\base\Exception
  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(). The input key must be properly random -- use generateRandomKey() to generate keys. The encrypted data includes a keyed message authentication code (MAC) so there is no need to hash input or output data.

See also:

• decryptByKey()
• encryptByPassword()

View source

Arguments

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

Returns

string – The encrypted data

Throws

• yii\base\InvalidConfigException
  on OpenSSL not loaded
• yii\base\Exception
  on OpenSSL error

getMinimumPasswordLength()

View source

Returns

integer

getValidationKey()

DEPRECATED

Deprecated in 3.0.0-beta.27. Use Craft::$app->config->general->securityKey instead.

Deprecated wrapper for Craft::$app->config->general->securityKey.

View source

Returns

string

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() as those methods perform the task.

See also:

• validateData()
• generateRandomKey()
• hkdf()
• pbkdf2()

View source

Arguments

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

Returns

string – The data prefixed with the keyed hash

Throws

• yii\base\Exception
  if the validation key could not be written
• yii\base\InvalidConfigException
  when HMAC generation fails.

hashPassword()

Hashes a given password with the bcrypt blowfish encryption algorithm.

View source

Arguments

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

Returns

string – The hash.

init()

View source

isSensitive()

Since

3.7.24

Returns whether the given key appears to be sensitive.

View source

Arguments

• $key (string)

Returns

boolean

redactIfSensitive()

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

View source

Arguments

• $key (string)
• $value (string, array)

Returns

string, array – The possibly-redacted value

validateData()

Validates if the given data is tampered.

See also hashData()View source

Arguments

• $data (string) – The data to be validated. The data must be previously generated by hashData().
• $key (string, null) – 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) – 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, false – The real data with the hash stripped off. False if the data is tampered.

Throws

• yii\base\Exception
  if the validation key could not be written
• yii\base\InvalidConfigException
  when HMAC generation fails.

Protected Methods

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