riimu / kit-securerandom
利用现有安全随机生成器的库
Requires
- php: >=5.6.0
Requires (Dev)
- phpunit/phpunit: ^6.3 || ^5.7
Suggests
- ext-mcrypt: To use the Mcrypt secure random byte generator
- ext-openssl: To use the OpenSSL secure random byte generator
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/
要求
安装
使用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() );
鸣谢
此库版权所有(c)2014-2017 Riikka Kalliomäki。
请参阅LICENSE以获取许可和复制信息。