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

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);

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework. To run it:

./vendor/bin/infection

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

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.

yiisoft / security

Maintainers

Details