PHP Conference Japan 2024

random_bytes

(PHP 7, PHP 8)

random_bytesПолучает криптографически безопасные случайные байты

Описание

random_bytes(int $length): string

Функция создаёт строку, которая содержит равномерно выбранные случайные байты с запрошенной длиной length.

Поскольку возвращаемые байты выбираются совершенно случайно, полученная строка может содержать непечатаемые символы или недопустимые последовательности UTF-8. Может потребоваться её кодирование перед передачей или отображением.

Случайная последовательность, которую создаёт функция, подходит для всех приложений, включая генерацию долгосрочных секретов, таких как ключи шифрования.

Источники случайных величин в порядке приоритета:

  • 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, если CCRandomGenerateBytes доступен во время компиляции): 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

  • Любая комбинация операционной системы и версии PHP, не указанная раньше: /dev/urandom
  • Если ни один из источников не доступен или все они не генерируют случайную величину, то будет выброшено исключение Random\RandomException.

Замечание: Эта функция была добавлена в PHP 7.0, а для версий с 5.2 по 5.6 включительно доступна » пользовательская реализация.

Список параметров

length

Длина генерируемой строки в байтах; значение должно быть равно или больше 1.

Возвращаемые значения

Функция возвращает строку, которая состоит из заданного количества криптографически безопасных байтов.

Ошибки

  • Если подходящие источники случайных величин отсутствуют, то выбрасывается исключение Random\RandomException.
  • Если значение параметра length меньше 1, будет выброшена ошибка ValueError.

Список изменений

Версия Описание
8.2.0 В случае возникновения ошибки CSPRNG, функция теперь будет выбрасывать исключение Random\RandomException. Ранее выбрасывалось исключение Exception.

Примеры

Пример #1 Пример использования random_bytes()

<?php
$bytes
= random_bytes(5);
var_dump(bin2hex($bytes));
?>

Вывод приведённого примера будет похож на:

string(10) "385e33f741"

Смотрите также

  • Random\Randomizer::getBytes() - Получает случайные байты
  • random_int() - Получает криптографически безопасное равномерно выбранное целое число
  • bin2hex() - Преобразовывает двоичные данные в шестнадцатеричное представление
  • base64_encode() - Кодирует данные в формат MIME base64
Добавить

Примечания пользователей

Пользователи ещё не добавляли примечания для страницы
To Top