README

SecureRandom 是一个PHP库，用于生成安全随机数，并用于常见的随机化操作，如洗牌数组或生成密码等字符串序列。在版本7.0之前，PHP没有内置的安全随机函数，但仍然可以使用不同的随机源生成安全随机值。因此，这个库有两个主要目的

提供不同平台和PHP版本之间安全随机源的共同接口
使正确使用随机源生成随机值和执行常见随机数组操作变得更容易。

这个库不提供任何额外的安全随机字节生成器。它仅使用通过扩展或内部提供的字节生成器。PHP通常可用的四种生成器是

PHP 7.0提供的CSPRNG函数
从随机设备 /dev/(u)random 读取
调用 mcrypt_create_iv() 函数
调用 openssl_random_pseudo_bytes() 函数

此库生成的随机性的安全性完全取决于底层随机字节生成器。除了生成随机数均匀分布所需的标准化外，库不会对字节进行任何其他转换。

API文档可在以下位置查看： http://kit.riimu.net/api/securerandom/

要求

最低支持的PHP版本是5.6
该库依赖于以下PHP扩展
- OpenSSL（使用OpenSSQL生成器）
- Mcrypt（使用Mcrypt生成器）
必须可读 /dev/urandom 以使用随机读取生成器

安装

使用Composer安装

安装此库最简单的方法是使用Composer来处理依赖项。要使用Composer安装此库，只需按照以下两个步骤操作

通过在项目根目录中运行Composer的命令行安装获取 composer.phar。
运行安装脚本后，您应该在项目根目录中拥有 composer.phar 文件，并且可以运行以下命令
```
php composer.phar require "riimu/kit-securerandom:^1.3"
```

通过Composer安装此库后，您可以通过包含Composer在安装过程中生成的 vendor/autoload.php 文件来加载库。

将库作为依赖项添加

如果您已经熟悉如何使用Composer，您还可以通过将以下 composer.json 文件添加到项目中并运行 composer install 命令来将库作为依赖项添加

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

手动安装

如果您不想使用Composer加载库，您也可以通过下载最新版本并将 src 文件夹提取到项目中来自动下载库。然后，您可以包含提供的 src/autoload.php 文件来加载库类。

用法

库的用法非常简单。只需创建一个SecureRandom实例，然后调用任何方法来生成随机值。例如

<?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'

随机方法

SecureRandom中提供了以下方法来获取随机数

getBytes($count)返回一个长度等于$count的随机字节字符串。
getInteger($min, $max)返回两个给定的正整数（包括）之间的随机整数。
getFloat()返回一个介于0和1之间的随机浮点值（包括）。
getRandom()返回一个介于0和1之间的随机浮点值，具有52位精度，并且返回的值总是小于1。与getFloat()相比，值分布更均匀，不依赖于PHP_INT_MAX。
getArray(array $array, $count)从给定的数组中返回一定数量的随机元素。元素顺序是随机的，但键被保留。
choose(array $array)从数组中返回一个随机值。
shuffle(array $array)返回一个随机顺序的数组。键被保留。
getSequence($choices, $length)返回一个随机值或字符序列。选择可以是字符串或数组。返回值的类型取决于选择的类型。
getUuid()返回一个随机的版本4 通用唯一标识符。UUID是随机生成的唯一标识符，可以独立生成，碰撞的可能性非常小。一个UUID的例子可能是00056a74-036b-47c5-ab35-6f34a41a70ae。

关于/dev/random的注意事项

此库默认使用/dev/urandom作为随机数源。从/dev/random读取不会为典型的PHP Web应用程序提供额外的安全性，其阻塞性质会使它非常不适合此类用途。

只有少数合法情况下你应该从/dev/random读取。这主要是在你担心/dev/urandom尚未正确初始化的情况下。然而，这对于Web应用程序通常不是问题，因为这个问题通常只在系统启动时出现。

如果你知道你绝对需要从/dev/random读取，你可以通过将构造函数参数设置为false并提供生成器到SecureRandom中，将RandomReader和Mcrypt设置为使用它作为随机数源。例如

<?php

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

可用的随机生成器

创建SecureRandom时，它将尝试使用当前平台支持的可用安全随机生成器之一。以下随机源可用，它们将按以下顺序尝试

Generator\Internal使用PHP 7.0中可用的内部函数
Generator\RandomReader简单地从随机设备/dev/urandom读取字节
Generator\Mcrypt使用mcrypt_create_iv()，使用MCRYPT_DEV_URANDOM作为源来生成随机字节
Generator\OpenSSL使用openssl_random_pseudo_bytes()来生成随机字节

关于OpenSSL使用的算法是否真正具有密码学强度，有一些争议。然而，由于缺乏针对它的具体证据，以及它在PHP手册中的强度影响，此库默认将使用OpenSSL作为最后的回退，以实现跨不同平台更好的兼容性。

如果你希望明确定义字节数据生成器，你可以将其作为构造函数参数提供给SecureRandom。例如

<?php

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

鸣谢

请参阅LICENSE以获取许可和复制信息。

riimu / kit-securerandom

维护者

详情