random_bytes

(PHP 7, PHP 8)

random_bytes — Obtém bytes aleatórios criptograficamente seguros

Descrição

random_bytes(int $length): string

Gera uma string contendo bytes aleatórios selecionados uniformemente com o comprimento solicitado em length.

Como os bytes retornados são selecionados de forma completamente aleatória, é provável que a string resultante contenha caracteres não imprimíveis ou sequências UTF-8 inválidas. Pode ser necessário codificá-la antes da transmissão ou exibição.

A aleatoriedade gerada por esta função é adequada para todas as aplicações, incluindo a geração de segredos de longo prazo, como chaves de criptografia.

As fontes de aleatoriedade usadas para esta função são as seguintes:

  • 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 se CCRandomGenerateBytes estiver disponível em tempo de compilação): 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

  • Qualquer combinação de sistema operacional e versão do PHP não mencionada anteriormente: /dev/urandom
  • Se nenhuma das fontes estiver disponível ou todas falharem em gerar aleatoriedade, então uma exceção Random\RandomException será lançada.

Note: Embora esta função tenha sido adicionada ao PHP no PHP 7.0, uma » implementação no espaço do usuário está disponível para o PHP 5.2 ao 5.6, inclusive.

Parâmetros

length

O comprimento da sequência aleatória que deve ser retornada em bytes; deve ser 1 ou superior.

Valor Retornado

Uma string contendo o número solicitado de bytes aleatórios criptograficamente seguros.

Erros/Exceções

  • Se uma fonte apropriada de aleatoriedade não puder ser encontrada, uma exceção Random\RandomException será lançada.
  • Se o valor de length for menor que 1, um ValueError será lançado.

Registro de Alterações

Versão Descrição
8.2.0 No caso de uma falha de CSPRNG, esta função agora lançará uma Random\RandomException. Anteriormente, uma Exception simples era lançada.

Exemplos

Example #1 Exemplo de random_bytes()

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

O exemplo acima produzirá algo semelhante a:

string(10) "385e33f741"

Veja Também