Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

random_compat

PHP 5.x support for random_bytes() and random_int()

Subscribe to updates I use random_compat


Statistics on random_compat

Number of watchers on Github 2716
Number of open issues 3
Main language PHP
Average time to merge a PR 3 days
Open pull requests 4+
Closed pull requests 19+
Last commit over 1 year ago
Repo Created about 4 years ago
Repo Last Updated over 1 year ago
Size 873 KB
Homepage https://paragonie...
Organization / Authorparagonie
Latest Releasev2.0.11
Contributors19
Page Updated
Do you use random_compat? Leave a review!
View open issues (3)
View random_compat activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating random_compat for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

random_compat

Build Status Scrutinizer Latest Stable Version Latest Unstable Version License Downloads

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.

Installing

With Composer:

composer require paragonie/random_compat

Signed PHP Archive:

As of version 1.2.0, we also ship an ECDSA-signed PHP Archive with each stable release on Github.

  1. Download the .phar, .phar.pubkey, and .phar.pubkey.asc files.
  2. (Recommended but not required) Verify the PGP signature of .phar.pubkey (contained within the .asc file) using the PGP public key for Paragon Initiative Enterprises.
  3. Extract both .phar and .phar.pubkey files to the same directory.
  4. require_once "/path/to/random_compat.phar";
  5. When a new version is released, you only need to replace the .phar file; the .pubkey will not change (unless our signing key is ever compromised).

Manual Installation:

  1. Download a stable release.
  2. Extract the files into your project.
  3. require_once "/path/to/random_compat/lib/random.php";

The entrypoint should be lib/random.php directly, not any of the other files in /lib.

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 int. 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
    );
}

Troubleshooting

Exception: Could not gather sufficient random data**

If an Exception is thrown, then your operating system is not secure.

  1. If you're on Windows, make sure you enable mcrypt.
  2. If you're on any other OS, make sure /dev/urandom is readable.
    • FreeBSD jails need to expose /dev/urandom from the host OS
    • If you use open_basedir, make sure /dev/urandom is allowed

This library does not (and will not accept any patches to) fall back to an insecure random number generator.

Version Conflict with [Other PHP Project]

If you're using a project that has a line like this in its composer.json

"require" {
    ...
    "paragonie/random_compat": "~1.1",
    ...
}

...and then you try to add random_compat 2 (or another library that explicitly requires random_compat 2, such as this secure PHP encryption library), you will get a version conflict.

The solution is to get the project to update its requirement string to allow version 2 and above to be used instead of hard-locking users to version 1.

"require" {
    ...
-    "paragonie/random_compat": "~1.1",
+    "paragonie/random_compat": "^1|^2",
    ...
}

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:

random_compat open pull requests (View All Pulls)
  • update to version 5.3.3 for mcrypt use
  • Fix basedir typo
  • Satisfies the php7.0 linter, fixes #115
  • fix 1.x version number
random_compat list of languages used
random_compat latest release notes
v2.0.11 Version 2.0.11
  • Minor docblock corrections.
  • Re-issuing a PHP Archive to attempt to address an issue with the Phar provided. See #134.
v2.0.10 Version 2.0.10
  • Mcrypt can now be used on PHP < 5.3.7 if you're not on Windows.
  • Minor boyscouting changes.
v1.4.2 Version 1.4.2

Backported changes from version 2:

  • Version 2.0.10 - 2017-03-13
    • Mcrypt can now be used on PHP < 5.3.7 if you're not on Windows.
  • Version 2.0.9 - 2017-03-03
    • More Psalm integration fixes.
  • Version 2.0.8 - 2017-03-03
    • Prevent function already declared error for random_int() caused by misusing the library (really you should only ever include lib/random.php and never any of the other files). See #125.
  • Version 2.0.6, 2.0.7 - 2017-02-27
    • Just updates to psalm.xml to silence false positives.
  • Version 2.0.5 - 2017-02-27
    • Run random_compat through the static analysis tool, psalm, as part of our continuous integration process.
    • Minor readability enhancements (#122 and several docblock changes).
  • Version 2.0.4 - 2016-11-07
    • Don't unnecessarily prevent mcrypt_create_iv() from being used. See #111.
  • Version 2.0.3 - 2016-10-17
  • Version 2.0.2 - 2016-04-03
    • Added a consistency check (discovered by Taylor Hornby in his PHP encryption library). It wasn't likely causing any trouble for us.
Other projects in PHP