3 * A cryptographic random generator class used for generating secret keys
5 * This is based in part on Drupal code as well as what we used in our own code
6 * prior to introduction of this class.
8 * @author Daniel Friesen
15 * Minimum number of iterations we want to make in our drift calculations.
17 const MIN_ITERATIONS
= 1000;
20 * Number of milliseconds we want to spend generating each separate byte
21 * of the final generated bytes.
22 * This is used in combination with the hash length to determine the duration
23 * we should spend doing drift calculations.
25 const MSEC_PER_BYTE
= 0.5;
28 * Singleton instance for public use
30 protected static $singleton = null;
33 * The hash algorithm being used
35 protected $algo = null;
38 * The number of bytes outputted by the hash algorithm
40 protected $hashLength = null;
43 * A boolean indicating whether the previous random generation was done using
44 * cryptographically strong random number generator or not.
46 protected $strong = null;
49 * Initialize an initial random state based off of whatever we can find
51 protected function initialRandomState() {
52 // $_SERVER contains a variety of unstable user and system specific information
53 // It'll vary a little with each page, and vary even more with separate users
54 // It'll also vary slightly across different machines
55 $state = serialize( $_SERVER );
57 // To try and vary the system information of the state a bit more
58 // by including the system's hostname into the state
59 $state .= wfHostname();
61 // Try to gather a little entropy from the different php rand sources
62 $state .= rand() . uniqid( mt_rand(), true );
64 // Include some information about the filesystem's current state in the random state
67 // We know this file is here so grab some info about ourself
70 // We must also have a parent folder, and with the usual file structure, a grandparent
71 $files[] = dirname( __FILE__
);
72 $files[] = dirname( dirname( __FILE__
) );
74 // The config file is likely the most often edited file we know should be around
75 // so if the constant with it's location is defined include it's stat info into the state
76 if ( defined( 'MW_CONFIG_FILE' ) ) {
77 $files[] = MW_CONFIG_FILE
;
79 foreach ( $files as $file ) {
81 $stat = stat( $file );
84 // stat() duplicates data into numeric and string keys so kill off all the numeric ones
85 foreach ( $stat as $k => $v ) {
86 if ( is_numeric( $k ) ) {
90 // The absolute filename itself will differ from install to install so don't leave it out
91 $state .= realpath( $file );
92 $state .= implode( '', $stat );
94 // The fact that the file isn't there is worth at least a
95 // minuscule amount of entropy.
100 // Try and make this a little more unstable by including the varying process
101 // id of the php process we are running inside of if we are able to access it
102 if ( function_exists( 'getmypid' ) ) {
103 $state .= getmypid();
106 // If available try to increase the instability of the data by throwing in
107 // the precise amount of memory that we happen to be using at the moment.
108 if ( function_exists( 'memory_get_usage' ) ) {
109 $state .= memory_get_usage( true );
112 // It's mostly worthless but throw the wiki's id into the data for a little more variance
113 $state .= wfWikiID();
115 // If we have a secret key or proxy key set then throw it into the state as well
116 global $wgSecretKey, $wgProxyKey;
117 if ( $wgSecretKey ) {
118 $state .= $wgSecretKey;
119 } elseif ( $wgProxyKey ) {
120 $state .= $wgProxyKey;
127 * Randomly hash data while mixing in clock drift data for randomness
129 * @param $data string The data to randomly hash.
130 * @return String The hashed bytes
131 * @author Tim Starling
133 protected function driftHash( $data ) {
134 // Minimum number of iterations (to avoid slow operations causing the loop to gather little entropy)
135 $minIterations = self
::MIN_ITERATIONS
;
136 // Duration of time to spend doing calculations (in seconds)
137 $duration = ( self
::MSEC_PER_BYTE
/ 1000 ) * $this->hashLength();
138 // Create a buffer to use to trigger memory operations
139 $bufLength = 10000000;
140 $buffer = str_repeat( ' ', $bufLength );
143 // Iterate for $duration seconds or at least $minIerations number of iterations
145 $startTime = microtime( true );
146 $currentTime = $startTime;
147 while ( $iterations < $minIterations ||
$currentTime - $startTime < $duration ) {
148 // Trigger some memory writing to trigger some bus activity
149 // This may create variance in the time between iterations
150 $bufPos = ( $bufPos +
13 ) %
$bufLength;
151 $buffer[$bufPos] = ' ';
152 // Add the drift between this iteration and the last in as entropy
153 $nextTime = microtime( true );
154 $delta = (int)( ( $nextTime - $currentTime ) * 1000000 );
156 // Every 100 iterations hash the data and entropy
157 if ( $iterations %
100 === 0 ) {
158 $data = sha1( $data );
160 $currentTime = $nextTime;
163 $timeTaken = $currentTime - $startTime;
164 $data = $this->hash( $data );
166 wfDebug( __METHOD__
. ": Clock drift calculation " .
167 "(time-taken=" . ( $timeTaken * 1000 ) . "ms, " .
168 "iterations=$iterations, " .
169 "time-per-iteration=" . ( $timeTaken / $iterations * 1e6
) . "us)\n" );
174 * Return a rolling random state initially build using data from unstable sources
175 * @return string A new weak random state
177 protected function randomState() {
178 static $state = null;
179 if ( is_null( $state ) ) {
180 // Initialize the state with whatever unstable data we can find
181 // It's important that this data is hashed right afterwards to prevent
182 // it from being leaked into the output stream
183 $state = $this->hash( $this->initialRandomState() );
185 // Generate a new random state based on the initial random state or previous
186 // random state by combining it with clock drift
187 $state = $this->driftHash( $state );
192 * Decide on the best acceptable hash algorithm we have available for hash()
193 * @throws MWException
194 * @return String A hash algorithm
196 protected function hashAlgo() {
197 if ( !is_null( $this->algo
) ) {
201 $algos = hash_algos();
202 $preference = array( 'whirlpool', 'sha256', 'sha1', 'md5' );
204 foreach ( $preference as $algorithm ) {
205 if ( in_array( $algorithm, $algos ) ) {
206 $this->algo
= $algorithm;
207 wfDebug( __METHOD__
. ": Using the {$this->algo} hash algorithm.\n" );
212 // We only reach here if no acceptable hash is found in the list, this should
213 // be a technical impossibility since most of php's hash list is fixed and
214 // some of the ones we list are available as their own native functions
215 // But since we already require at least 5.2 and hash() was default in
216 // 5.1.2 we don't bother falling back to methods like sha1 and md5.
217 throw new MWException( "Could not find an acceptable hashing function in hash_algos()" );
221 * Return the byte-length output of the hash algorithm we are
222 * using in self::hash and self::hmac.
224 * @return int Number of bytes the hash outputs
226 protected function hashLength() {
227 if ( is_null( $this->hashLength
) ) {
228 $this->hashLength
= strlen( $this->hash( '' ) );
230 return $this->hashLength
;
234 * Generate an acceptably unstable one-way-hash of some text
235 * making use of the best hash algorithm that we have available.
237 * @param $data string
238 * @return String A raw hash of the data
240 protected function hash( $data ) {
241 return hash( $this->hashAlgo(), $data, true );
245 * Generate an acceptably unstable one-way-hmac of some text
246 * making use of the best hash algorithm that we have available.
248 * @param $data string
250 * @return String A raw hash of the data
252 protected function hmac( $data, $key ) {
253 return hash_hmac( $this->hashAlgo(), $data, $key, true );
257 * @see self::wasStrong()
259 public function realWasStrong() {
260 if ( is_null( $this->strong
) ) {
261 throw new MWException( __METHOD__
. ' called before generation of random data' );
263 return $this->strong
;
267 * @see self::generate()
269 public function realGenerate( $bytes, $forceStrong = false ) {
270 wfProfileIn( __METHOD__
);
272 wfDebug( __METHOD__
. ": Generating cryptographic random bytes for " . wfGetAllCallers( 5 ) . "\n" );
274 $bytes = floor( $bytes );
276 if ( is_null( $this->strong
) ) {
277 // Set strength to false initially until we know what source data is coming from
278 $this->strong
= true;
281 if ( strlen( $buffer ) < $bytes ) {
282 // If available make use of mcrypt_create_iv URANDOM source to generate randomness
283 // On unix-like systems this reads from /dev/urandom but does it without any buffering
284 // and bypasses openbasdir restrictions so it's preferable to reading directly
285 // On Windows starting in PHP 5.3.0 Windows' native CryptGenRandom is used to generate
286 // entropy so this is also preferable to just trying to read urandom because it may work
287 // on Windows systems as well.
288 if ( function_exists( 'mcrypt_create_iv' ) ) {
289 wfProfileIn( __METHOD__
. '-mcrypt' );
290 $rem = $bytes - strlen( $buffer );
291 $iv = mcrypt_create_iv( $rem, MCRYPT_DEV_URANDOM
);
292 if ( $iv === false ) {
293 wfDebug( __METHOD__
. ": mcrypt_create_iv returned false.\n" );
296 wfDebug( __METHOD__
. ": mcrypt_create_iv generated " . strlen( $iv ) . " bytes of randomness.\n" );
298 wfProfileOut( __METHOD__
. '-mcrypt' );
302 if ( strlen( $buffer ) < $bytes ) {
303 // If available make use of openssl's random_pesudo_bytes method to attempt to generate randomness.
304 // However don't do this on Windows with PHP < 5.3.4 due to a bug:
305 // http://stackoverflow.com/questions/1940168/openssl-random-pseudo-bytes-is-slow-php
306 if ( function_exists( 'openssl_random_pseudo_bytes' )
307 && ( !wfIsWindows() ||
version_compare( PHP_VERSION
, '5.3.4', '>=' ) )
309 wfProfileIn( __METHOD__
. '-openssl' );
310 $rem = $bytes - strlen( $buffer );
311 $openssl_bytes = openssl_random_pseudo_bytes( $rem, $openssl_strong );
312 if ( $openssl_bytes === false ) {
313 wfDebug( __METHOD__
. ": openssl_random_pseudo_bytes returned false.\n" );
315 $buffer .= $openssl_bytes;
316 wfDebug( __METHOD__
. ": openssl_random_pseudo_bytes generated " . strlen( $openssl_bytes ) . " bytes of " . ( $openssl_strong ?
"strong" : "weak" ) . " randomness.\n" );
318 if ( strlen( $buffer ) >= $bytes ) {
319 // openssl tells us if the random source was strong, if some of our data was generated
320 // using it use it's say on whether the randomness is strong
321 $this->strong
= !!$openssl_strong;
323 wfProfileOut( __METHOD__
. '-openssl' );
327 // Only read from urandom if we can control the buffer size or were passed forceStrong
328 if ( strlen( $buffer ) < $bytes && ( function_exists( 'stream_set_read_buffer' ) ||
$forceStrong ) ) {
329 wfProfileIn( __METHOD__
. '-fopen-urandom' );
330 $rem = $bytes - strlen( $buffer );
331 if ( !function_exists( 'stream_set_read_buffer' ) && $forceStrong ) {
332 wfDebug( __METHOD__
. ": Was forced to read from /dev/urandom without control over the buffer size.\n" );
334 // /dev/urandom is generally considered the best possible commonly
335 // available random source, and is available on most *nix systems.
336 wfSuppressWarnings();
337 $urandom = fopen( "/dev/urandom", "rb" );
340 // Attempt to read all our random data from urandom
341 // php's fread always does buffered reads based on the stream's chunk_size
342 // so in reality it will usually read more than the amount of data we're
343 // asked for and not storing that risks depleting the system's random pool.
344 // If stream_set_read_buffer is available set the chunk_size to the amount
345 // of data we need. Otherwise read 8k, php's default chunk_size.
347 // php's default chunk_size is 8k
348 $chunk_size = 1024 * 8;
349 if ( function_exists( 'stream_set_read_buffer' ) ) {
350 // If possible set the chunk_size to the amount of data we need
351 stream_set_read_buffer( $urandom, $rem );
354 $random_bytes = fread( $urandom, max( $chunk_size, $rem ) );
355 $buffer .= $random_bytes;
357 wfDebug( __METHOD__
. ": /dev/urandom generated " . strlen( $random_bytes ) . " bytes of randomness.\n" );
358 if ( strlen( $buffer ) >= $bytes ) {
359 // urandom is always strong, set to true if all our data was generated using it
360 $this->strong
= true;
363 wfDebug( __METHOD__
. ": /dev/urandom could not be opened.\n" );
365 wfProfileOut( __METHOD__
. '-fopen-urandom' );
368 // If we cannot use or generate enough data from a secure source
369 // use this loop to generate a good set of pseudo random data.
370 // This works by initializing a random state using a pile of unstable data
371 // and continually shoving it through a hash along with a variable salt.
372 // We hash the random state with more salt to avoid the state from leaking
373 // out and being used to predict the /randomness/ that follows.
374 if ( strlen( $buffer ) < $bytes ) {
375 wfDebug( __METHOD__
. ": Falling back to using a pseudo random state to generate randomness.\n" );
377 while ( strlen( $buffer ) < $bytes ) {
378 wfProfileIn( __METHOD__
. '-fallback' );
379 $buffer .= $this->hmac( $this->randomState(), mt_rand() );
380 // This code is never really cryptographically strong, if we use it
381 // at all, then set strong to false.
382 $this->strong
= false;
383 wfProfileOut( __METHOD__
. '-fallback' );
386 // Once the buffer has been filled up with enough random data to fulfill
387 // the request shift off enough data to handle the request and leave the
388 // unused portion left inside the buffer for the next request for random data
389 $generated = substr( $buffer, 0, $bytes );
390 $buffer = substr( $buffer, $bytes );
392 wfDebug( __METHOD__
. ": " . strlen( $buffer ) . " bytes of randomness leftover in the buffer.\n" );
394 wfProfileOut( __METHOD__
);
399 * @see self::generateHex()
401 public function realGenerateHex( $chars, $forceStrong = false ) {
402 // hex strings are 2x the length of raw binary so we divide the length in half
403 // odd numbers will result in a .5 that leads the generate() being 1 character
404 // short, so we use ceil() to ensure that we always have enough bytes
405 $bytes = ceil( $chars / 2 );
406 // Generate the data and then convert it to a hex string
407 $hex = bin2hex( $this->generate( $bytes, $forceStrong ) );
408 // A bit of paranoia here, the caller asked for a specific length of string
409 // here, and it's possible (eg when given an odd number) that we may actually
410 // have at least 1 char more than they asked for. Just in case they made this
411 // call intending to insert it into a database that does truncation we don't
412 // want to give them too much and end up with their database and their live
413 // code having two different values because part of what we gave them is truncated
414 // hence, we strip out any run of characters longer than what we were asked for.
415 return substr( $hex, 0, $chars );
418 /** Publicly exposed static methods **/
421 * Return a singleton instance of MWCryptRand
422 * @return MWCryptRand
424 protected static function singleton() {
425 if ( is_null( self
::$singleton ) ) {
426 self
::$singleton = new self
;
428 return self
::$singleton;
432 * Return a boolean indicating whether or not the source used for cryptographic
433 * random bytes generation in the previously run generate* call
434 * was cryptographically strong.
436 * @return bool Returns true if the source was strong, false if not.
438 public static function wasStrong() {
439 return self
::singleton()->realWasStrong();
443 * Generate a run of (ideally) cryptographically random data and return
444 * it in raw binary form.
445 * You can use MWCryptRand::wasStrong() if you wish to know if the source used
446 * was cryptographically strong.
448 * @param $bytes int the number of bytes of random data to generate
449 * @param $forceStrong bool Pass true if you want generate to prefer cryptographically
450 * strong sources of entropy even if reading from them may steal
451 * more entropy from the system than optimal.
452 * @return String Raw binary random data
454 public static function generate( $bytes, $forceStrong = false ) {
455 return self
::singleton()->realGenerate( $bytes, $forceStrong );
459 * Generate a run of (ideally) cryptographically random data and return
460 * it in hexadecimal string format.
461 * You can use MWCryptRand::wasStrong() if you wish to know if the source used
462 * was cryptographically strong.
464 * @param $chars int the number of hex chars of random data to generate
465 * @param $forceStrong bool Pass true if you want generate to prefer cryptographically
466 * strong sources of entropy even if reading from them may steal
467 * more entropy from the system than optimal.
468 * @return String Hexadecimal random data
470 public static function generateHex( $chars, $forceStrong = false ) {
471 return self
::singleton()->realGenerateHex( $chars, $forceStrong );