CryptLib/Random/Factory.php

   1 <?php
   2 /**
   3  * The Random Factory
   4  *
   5  * Use this factory to instantiate random number generators, sources and mixers.
   6  *
   7  * PHP version 5.3
   8  *
   9  * @category   PHPCryptLib
  10  * @package    Random
  11  * @author     Anthony Ferrara <ircmaxell@ircmaxell.com>
  12  * @copyright  2011 The Authors
  13  * @license    http://www.opensource.org/licenses/mit-license.html  MIT License
  14  * @version    Build @@version@@
  15  */
  16
  17 namespace CryptLib\Random;
  18
  19 use CryptLib\Core\Strength;
  20
  21 /**
  22  * The Random Factory
  23  *
  24  * Use this factory to instantiate random number generators, sources and mixers.
  25  *
  26  * @category   PHPCryptLib
  27  * @package    Random
  28  * @author     Anthony Ferrara <ircmaxell@ircmaxell.com>
  29  */
  30 class Factory extends \CryptLib\Core\AbstractFactory {
  31
  32     /**
  33      * @var array A list of available random number mixing strategies
  34      */
  35     protected $mixers = array();
  36
  37     /**
  38      * @var array A list of available random number sources
  39      */
  40     protected $sources = array();
  41
  42     /**
  43      * Build a new instance of the factory, loading core mixers and sources
  44      *
  45      * @return void
  46      */
  47     public function __construct() {
  48         $this->loadMixers();
  49         $this->loadSources();
  50     }
  51
  52     /**
  53      * Get a generator for the requested strength
  54      *
  55      * @param Strength $strength The requested strength of the random number
  56      *
  57      * @return Generator The instantiated generator
  58      * @throws RuntimeException If an appropriate mixing strategy isn't found
  59      */
  60     public function getGenerator(\CryptLib\Core\Strength $strength) {
  61         $sources    = $this->getSources();
  62         $newSources = array();
  63         foreach ($sources as $source) {
  64             if ($strength->compare($source::getStrength()) <= 0) {
  65                 $newSources[] = new $source;
  66             }
  67         }
  68         $mixer = $this->findMixer($strength);
  69         return new Generator($newSources, $mixer);
  70     }
  71
  72     /**
  73      * Get a high strength random number generator
  74      *
  75      * High Strength keys should ONLY be used for generating extremely strong
  76      * cryptographic keys.  Generating them is very resource intensive and may
  77      * take several minutes or more depending on the requested size.
  78      *
  79      * @return Generator The instantiated generator
  80      */
  81     public function getHighStrengthGenerator() {
  82         return $this->getGenerator(new Strength(Strength::HIGH));
  83     }
  84
  85     /**
  86      * Get a low strength random number generator
  87      *
  88      * Low Strength should be used anywhere that random strings are needed in a
  89      * non-cryptographical setting.  They are not strong enough to be used as
  90      * keys or salts.  They are however useful for one-time use tokens.
  91      *
  92      * @return Generator The instantiated generator
  93      */
  94     public function getLowStrengthGenerator() {
  95         return $this->getGenerator(new Strength(Strength::LOW));
  96     }
  97
  98     /**
  99      * Get a medium strength random number generator
 100      *
 101      * Medium Strength should be used for most needs of a cryptographic nature.
 102      * They are strong enough to be used as keys and salts.  However, they do
 103      * take some time and resources to generate, so they should not be over-used
 104      *
 105      * @return Generator The instantiated generator
 106      */
 107     public function getMediumStrengthGenerator() {
 108         return $this->getGenerator(new Strength(Strength::MEDIUM));
 109     }
 110
 111     /**
 112      * Get all loaded mixing strategies
 113      *
 114      * @return array An array of mixers
 115      */
 116     public function getMixers() {
 117         return $this->mixers;
 118     }
 119
 120     /**
 121      * Get all loaded random number sources
 122      *
 123      * @return array An array of sources
 124      */
 125     public function getSources() {
 126         return $this->sources;
 127     }
 128
 129     /**
 130      * Register a mixing strategy for this factory instance
 131      *
 132      * @param string $name  The name of the stategy
 133      * @param string $class The class name of the implementation
 134      *
 135      * @return Factory $this The current factory instance
 136      */
 137     public function registerMixer($name, $class) {
 138         $this->registerType(
 139             'mixers',
 140             __NAMESPACE__ . '\\Mixer',
 141             $name,
 142             $class
 143         );
 144         return $this;
 145     }
 146
 147     /**
 148      * Register a random number source for this factory instance
 149      *
 150      * Note that this class must implement the Source interface
 151      *
 152      * @param string $name  The name of the stategy
 153      * @param string $class The class name of the implementation
 154      *
 155      * @return Factory $this The current factory instance
 156      */
 157     public function registerSource($name, $class) {
 158         $this->registerType(
 159             'sources',
 160             __NAMESPACE__ . '\\Source',
 161             $name,
 162             $class
 163         );
 164         return $this;
 165     }
 166
 167     /**
 168      * Find a mixer based upon the requested strength
 169      *
 170      * @param Strength $strength The strength mixer to find
 171      *
 172      * @return Mixer The found mixer
 173      * @throws RuntimeException if a valid mixer cannot be found
 174      */
 175     protected function findMixer(\CryptLib\Core\Strength $strength) {
 176         $newMixer = null;
 177         $fallback = null;
 178         foreach ($this->getMixers() as $mixer) {
 179             if ($strength->compare($mixer::getStrength()) == 0) {
 180                 $newMixer = new $mixer;
 181             } elseif ($strength->compare($mixer::getStrength()) == 1) {
 182                 $fallback = new $mixer;
 183             }
 184         }
 185         if (is_null($newMixer)) {
 186             if (is_null($fallback)) {
 187                 throw new \RuntimeException('Could not find mixer');
 188             }
 189             return $fallback;
 190         }
 191         return $newMixer;
 192     }
 193
 194     /**
 195      * Load all core mixing strategies
 196      *
 197      * @return void
 198      */
 199     protected function loadMixers() {
 200         $this->loadFiles(
 201             __DIR__ . '/Mixer',
 202             __NAMESPACE__ . '\\Mixer\\',
 203             array($this, 'registerMixer')
 204         );
 205     }
 206
 207     /**
 208      * Load all core random number sources
 209      *
 210      * @return void
 211      */
 212     protected function loadSources() {
 213         $this->loadFiles(
 214             __DIR__ . '/Source',
 215             __NAMESPACE__ . '\\Source\\',
 216             array($this, 'registerSource')
 217         );
 218     }
 219
 220 }
 221