README

Yii Security

Security package provides a set of classes to handle common security-related tasks:

• Random values generation
• Password hashing and validation
• Encryption and decryption
• Data tampering prevention
• Masking token length

Requirements

• PHP 8.0 or higher.
• hash PHP extension.
• openssl PHP extension.
• random PHP extension.

Installation

The package could be installed with Composer:

composer require yiisoft/security

General usage

Random values generation

In order to generate a string that is 42 characters long use:

$randomString = Random::string(42);

The following extras are available via PHP directly:

• random_bytes() for bytes. Note that output may not be ASCII.
• random_int() for integers.

Password hashing and validation

Working with passwords includes two steps. Saving password hashes:

$hash = (new PasswordHasher())->hash($password);

// save hash to database or another storage
saveHash($hash); 

Validating password against the hash:

// obtain hash from database or another storage
$hash = getHash();

$result = (new PasswordHasher())->validate($password, $hash); 

Encryption and decryption by password

Encrypting data:

$encryptedData = (new Crypt())->encryptByPassword($data, $password);

// save data to database or another storage
saveData($encryptedData);

Decrypting it:

// obtain encrypted data from database or another storage
$encryptedData = getEncryptedData();

$data = (new Crypt())->decryptByPassword($encryptedData, $password);

Encryption and decryption by key

Encrypting data:

$encryptedData = (new Crypt())->encryptByKey($data, $key);

// save data to database or another storage
saveData($encryptedData);

Decrypting it:

// obtain encrypted data from database or another storage
$encryptedData = getEncryptedData();

$data = (new Crypt())->decryptByKey($encryptedData, $key);

Data tampering prevention

MAC signing could be used in order to prevent data tampering. The $key should be present at both sending and receiving sides. At the sending side:

$signedMessage = (new Mac())->sign($message, $key);

sendMessage($signedMessage);

At the receiving side:

$signedMessage = receiveMessage($signedMessage);

try {
    $message = (new Mac())->getMessage($signedMessage, $key);
} catch (\Yiisoft\Security\DataIsTamperedException $e) {
    // data is tampered
}

Masking token length

Masking a token helps to mitigate BREACH attack by randomizing how token outputted on each request. A random mask applied to the token making the string always unique.

In order to mask a token:

$maskedToken = \Yiisoft\Security\TokenMask::apply($token);

In order to get original value from the masked one:

$token = \Yiisoft\Security\TokenMask::remove($maskedToken);

Native PHP functionality

Additionally to this library methods, there is a set of handy native PHP methods.

Timing attack resistant string comparison

Comparing strings as usual is not secure when dealing with user inputed passwords or key phrases. Usual string comparison return as soon as a difference between the strings is found so attacker could efficiently brute-force character by character going to the next one as soon as response time increases.

There is a special function in PHP that compares strings in a constant time:

hash_equals($expected, $actual);

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

License

The Yii Security is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates