Kit SecureRandom

Gerador Aleatório Seguro

SecureRandom é uma biblioteca PHP para gerar números aleatórios seguros e usá-los para operações comuns de randomização, como embaralhar arrays ou gerar sequências de strings como senhas. Antes da versão 7.0, o PHP não possuía funções aleatórias seguras integradas, mas ainda era possível usar diferentes fontes de aleatoriedade para gerar valores aleatórios seguros. Assim, esta biblioteca tem dois propósitos principais:

• Fornecer uma interface comum para diferentes fontes de aleatoriedade segura em diferentes plataformas e versões de PHP
• Para tornar mais fácil o uso adequado das fontes de aleatoriedade para gerar valores aleatórios e realizar operações comuns de array aleatório.

Esta biblioteca não fornece nenhum gerador adicional de bytes aleatórios seguros. Ele simplesmente usa os geradores de bytes que estão disponíveis para o PHP por meio de extensões ou internamente. Os quatro geradores comumente disponíveis para PHP são:

• Funções CSPRNG fornecidas pelo PHP 7.0
• lendo do dispositivo aleatório /dev/(u)random
• chamando a função mcrypt_create_iv()
• chamando a função openssl_random_pseudo_bytes()

A segurança da aleatoriedade gerada por esta biblioteca depende inteiramente do gerador de bytes aleatórios subjacente. A biblioteca não faz nenhuma transformação adicional nos bytes além da normalização necessária para gerar distribuições pares de números aleatórios.

A documentação da API está disponível em: http://kit.riimu.net/api/securerandom/

Requisitos

• A versão mínima do PHP suportada é 5.6
• A biblioteca depende das seguintes extensões PHP
  • OpenSSL (para usar o gerador OpenSSQL)
  • Mcrypt (para usar o gerador Mcrypt)
• O /dev/urandom deve ser legível para usar o gerador de leitor aleatório

Instalação

Instalação com Composer

A maneira mais fácil de instalar esta biblioteca é usar o Composer para lidar com suas dependências. Para instalar esta biblioteca via Composer, basta seguir estes dois passos:

1. Adquira o composer.phar executando a instalação da linha de comando do Composer na raiz do seu projeto.

2. Depois de executar o script de instalação, você deverá ter o arquivo composer.phar na raiz do projeto e poderá executar o seguinte comando:

    php composer.phar require "riimu/kit-securerandom:^1.3"
   

Após instalar esta biblioteca via Composer, você pode carregá-la incluindo o arquivo vendor/autoload.php que foi gerado pelo Composer durante a instalação.

Adicionando a biblioteca como uma dependência

Se você já está familiarizado com o uso do Composer, você pode alternativamente adicionar a biblioteca como uma dependência adicionando o seguinte arquivo composer.json ao seu projeto e executando o comando composer install :

{
    "require" : {
        "riimu/kit-securerandom" : " ^1.3 "
    }
}

Instalação manual

Se não desejar usar o Composer para carregar a biblioteca, você também pode fazer o download da biblioteca manualmente, baixando a versão mais recente e extraindo a pasta src para o seu projeto. Você pode então incluir o arquivo src/autoload.php fornecido para carregar as classes da biblioteca.

Uso

O uso da biblioteca é muito simples. Basta criar uma instância do SecureRandom e chamar qualquer um dos métodos para gerar valores aleatórios. Por exemplo:

 <?php

require ' vendor/autoload.php ' ;
$ rng = new  Riimu  Kit  SecureRandom  SecureRandom ();

var_dump ( base64_encode ( $ rng -> getBytes ( 32 )));     // Returns a random byte string
var_dump ( $ rng -> getInteger ( 100 , 1000 ));           // Returns a random integer between 100 and 1000
var_dump ( $ rng -> getFloat ());                      // Returns a random float between 0 and 1
var_dump ( $ rng -> getRandom ());                     // Returns a random float between 0 and 1 (not including 1)
var_dump ( $ rng -> getArray ( range ( 0 , 100 ), 5 ));      // Returns 5 randomly selected elements from the array
var_dump ( $ rng -> choose ( range ( 0 , 100 )));           // Returns one randomly chosen value from the array
var_dump ( $ rng -> shuffle ( range ( 0 , 9 )));            // Returns the array in random order
var_dump ( $ rng -> getSequence ( ' 01 ' , 32 ));           // Returns a random sequence of 0s and 1s with length of 32
var_dump ( $ rng -> getSequence ([ ' a ' , ' b ' , ' c ' ], 5 )); // Returns an array with 5 elements randomly chosen from 'a', 'b', and 'c'
var_dump ( $ rng -> getUuid ());                       // Returns a random version UUID, e.g. '00056a74-036b-47c5-ab35-6f34a41a70ae'

Métodos aleatórios

Os seguintes métodos estão disponíveis em SecureRandom para recuperar aleatoriedade:

• getBytes($count) retorna uma string de bytes aleatórios com comprimento igual a $count.

• getInteger($min, $max) retorna um número inteiro aleatório entre os dois números inteiros positivos fornecidos (inclusive).

• getFloat() retorna um valor flutuante aleatório entre 0 e 1 (inclusive).

• getRandom() retorna um valor flutuante aleatório entre 0 e 1 que tem 52 bits de precisão e de forma que o valor retornado é sempre menor que 1. Em comparação com getFloat() , a distribuição de valores é mais uniforme e não depende de PHP_INT_MAX .

• getArray(array $array, $count) retorna um número de elementos aleatórios de um determinado array. Os elementos estão em ordem aleatória, mas as chaves são preservadas.

• choose(array $array) retorna um valor aleatório escolhido no array.

• shuffle(array $array) retorna o array em ordem aleatória. As chaves são preservadas.

• getSequence($choices, $length) retorna uma sequência aleatória de valores ou caracteres. As opções podem ser fornecidas como uma string ou uma matriz. O tipo do valor de retorno depende do tipo de escolhas.

• getUuid() retorna um identificador universalmente exclusivo da versão 4 aleatória. UUIDs são identificadores exclusivos que podem ser gerados aleatoriamente, de forma independente e têm probabilidade muito pequena de colisão. E um exemplo de UUID poderia ser 00056a74-036b-47c5-ab35-6f34a41a70ae .

Notas sobre /dev/random

Os geradores fornecidos por esta biblioteca usam /dev/urandom como fonte de aleatoriedade por padrão. A leitura de /dev/random não fornece segurança adicional para aplicativos web PHP típicos e sua natureza de bloqueio o tornaria muito inadequado para tais propósitos.

Existem apenas alguns casos legítimos em que você deve ler /dev/random . Isso ocorre principalmente se você estiver preocupado porque /dev/urandom ainda não foi propagado corretamente. No entanto, esse normalmente não é o caso de aplicativos da Web, pois isso tende a ocorrer apenas na inicialização do sistema.

Se você sabe que é absolutamente necessário ler /dev/random é possível configurar o RandomReader e Mcrypt para usá-lo como fonte de aleatoriedade, definindo o parâmetro do construtor como false e fornecendo o gerador para SecureRandom no construtor. Por exemplo:

 <?php

require ' vendor/autoload.php ' ;
$ generator = new  Riimu  Kit  SecureRandom  Generator  RandomReader ( false );
$ rng = new  Riimu  Kit  SecureRandom  SecureRandom ( $ generator );

Geradores aleatórios disponíveis

Quando SecureRandom for criado, ele tentará usar um dos geradores aleatórios seguros disponíveis, dependendo de qual deles for suportado pela plataforma atual. As seguintes fontes aleatórias estão disponíveis e serão testadas na seguinte ordem:

• GeneratorInternal usa as funções internas disponíveis no PHP 7.0
• GeneratorRandomReader simplesmente lê bytes do dispositivo aleatório /dev/urandom
• GeneratorMcrypt usa mcrypt_create_iv() para gerar bytes aleatórios usando MCRYPT_DEV_URANDOM como fonte.
• GeneratorOpenSSL usa openssl_random_pseudo_bytes() para gerar bytes aleatórios.

Tem havido algum debate sobre se o algoritmo usado pelo OpenSSL é realmente criptograficamente forte ou não. No entanto, devido à falta de evidências concretas contra ela e devido às implicações de sua força no manual do PHP, esta biblioteca usará OpenSSL como último recurso por padrão para obter melhor compatibilidade entre diferentes plataformas.

Se você deseja definir explicitamente o gerador de bytes, você pode fornecê-lo como parâmetro construtor para SecureRandom . Por exemplo:

 <?php

require ' vendor/autoload.php ' ;
$ rng = new  Riimu  Kit  SecureRandom  SecureRandom (
    new  Riimu  Kit  SecureRandom  Generator  Mcrypt ()
);

Créditos

Esta biblioteca tem Copyright (c) 2014-2017 Riikka Kalliomäki.

Consulte LICENÇA para obter informações sobre licença e cópia.