Factory.php 7.9 KB

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