1## Rand
2
3The `Rand` class provides set of static functions for getting
4random values. It includes functions for adding entropy to
5the PRNG algorithm.
6
7### Static Methods
8
9#### `Rand::generate($num, $must_be_strong, &$returned_strong_result)`
10
11_**Description**_: Generates and returns random data
12
13The `Rand::generate` method generates data from seeded buffer.
14The buffer is seeded automatically when the extension is initialized.
15Entropy can be added using `Rand::seed`.
16
17The second parameter `$must_be_strong`, whose default value is true,
18specify whether the returned bytes are cryptographically strong
19pseudo-random bytes. If it's `false`, then information whether
20the bytes are strong is saved in the third parameter. If it's `true`
21and data are not strong, a `RandException` is thrown
22
23When using a default Rand implementation on Linux or BSD, then it's
24very unlikely to get bytes that are not strong. It means that
25the second and third parameters can be ignored and just
26specify `$num` and then possibly handle an exception.
27
28##### *Parameters*
29
30*num* : `int` - the number of bytes that are returned (string length)
31*must_be_strong* : `bool` - whether the result has to be strong -
32default is `true`
33*returned_strong_result* : `bool` reference - output variable
34which stores information whether the generated result is strong
35
36##### *Return value*
37
38`string`: Random data.
39
40##### *Throws*
41
42It can throw `RandException` with code
43
44- `RandException::REQUESTED_BYTES_NUMBER_TOO_HIGH` - if the number
45of requested random bytes (`$num`) is greater than C `INT_MAX`
46- `RandException::GENERATE_PREDICTABLE` - if `$must_be_strong`
47is `true` and the returned result is not strong.
48
49##### *Examples*
50
51```php
52$iv = \Crypto\Rand::generate(16);
53```
54
55#### `Rand::seed($buf, $entropy)`
56
57_**Description**_: Mixes supplied data into the PRNG state
58
59This method mixes data in `$buf` into the internal PRNG state. It
60means that it's not an actual seeding on its own but more adding
61an extra entropy. The estimated value of entropy can be supplied
62as the second parameter `$entropy`. If it's not specified, then
63length of the buffer is used.
64
65##### *Parameters*
66
67*buf* : `int` - a buffer to be mixed into the PRNG state
68*entropy* : `float` - estimated entropy of the data in `$buf`
69
70##### *Return value*
71
72`null`: Nothing is returned.
73
74##### *Throws*
75
76It can throw `RandException` with code
77
78- `RandException::SEED_LENGTH_TOO_HIGH` - if the length of
79the buffer is greater than C `INT_MAX`
80
81##### *Examples*
82
83```php
84\Crypto\Rand::seed($buf);
85```
86
87#### `Rand::cleanup()`
88
89_**Description**_: Erases the PRNG state
90
91This method globally erases the memory that is used by PRNG.
92
93##### *Parameters*
94
95This method has no parameters.
96
97##### *Throws*
98
99This method does not throw any exception.
100
101##### *Return value*
102
103`null`: Nothing is returned.
104
105##### *Examples*
106
107```php
108\Crypto\Rand::cleanup();
109```
110
111#### `Rand::loadFile($filename, $max_bytes)`
112
113_**Description**_: Reads data from file and mixes them to the PRNG
114state
115
116This method mixes data from the file in `$filename` into
117the internal PRNG state. It reads at most `$max_bytes` bytes.
118
119##### *Parameters*
120
121*filename* : `string` - file path of the file that is read
122*max_bytes* : `int` - maximal number of bytes that is read
123from file
124
125##### *Return value*
126
127`int`: The number of bytes read.
128
129##### *Throws*
130
131It can throw `RandException` with code
132
133- `RandException::REQUESTED_BYTES_NUMBER_TOO_HIGH` - if the supplied
134`$max_bytes` is greater than C `INT_MAX`
135
136##### *Examples*
137
138```php
139\Crypto\Rand::loadFile($filename, 1024);
140```
141
142#### `Rand::writeFile($filename)`
143
144_**Description**_: Writes random bytes to the file
145
146This method writes 1024 bytes the the file `$filename`. It
147can be used later to initial PRNG state by calling
148`Rand::load`.
149
150##### *Parameters*
151
152*filename* : `string` - file path of the file where
153random data are written.
154
155##### *Return value*
156
157`int`: The number of bytes read.
158
159##### *Throws*
160
161It can throw `RandException` with code
162
163- `RandException::REQUESTED_BYTES_NUMBER_TOO_HIGH` - if the written
164bytes were generated without appropriate seed.
165
166##### *Examples*
167
168```php
169\Crypto\Rand::writeFile($filename);
170```
171