PHP: Hypertext Preprocessor (original) (raw)
random_bytes
(PHP 7, PHP 8)
random_bytes — Get cryptographically secure random bytes
Description
As the returned bytes are selected completely randomly, the resulting string is likely to contain unprintable characters or invalid UTF-8 sequences. It may be necessary to encode it before transmission or display.
The randomness generated by this function is suitable for all applications, including the generation of long-term secrets, such as encryption keys.
The sources of randomness in the order of priority are as follows:
- Linux: » getrandom(), /dev/urandom
- FreeBSD >= 12 (PHP >= 7.3): » getrandom(), /dev/urandom
- Windows (PHP >= 7.2): » CNG-API
Windows: » CryptGenRandom - macOS (PHP >= 8.2; >= 8.1.9; >= 8.0.22 if CCRandomGenerateBytes is available at compile time): CCRandomGenerateBytes()
macOS (PHP >= 8.1; >= 8.0.2): arc4random_buf(), /dev/urandom - NetBSD >= 7 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom
- OpenBSD >= 5.5 (PHP >= 7.1; >= 7.0.1): arc4random_buf(), /dev/urandom
- DragonflyBSD (PHP >= 8.1): » getrandom(), /dev/urandom
- Solaris (PHP >= 8.1): » getrandom(), /dev/urandom
- Any combination of operating system and PHP version not previously mentioned: /dev/urandom
- If none of the sources are available or they all fail to generate randomness, then a Random\RandomException will be thrown.
Note: Although this function was added to PHP in PHP 7.0, a» userland implementation is available for PHP 5.2 to 5.6, inclusive.
Parameters
length
The length of the random string that should be returned in bytes; must be 1 or greater.
Return Values
A string containing the requested number of cryptographically secure random bytes.
Errors/Exceptions
- If an appropriate source of randomness cannot be found, a Random\RandomException will be thrown.
- If the value of
lengthis less than1, a ValueError will be thrown.
Changelog
| Version | Description |
|---|---|
| 8.2.0 | In case of a CSPRNG failure, this function will now throw aRandom\RandomException. Previously a plainException was thrown. |
Examples
Example #1 random_bytes() example
<?php $bytes = random_bytes(5); var_dump(bin2hex($bytes)); ?>
The above example will output something similar to:
See Also
- Random\Randomizer::getBytes() - Get random bytes
- random_int() - Get a cryptographically secure, uniformly selected integer
- bin2hex() - Convert binary data into hexadecimal representation
- base64_encode() - Encodes data with MIME base64