paragonie/seedspring

Seeded, deterministic random number generator

v1.2.1 2024-05-08 16:49 UTC

Requires

• php: >= 5.6
• ext-openssl: *
• paragonie/constant_time_encoding: ^1|^2|^3
• paragonie/random_compat: >=2

Requires (Dev)

• phpunit/phpunit: ^5|^6|^7|^8|^9
• vimeo/psalm: ^1|^2|^3|^4

MIT

• Paragon Initiative Enterprises

README

Seeded, Deterministic PRNG (based on AES-CTR instead of LCG) (Requires PHP 7 or random_compat)

Security Warning

This is not meant to replace random_bytes(). Think of this as an improvement to srand() + rand(). Do not use this for security purposes.

Installing

composer require paragonie/seedspring

Usage

use \ParagonIE\SeedSpring\SeedSpring;

// For example
$sharedSeed = str_repeat("\x80", 16);

$rng = new SeedSpring($sharedSeed);

$data = $rng->getBytes(1024);
$int = $rng->getInt(1, 100);

Motivation

A cryptographically secure pseudorandom number generator, such as random_int(), is wonderful for security purposes. However, there are situations where you need to generate a deterministic, pseudorandom byte stream on two devices from a shared seed. (e.g. something like Minecraft's world generator).

PHP's native seedable (and insecure) RNGs, rand() and mt_rand(), only support a 32-bit integer seed, which severely limits the possible outputs. Our deterministic RNG supports up to 2^128 possible outputs, since it's based on a 128-bit block cipher.

Our implementation uses AES-128-CTR to turn a finite, 128-bit key into an practically endless stream of random bytes.

It will repeat after 2^132 bytes of output. You should consider rekeying after 2^66 bytes.

For anything security-sensitive, you should rekey after 2^39 bytes. This is because the probability of predicting successive blocks becomes unacceptably high for security operations.