riimu/kit-securerandom

利用现有安全随机生成器的库

v1.3.1 2017-09-09 15:23 UTC

This package is auto-updated.

Last update: 2024-09-19 20:28:14 UTC


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/

Travis Scrutinizer Scrutinizer Coverage Packagist

要求

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

安装

使用Composer安装

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

  1. 通过在项目根目录中运行Composer的 命令行安装 获取 composer.phar

  2. 运行安装脚本后,您应该在项目根目录中拥有 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中,将RandomReaderMcrypt设置为使用它作为随机数源。例如

<?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以获取许可和复制信息。