Bachir Soussi Chiadmi 41863f872c updated core and modules		6 years ago
..
dist	41863f872c updated core and modules	6 years ago
lib	41863f872c updated core and modules	6 years ago
other	41863f872c updated core and modules	6 years ago
.gitignore	58f46e4e8f caore d8 files	7 years ago
.scrutinizer.yml	58f46e4e8f caore d8 files	7 years ago
.travis.yml	58f46e4e8f caore d8 files	7 years ago
ERRATA.md	58f46e4e8f caore d8 files	7 years ago
LICENSE	58f46e4e8f caore d8 files	7 years ago
README.md	58f46e4e8f caore d8 files	7 years ago
SECURITY.md	58f46e4e8f caore d8 files	7 years ago
build-phar.sh	41863f872c updated core and modules	6 years ago
composer.json	41863f872c updated core and modules	6 years ago
phpunit.sh	58f46e4e8f caore d8 files	7 years ago
phpunit.xml.dist	58f46e4e8f caore d8 files	7 years ago
psalm-autoload.php	41863f872c updated core and modules	6 years ago
psalm.xml	41863f872c updated core and modules	6 years ago

random_compat

PHP 5.x polyfill for random_bytes() and random_int() created and maintained by Paragon Initiative Enterprises.

Although this library should function in earlier versions of PHP, we will only consider issues relevant to supported PHP versions. If you are using an unsupported version of PHP, please upgrade as soon as possible.

Important

Although this library has been examined by some security experts in the PHP community, there will always be a chance that we overlooked something. Please ask your favorite trusted hackers to hammer it for implementation errors and bugs before even thinking about deploying it in production.

Do not use the master branch, use a stable release.

For the background of this library, please refer to our blog post on Generating Random Integers and Strings in PHP.

Usability Notice

If PHP cannot safely generate random data, this library will throw an Exception. It will never fall back to insecure random data. If this keeps happening, upgrade to a newer version of PHP immediately.

Usage

This library exposes the CSPRNG functions added in PHP 7 for use in PHP 5 projects. Their behavior should be identical.

Generate a string of random bytes

try {
    $string = random_bytes(32);
} catch (TypeError $e) {
    // Well, it's an integer, so this IS unexpected.
    die("An unexpected error has occurred"); 
} catch (Error $e) {
    // This is also unexpected because 32 is a reasonable integer.
    die("An unexpected error has occurred");
} catch (Exception $e) {
    // If you get this message, the CSPRNG failed hard.
    die("Could not generate a random string. Is our OS secure?");
}

var_dump(bin2hex($string));
// string(64) "5787c41ae124b3b9363b7825104f8bc8cf27c4c3036573e5f0d4a91ad2eeac6f"

Generate a random integer between two given integers (inclusive)

try {
    $int = random_int(0,255);

} catch (TypeError $e) {
    // Well, it's an integer, so this IS unexpected.
    die("An unexpected error has occurred"); 
} catch (Error $e) {
    // This is also unexpected because 0 and 255 are both reasonable integers.
    die("An unexpected error has occurred");
} catch (Exception $e) {
    // If you get this message, the CSPRNG failed hard.
    die("Could not generate a random string. Is our OS secure?");
}

var_dump($int);
// int(47)

Exception handling

When handling exceptions and errors you must account for differences between PHP 5 and PHP7.

The differences:

Catching Error works, so long as it is caught before Exception.
Catching Exception has different behavior, without previously catching Error.
There is no portable way to catch all errors/exceptions.

Our recommendation

Always catch Error before Exception.

Example

try {
    return random_int(1, $userInput);
} catch (TypeError $e) {
    // This is okay, so long as `Error` is caught before `Exception`.
    throw new Exception('Please enter a number!');
} catch (Error $e) {
    // This is required, if you do not need to do anything just rethrow.
    throw $e;
} catch (Exception $e) {
    // This is optional and maybe omitted if you do not want to handle errors
    // during generation.
    throw new InternalServerErrorException(
        'Oops, our server is bust and cannot generate any random data.',
        500,
        $e
    );
}

Contributors

This project would not be anywhere near as excellent as it is today if it weren't for the contributions of the following individuals:

README.md