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