<?php
/**
* @version	$Id: SecurityGenerator.php 16691 2021-03-18 14:29:44Z alex $
* @package	In-Portal
* @copyright	Copyright (C) 1997 - 2018 Intechnic. All rights reserved.
* @license      GNU/GPL
* In-Portal is Open Source software.
* This means that this software may have been modified pursuant
* the GNU General Public License, and as distributed it includes
* or is derivative of works licensed under the GNU General Public License
* or other free or open source software licenses.
* See http://www.in-portal.org/license for copyright notices and details.
*/

defined('FULL_PATH') or die('restricted access!');


final class SecurityGenerator
{

	/**
	 * Flag for uppercase letters.
	 */
	const CHAR_UPPER = 1;

	/**
	 * Flag for lowercase letters.
	 */
	const CHAR_LOWER = 2;

	/**
	 * Flag for alpha characters (CHAR_UPPER | CHAR_LOWER).
	 */
	const CHAR_ALPHA = 3;

	/**
	 * Flag for digits.
	 */
	const CHAR_DIGITS = 4;

	/**
	 * Flag for alpha numeric characters (CHAR_ALPHA | CHAR_DIGITS).
	 */
	const CHAR_ALNUM = 7;

	/**
	 * Flag for uppercase hexadecimal symbols (8 | CHAR_DIGITS).
	 */
	const CHAR_UPPER_HEX = 12;

	/**
	 * Flag for lowercase hexidecimal symbols (16 | CHAR_DIGITS).
	 */
	const CHAR_LOWER_HEX = 20;

	/**
	 * Flag for base64 symbols (32 | CHAR_ALNUM).
	 */
	const CHAR_BASE64 = 39;

	/**
	 * Flag for additional symbols accessible via the keyboard.
	 */
	const CHAR_SYMBOLS = 64;

	/**
	 * Flag for brackets.
	 */
	const CHAR_BRACKETS = 128;

	/**
	 * Flag for punctuation marks.
	 */
	const CHAR_PUNCT = 256;

	/**
	 * Flag for upper/lower-case and digits but without "B8G6I1l|0OQDS5Z2".
	 */
	const EASY_TO_READ = 512;

	/**
	 * Ambiguous characters for "Easy To Read" sets.
	 *
	 * @internal
	 */
	const AMBIGUOUS_CHARS = 'B8G6I1l|0OQDS5Z2()[]{}:;,.';

	/**
	 * The different characters, by Flag.
	 *
	 * @var array
	 */
	static protected $charArrays = array(
		self::CHAR_UPPER => 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
		self::CHAR_LOWER => 'abcdefghijklmnopqrstuvwxyz',
		self::CHAR_DIGITS => '0123456789',
		self::CHAR_UPPER_HEX => 'ABCDEF',
		self::CHAR_LOWER_HEX => 'abcdef',
		self::CHAR_BASE64 => '+/',
		self::CHAR_SYMBOLS => '!"#$%&\'()* +,-./:;<=>?@[\]^_`{|}~',
		self::CHAR_BRACKETS => '()[]{}<>',
		self::CHAR_PUNCT => ',.;:',
	);

	/**
	 * Generate a random string of specified length using supplied character list.
	 *
	 * @param integer $length     The length of the generated string.
	 * @param mixed   $characters List of characters to use or character flags.
	 *
	 * @return SecurityGeneratorPromise
	 */
	public static function generateString($length, $characters)
	{
		// Combine character sets.
		if ( is_int($characters) ) {
			$characters = self::expandCharacterSets($characters);
		}

		return new SecurityGeneratorPromise(
			SecurityGeneratorPromise::TYPE_STRING,
			array($length, $characters)
		);
	}

	/**
	 * Expand a character set bitwise spec into a string character set.
	 * This will also replace EASY_TO_READ characters if the flag is set.
	 *
	 * @param integer $spec The spec to expand (bitwise combination of flags).
	 *
	 * @return string The expanded string
	 */
	protected static function expandCharacterSets($spec)
	{
		$combined = '';

		if ( $spec == self::EASY_TO_READ ) {
			$spec |= self::CHAR_ALNUM;
		}

		foreach ( self::$charArrays as $flag => $chars ) {
			// Handle this later.
			if ( $flag == self::EASY_TO_READ ) {
				continue;
			}

			if ( ($spec & $flag) === $flag ) {
				$combined .= $chars;
			}
		}

		// Remove ambiguous characters.
		if ( $spec & self::EASY_TO_READ ) {
			$combined = str_replace(str_split(self::AMBIGUOUS_CHARS), '', $combined);
		}

		return count_chars($combined, 3);
	}

	/**
	 * Generates a random number.
	 *
	 * @param integer $min Smallest value.
	 * @param integer $max Largest value.
	 *
	 * @return SecurityGeneratorPromise
	 */
	public static function generateNumber($min, $max)
	{
		return new SecurityGeneratorPromise(
			SecurityGeneratorPromise::TYPE_NUMBER,
			array($min, $max)
		);
	}

	/**
	 * Generates random bytes.
	 *
	 * @param integer $length     Raw result length.
	 * @param boolean $raw_output Return raw result.
	 *
	 * @return SecurityGeneratorPromise
	 */
	public static function generateBytes($length = 16, $raw_output = false)
	{
		return new SecurityGeneratorPromise(
			SecurityGeneratorPromise::TYPE_BYTES,
			array($length, $raw_output)
		);
	}

}