Riimu\Kit\SecureRandom\SecureRandom

Complexity

Total Complexity

34

Size/Duplication

Total Lines	266
Duplicated Lines	0 %

Coupling/Cohesion

Components	2
Dependencies	3

Test Coverage

Coverage

100%

Importance

Changes	12
Bugs	4	Features	2

12 Methods

Rating	Name	Duplication	Size	Complexity
A	__construct()	0	10	3
A	getDefaultGenerator()	0	12	3
A	getBytes()	0	12	3
A	getNumber()	0	10	3
A	getByteNumber()	0	14	3
A	getInteger()	0	11	3
A	getFloat()	0	4	1
A	getArray()	0	19	4
A	choose()	0	8	2
A	shuffle()	0	4	1
A	getSequence()	0	16	4
A	getSequenceValues()	0	17	4

<?php

namespace Riimu\Kit\SecureRandom;

use Riimu\Kit\SecureRandom\Generator\Generator;
use Riimu\Kit\SecureRandom\Generator\NumberGenerator;

/**
 * Library for normalizing bytes returned by secure random byte generators.
 *
 * SecureRandom takes bytes generated by secure random byte generators and
 * normalizes (i.e. provides even distribution) for other common usages, such
 * as generation of integers, floats and randomizing arrays.
 *
 * @author Riikka Kalliomäki <riikka.kalliomaki@gmail.com>
 * @copyright Copyright (c) 2014, Riikka Kalliomäki
 * @license http://opensource.org/licenses/mit-license.php MIT License
 */
class SecureRandom
{
    /** @var Generator The secure random byte generator used to generate bytes */
    private $generator;

    /** @var string[] List of default generators */
    private static $defaultGenerators = [
        '\Riimu\Kit\SecureRandom\Generator\Internal',
        '\Riimu\Kit\SecureRandom\Generator\RandomReader',
        '\Riimu\Kit\SecureRandom\Generator\Mcrypt',
        '\Riimu\Kit\SecureRandom\Generator\OpenSSL',
    ];

    /**
     * Creates a new instance of SecureRandom.
     *
     * You can either provide a generator to use for generating random bytes or
     * give null as the argument to use default generators. If null is provided,
     * the constructor will attempt to create the random byte generators in the
     * following order until it finds one that is supported:
     *
     * - Internal
     * - RandomReader
     * - Mcrypt
     * - OpenSSL
     *
     * Note that since most cases require non-blocking random generation, the
     * default generators use /dev/urandom as the random source. If you do not
     * think this provides enough security, create the desired random generator
     * using /dev/random as the source.
     *
     * @param Generator|null $generator Random byte generator or null for default
     * @throws GeneratorException If the provided or default generators are not supported
     */
    public function __construct(Generator $generator = null)
    {
        if ($generator === null) {
            $generator = $this->getDefaultGenerator();
        } elseif (!$generator->isSupported()) {
            throw new GeneratorException('The provided secure random byte generator is not supported by the system');
        }

        $this->generator = $generator;
    }

    /**
     * Returns the first supported default secure random byte generator.
     * @return Generator Supported secure random byte generator
     * @throws GeneratorException If none of the default generators are supported
     */
    private function getDefaultGenerator()
    {
        foreach (self::$defaultGenerators as $generator) {
            $generator = new $generator();

            if ($generator->isSupported()) {
                return $generator;
            }
        }

        throw new GeneratorException('Default secure random byte generators are not supported by the system');
    }

    /**
     * Returns a number of random bytes.
     * @param int $count Number of random bytes to return
     * @return string Randomly generated bytes
     * @throws \InvalidArgumentException If the count is invalid
     */
    public function getBytes($count)
    {
        $count = (int) $count;

        if ($count < 0) {
            throw new \InvalidArgumentException('Number of bytes must be 0 or more');
        } elseif ($count === 0) {
            return '';
        }

        return $this->generator->getBytes($count);
    }

    /**
     * Returns a random number between 0 and the limit.
     * @param int $limit Maximum random number
     * @return int Random number between 0 and the limit
     */
    private function getNumber($limit)
    {
        if ($limit === 0) {
            return 0;
        } elseif ($this->generator instanceof NumberGenerator) {
            return $this->generator->getNumber(0, $limit);
        }

        return $this->getByteNumber($limit);
    }

    /**
     * Returns a random number generated using the random byte generator.
     * @param int $limit Maximum value for the random number
     * @return int The generated random number between 0 and the limit
     */
    private function getByteNumber($limit)
    {
        for ($bits = 1, $mask = 1; $limit >> $bits > 0; $bits++) {
            $mask |= 1 << $bits;
        }

        $bytes = (int) ceil($bits / 8);

        do {
            $result = hexdec(bin2hex($this->generator->getBytes($bytes))) & $mask;
        } while ($result > $limit);

        return $result;
    }

    /**
     * Returns a random integer between two positive integers (inclusive).
     * @param int $min Minimum limit
     * @param int $max Maximum limit
     * @return int Random integer between minimum and maximum limit
     * @throws \InvalidArgumentException If the limits are invalid
     */
    public function getInteger($min, $max)
    {
        $min = (int) $min;
        $max = (int) $max;

        if ($min < 0 || $max < $min) {
            throw new \InvalidArgumentException('Invalid minimum or maximum value');
        }

        return $min + $this->getNumber($max - $min);
    }

    /**
     * Returns a random float between 0 and 1 (inclusive).
     * @return float Random float between 0 and 1
     */
    public function getFloat()
    {
        return (float) ($this->getNumber(PHP_INT_MAX) / PHP_INT_MAX);
    }

    /**
     * Returns a number of randomly selected elements from the array.
     *
     * This method returns randomly selected elements from the array. The number
     * of elements is determined by by the second argument. The elements are
     * returned in random order but the keys are preserved.
     *
     * @param array $array Array of elements
     * @param int $count Number of elements to return from the array
     * @return array Randomly selected elements in random order
     * @throws \InvalidArgumentException If the count is invalid
     */
    public function getArray(array $array, $count)
    {
        $count = (int) $count;
        $size = count($array);

        if ($count < 0 || $count > $size) {
            throw new \InvalidArgumentException('Invalid number of elements');
        }

        $result = [];

        for ($i = 0; $i < $count; $i++) {
            $element = array_slice($array, $this->getNumber($size - $i - 1), 1, true);
            $result += $element;
            unset($array[key($element)]);
        }

        return $result;
    }

    /**
     * Returns one randomly selected value from the array.
     * @param array $array Array to choose from
     * @return mixed One randomly selected value from the array
     * @throws \InvalidArgumentException If the array is empty
     */
    public function choose(array $array)
    {
        if (count($array) < 1) {
            throw new \InvalidArgumentException('Array must have at least one value');
        }

        return current(array_slice($array, $this->getNumber(count($array) - 1), 1));
    }

    /**
     * Returns the array with the elements reordered in random order.
     * @param array $array Array to shuffle
     * @return array The provided array with elements in random order
     */
    public function shuffle(array $array)
    {
        return $this->getArray($array, count($array));
    }

    /**
     * Returns a random sequence of values.
     *
     * If a string is provided as the first argument, the method returns a
     * string with characters selected from the provided string. The length of
     * the returned string is determined by the second argument.
     *
     * If an array is provided as the first argument, the method returns an
     * array with elements selected from the provided array. The size of the
     * returned array is determined by the second argument.
     *
     * The functionality is similar to getArray(), except for the fact that the
     * returned value can contain the same character or element multiple times.
     * If the same character or element appears multiple times in the provided
     * argument, it will increase the relative chance of it appearing in the
     * returned value.
     *
     * @param string|array $choices Values to choose from
     * @param int $length Length of the sequence
     * @return array|string The generated random sequence
     * @throws \InvalidArgumentException If the choices or length is invalid
     */
    public function getSequence($choices, $length)
    {
        $length = (int) $length;
        $string = is_string($choices);

        if ($length < 0) {
            throw new \InvalidArgumentException('Invalid sequence length');
        }

        $result = $this->getSequenceValues(
            $string ? str_split($choices) : array_values($choices),
            $length
        );

        return $string ? implode('', $result) : $result;
    }

    /**
     * Returns the selected list of values for the sequence.
     * @param array $values List of possible values
     * @param int $length Number of values to return
     * @return array Selected list of values for the sequence
     */
    private function getSequenceValues(array $values, $length)
    {
        if ($length < 1) {
            return [];
        } elseif (count($values) < 1) {
            throw new \InvalidArgumentException('Cannot generate sequence from empty value set');
        }

        $size = count($values);
        $result = [];

        for ($i = 0; $i < $length; $i++) {
            $result[] = $values[$this->getNumber($size - 1)];
        }

        return $result;
    }
}