1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
# random_compat
[](https://travis-ci.org/paragonie/random_compat)
[](https://scrutinizer-ci.com/g/paragonie/random_compat)
PHP 5.x polyfill for `random_bytes()` and `random_int()` created and maintained
by [Paragon Initiative Enterprises](https://paragonie.com).
Although this library *should* function in earlier versions of PHP, we will only
consider issues relevant to [supported PHP versions](https://secure.php.net/supported-versions.php).
**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](https://github.com/paragonie/random_compat/releases/latest).**
For the background of this library, please refer to our blog post on
[Generating Random Integers and Strings in PHP](https://paragonie.com/blog/2015/07/how-safely-generate-random-strings-and-integers-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](https://getcomposer.org):**
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`](https://github.com/paragonie/random_compat/releases/latest) 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](https://paragonie.com/static/gpg-public-key.txt).
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](https://github.com/paragonie/random_compat/releases/latest).
2. Extract the files into your project.
3. `require_once "/path/to/random_compat/lib/random.php";`
## Usage
This library exposes the [CSPRNG functions added in PHP 7](https://secure.php.net/manual/en/ref.csprng.php)
for use in PHP 5 projects. Their behavior should be identical.
### Generate a string of random bytes
```php
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)
```php
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
```php
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:
* [@AndrewCarterUK (Andrew Carter)](https://github.com/AndrewCarterUK)
* [@asgrim (James Titcumb)](https://github.com/asgrim)
* [@bcremer (Benjamin Cremer)](https://github.com/bcremer)
* [@CodesInChaos (Christian Winnerlein)](https://github.com/CodesInChaos)
* [@chriscct7 (Chris Christoff)](https://github.com/chriscct7)
* [@cs278 (Chris Smith)](https://github.com/cs278)
* [@cweagans (Cameron Eagans)](https://github.com/cweagans)
* [@dd32 (Dion Hulse)](https://github.com/dd32)
* [@geggleto (Glenn Eggleton)](https://github.com/geggleto)
* [@ircmaxell (Anthony Ferrara)](https://github.com/ircmaxell)
* [@jedisct1 (Frank Denis)](https://github.com/jedisct1)
* [@juliangut (Julián Gutiérrez)](https://github.com/juliangut)
* [@kelunik (Niklas Keller)](https://github.com/kelunik)
* [@lt (Leigh)](https://github.com/lt)
* [@MasonM (Mason Malone)](https://github.com/MasonM)
* [@mmeyer2k (Michael M)](https://github.com/mmeyer2k)
* [@narfbg (Andrey Andreev)](https://github.com/narfbg)
* [@nicolas-grekas (Nicolas Grekas)](https://github.com/nicolas-grekas)
* [@oittaa](https://github.com/oittaa)
* [@oucil (Kevin Farley)](https://github.com/oucil)
* [@redragonx (Stephen Chavez)](https://github.com/redragonx)
* [@rchouinard (Ryan Chouinard)](https://github.com/rchouinard)
* [@SammyK (Sammy Kaye Powers)](https://github.com/SammyK)
* [@scottchiefbaker (Scott Baker)](https://github.com/scottchiefbaker)
* [@skyosev (Stoyan Kyosev)](https://github.com/skyosev)
* [@stof (Christophe Coevoet)](https://github.com/stof)
* [@teohhanhui (Teoh Han Hui)](https://github.com/teohhanhui)
* [@tom-- (Tom Worster)](https://github.com/tom--)
* [@tsyr2ko](https://github.com/tsyr2ko)
* [@trowski (Aaron Piotrowski)](https://github.com/trowski)
* [@twistor (Chris Lepannen)](https://github.com/twistor)
* [@voku (Lars Moelleken)](https://github.com/voku)
* [@xabbuh (Christian Flothmann)](https://github.com/xabbuh)
|
