Convert Figma logo to code with AI

paragonie logorandom_compat

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

8,158
147
8,158
5
View on GitHub

Top Related Projects

defuse's avatar

php-encryption

3,777

Simple Encryption in PHP.

ramsey's avatar

uuid

12,433

:snowflake: A PHP library for generating universally unique identifiers (UUIDs).

brick's avatar

math

1,808

Arbitrary-precision arithmetic library for PHP

Quick Overview

paragonie/random_compat is a PHP library that provides a polyfill for the random_bytes() and random_int() functions introduced in PHP 7.0. It allows developers to use these secure random number generation functions in older PHP versions (5.x), ensuring better compatibility and security across different PHP environments.

Pros

  • Improves security by providing cryptographically secure random number generation for older PHP versions
  • Easy to integrate into existing projects
  • Well-maintained and regularly updated
  • Extensively tested across various PHP versions and platforms

Cons

  • Slightly slower performance compared to native PHP 7+ functions
  • Requires additional setup and configuration for older PHP versions
  • May not be necessary for projects exclusively using PHP 7.0 or newer
  • Potential compatibility issues with some hosting environments

Code Examples

  1. Generating a random byte string:
$randomBytes = random_bytes(16);
echo bin2hex($randomBytes);
  1. Generating a random integer within a specified range:
$min = 1;
$max = 100;
$randomInt = random_int($min, $max);
echo $randomInt;
  1. Creating a random token:
$token = bin2hex(random_bytes(32));
echo $token;

Getting Started

To use paragonie/random_compat in your project, follow these steps:

  1. Install the library using Composer:
composer require paragonie/random_compat
  1. Include the Composer autoloader in your PHP script:
require_once 'vendor/autoload.php';
  1. Use the random_bytes() and random_int() functions in your code:
$randomBytes = random_bytes(16);
$randomInt = random_int(1, 100);

That's it! The library will automatically provide the polyfill for older PHP versions when needed.

Competitor Comparisons

defuse logo

php-encryption

3,777

Simple Encryption in PHP.

Pros of php-encryption

  • Provides a complete encryption solution, including key management and secure data storage
  • Offers a higher-level API for easier implementation of encryption in PHP applications
  • Includes additional security features like authenticated encryption and key derivation

Cons of php-encryption

  • Larger codebase and more dependencies compared to random_compat
  • May have a steeper learning curve for developers new to cryptography
  • Potentially slower performance due to its comprehensive feature set

Code Comparison

random_compat:

$bytes = random_bytes(32);
$int = random_int(1, 100);

php-encryption:

use Defuse\Crypto\Key;
use Defuse\Crypto\Crypto;

$key = Key::createNewRandomKey();
$ciphertext = Crypto::encrypt($message, $key);

Summary

While random_compat focuses on providing secure random number generation for older PHP versions, php-encryption offers a more comprehensive cryptography solution. random_compat is lighter and easier to integrate for specific random number needs, while php-encryption provides a robust set of tools for implementing encryption in PHP applications. The choice between the two depends on the specific requirements of your project and the level of cryptographic functionality needed.

ramsey logo

uuid

12,433

:snowflake: A PHP library for generating universally unique identifiers (UUIDs).

Pros of UUID

  • Specialized for UUID generation, offering more UUID-specific features
  • Supports multiple UUID versions (v1, v3, v4, v5)
  • Provides additional utility methods for UUID manipulation

Cons of UUID

  • Larger library size, potentially increasing project footprint
  • May have more dependencies, increasing complexity
  • Focused solely on UUIDs, less versatile for general random number generation

Code Comparison

UUID:

use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid4();
echo $uuid->toString();

random_compat:

$bytes = random_bytes(16);
$hex = bin2hex($bytes);
echo sprintf('%s-%s-%s-%s-%s', substr($hex, 0, 8), substr($hex, 8, 4), substr($hex, 12, 4), substr($hex, 16, 4), substr($hex, 20));

Summary

UUID is a specialized library for generating and manipulating UUIDs, offering more UUID-specific features but with a larger footprint. random_compat is a more general-purpose library for secure random number generation, which can be used to create UUIDs but lacks built-in UUID-specific functionality. The choice between the two depends on the project's specific needs and constraints.

brick logo

math

1,808

Arbitrary-precision arithmetic library for PHP

Pros of Math

  • Focuses on arbitrary-precision arithmetic operations
  • Supports a wider range of mathematical functions and operations
  • Provides a more comprehensive mathematical library

Cons of Math

  • Larger library size and potentially higher resource usage
  • May have a steeper learning curve for basic operations
  • Not specifically designed for cryptographically secure random number generation

Code Comparison

Math:

use Brick\Math\BigInteger;

$result = BigInteger::of(2)->power(256)->minus(1);
echo $result->toBase(16);

Random_compat:

$bytes = random_bytes(32);
$hex = bin2hex($bytes);
echo $hex;

Summary

Math is a comprehensive arbitrary-precision arithmetic library, while Random_compat focuses on providing secure random number generation for older PHP versions. Math offers more mathematical operations but may be overkill for simple random number needs. Random_compat is more specialized and lightweight for cryptographic randomness but lacks advanced mathematical capabilities.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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:

# For libraries and frameworks that support PHP 5 but may be used by
# other software that only supports PHP 7:
composer require paragonie/random_compat:\>=2

# For software that explicitly needs PHP 5 support:
composer require paragonie/random_compat:\<9.99

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",
    ...
}

Version 9.99.99

Note: There is a special version called 9.99.99 which makes this library do nothing, but is only installable on PHP 7.

If you're writing software (e.g. a library) that supports PHP 5, but may be used by software that doesn't, you'll want to allow 9.99.99 to be installed. The above diff is what you want.

Conversely, if you're writing software that (in and of itself) supports PHP 5, you do not want 9.99.99 to be installed, so you'll want to make this change instead:

"require" {
    ...
-    "paragonie/random_compat": "~1.1",
+    "paragonie/random_compat": ">=1 <9.99",
    ...
}

To avoid installing "empty" version 9.99.99 you can add replace section in your root composer.json:

"replace": {
    "paragonie/random_compat": "9.99.99"
},

Manifest Read Length Error

If you're using the PHP Archive (Phar) approach rather than Composer, and you are getting an error message to the effect of "manifest read length was {int1} should be {int2}", the Phar extension may not be enabled.

See this comment for specific guidance on how to fix this issue.

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:

Support Contracts

If your company uses this library in their products or services, you may be interested in purchasing a support contract from Paragon Initiative Enterprises.