[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * A cryptographic random generator class used for generating secret keys
   4   *
   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.
   7   *
   8   * This program is free software; you can redistribute it and/or modify
   9   * it under the terms of the GNU General Public License as published by
  10   * the Free Software Foundation; either version 2 of the License, or
  11   * (at your option) any later version.
  12   *
  13   * This program is distributed in the hope that it will be useful,
  14   * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16   * GNU General Public License for more details.
  17   *
  18   * You should have received a copy of the GNU General Public License along
  19   * with this program; if not, write to the Free Software Foundation, Inc.,
  20   * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  21   * http://www.gnu.org/copyleft/gpl.html
  22   *
  23   * @author Daniel Friesen
  24   * @file
  25   */
  26  
  27  class MWCryptRand {
  28      /**
  29       * Minimum number of iterations we want to make in our drift calculations.
  30       */
  31      const MIN_ITERATIONS = 1000;
  32  
  33      /**
  34       * Number of milliseconds we want to spend generating each separate byte
  35       * of the final generated bytes.
  36       * This is used in combination with the hash length to determine the duration
  37       * we should spend doing drift calculations.
  38       */
  39      const MSEC_PER_BYTE = 0.5;
  40  
  41      /**
  42       * Singleton instance for public use
  43       */
  44      protected static $singleton = null;
  45  
  46      /**
  47       * The hash algorithm being used
  48       */
  49      protected $algo = null;
  50  
  51      /**
  52       * The number of bytes outputted by the hash algorithm
  53       */
  54      protected $hashLength = null;
  55  
  56      /**
  57       * A boolean indicating whether the previous random generation was done using
  58       * cryptographically strong random number generator or not.
  59       */
  60      protected $strong = null;
  61  
  62      /**
  63       * Initialize an initial random state based off of whatever we can find
  64       * @return string
  65       */
  66  	protected function initialRandomState() {
  67          // $_SERVER contains a variety of unstable user and system specific information
  68          // It'll vary a little with each page, and vary even more with separate users
  69          // It'll also vary slightly across different machines
  70          $state = serialize( $_SERVER );
  71  
  72          // To try vary the system information of the state a bit more
  73          // by including the system's hostname into the state
  74          $state .= wfHostname();
  75  
  76          // Try to gather a little entropy from the different php rand sources
  77          $state .= rand() . uniqid( mt_rand(), true );
  78  
  79          // Include some information about the filesystem's current state in the random state
  80          $files = array();
  81  
  82          // We know this file is here so grab some info about ourselves
  83          $files[] = __FILE__;
  84  
  85          // We must also have a parent folder, and with the usual file structure, a grandparent
  86          $files[] = __DIR__;
  87          $files[] = dirname( __DIR__ );
  88  
  89          // The config file is likely the most often edited file we know should
  90          // be around so include its stat info into the state.
  91          // The constant with its location will almost always be defined, as
  92          // WebStart.php defines MW_CONFIG_FILE to $IP/LocalSettings.php unless
  93          // being configured with MW_CONFIG_CALLBACK (e.g. the installer).
  94          if ( defined( 'MW_CONFIG_FILE' ) ) {
  95              $files[] = MW_CONFIG_FILE;
  96          }
  97  
  98          foreach ( $files as $file ) {
  99              wfSuppressWarnings();
 100              $stat = stat( $file );
 101              wfRestoreWarnings();
 102              if ( $stat ) {
 103                  // stat() duplicates data into numeric and string keys so kill off all the numeric ones
 104                  foreach ( $stat as $k => $v ) {
 105                      if ( is_numeric( $k ) ) {
 106                          unset( $k );
 107                      }
 108                  }
 109                  // The absolute filename itself will differ from install to install so don't leave it out
 110                  if ( ( $path = realpath( $file ) ) !== false ) {
 111                      $state .= $path;
 112                  } else {
 113                      $state .= $file;
 114                  }
 115                  $state .= implode( '', $stat );
 116              } else {
 117                  // The fact that the file isn't there is worth at least a
 118                  // minuscule amount of entropy.
 119                  $state .= '0';
 120              }
 121          }
 122  
 123          // Try and make this a little more unstable by including the varying process
 124          // id of the php process we are running inside of if we are able to access it
 125          if ( function_exists( 'getmypid' ) ) {
 126              $state .= getmypid();
 127          }
 128  
 129          // If available try to increase the instability of the data by throwing in
 130          // the precise amount of memory that we happen to be using at the moment.
 131          if ( function_exists( 'memory_get_usage' ) ) {
 132              $state .= memory_get_usage( true );
 133          }
 134  
 135          // It's mostly worthless but throw the wiki's id into the data for a little more variance
 136          $state .= wfWikiID();
 137  
 138          // If we have a secret key set then throw it into the state as well
 139          global $wgSecretKey;
 140          if ( $wgSecretKey ) {
 141              $state .= $wgSecretKey;
 142          }
 143  
 144          return $state;
 145      }
 146  
 147      /**
 148       * Randomly hash data while mixing in clock drift data for randomness
 149       *
 150       * @param string $data The data to randomly hash.
 151       * @return string The hashed bytes
 152       * @author Tim Starling
 153       */
 154  	protected function driftHash( $data ) {
 155          // Minimum number of iterations (to avoid slow operations causing the
 156          // loop to gather little entropy)
 157          $minIterations = self::MIN_ITERATIONS;
 158          // Duration of time to spend doing calculations (in seconds)
 159          $duration = ( self::MSEC_PER_BYTE / 1000 ) * $this->hashLength();
 160          // Create a buffer to use to trigger memory operations
 161          $bufLength = 10000000;
 162          $buffer = str_repeat( ' ', $bufLength );
 163          $bufPos = 0;
 164  
 165          // Iterate for $duration seconds or at least $minIterations number of iterations
 166          $iterations = 0;
 167          $startTime = microtime( true );
 168          $currentTime = $startTime;
 169          while ( $iterations < $minIterations || $currentTime - $startTime < $duration ) {
 170              // Trigger some memory writing to trigger some bus activity
 171              // This may create variance in the time between iterations
 172              $bufPos = ( $bufPos + 13 ) % $bufLength;
 173              $buffer[$bufPos] = ' ';
 174              // Add the drift between this iteration and the last in as entropy
 175              $nextTime = microtime( true );
 176              $delta = (int)( ( $nextTime - $currentTime ) * 1000000 );
 177              $data .= $delta;
 178              // Every 100 iterations hash the data and entropy
 179              if ( $iterations % 100 === 0 ) {
 180                  $data = sha1( $data );
 181              }
 182              $currentTime = $nextTime;
 183              $iterations++;
 184          }
 185          $timeTaken = $currentTime - $startTime;
 186          $data = $this->hash( $data );
 187  
 188          wfDebug( __METHOD__ . ": Clock drift calculation " .
 189              "(time-taken=" . ( $timeTaken * 1000 ) . "ms, " .
 190              "iterations=$iterations, " .
 191              "time-per-iteration=" . ( $timeTaken / $iterations * 1e6 ) . "us)\n" );
 192  
 193          return $data;
 194      }
 195  
 196      /**
 197       * Return a rolling random state initially build using data from unstable sources
 198       * @return string A new weak random state
 199       */
 200  	protected function randomState() {
 201          static $state = null;
 202          if ( is_null( $state ) ) {
 203              // Initialize the state with whatever unstable data we can find
 204              // It's important that this data is hashed right afterwards to prevent
 205              // it from being leaked into the output stream
 206              $state = $this->hash( $this->initialRandomState() );
 207          }
 208          // Generate a new random state based on the initial random state or previous
 209          // random state by combining it with clock drift
 210          $state = $this->driftHash( $state );
 211  
 212          return $state;
 213      }
 214  
 215      /**
 216       * Decide on the best acceptable hash algorithm we have available for hash()
 217       * @throws MWException
 218       * @return string A hash algorithm
 219       */
 220  	protected function hashAlgo() {
 221          if ( !is_null( $this->algo ) ) {
 222              return $this->algo;
 223          }
 224  
 225          $algos = hash_algos();
 226          $preference = array( 'whirlpool', 'sha256', 'sha1', 'md5' );
 227  
 228          foreach ( $preference as $algorithm ) {
 229              if ( in_array( $algorithm, $algos ) ) {
 230                  $this->algo = $algorithm;
 231                  wfDebug( __METHOD__ . ": Using the {$this->algo} hash algorithm.\n" );
 232  
 233                  return $this->algo;
 234              }
 235          }
 236  
 237          // We only reach here if no acceptable hash is found in the list, this should
 238          // be a technical impossibility since most of php's hash list is fixed and
 239          // some of the ones we list are available as their own native functions
 240          // But since we already require at least 5.2 and hash() was default in
 241          // 5.1.2 we don't bother falling back to methods like sha1 and md5.
 242          throw new MWException( "Could not find an acceptable hashing function in hash_algos()" );
 243      }
 244  
 245      /**
 246       * Return the byte-length output of the hash algorithm we are
 247       * using in self::hash and self::hmac.
 248       *
 249       * @return int Number of bytes the hash outputs
 250       */
 251  	protected function hashLength() {
 252          if ( is_null( $this->hashLength ) ) {
 253              $this->hashLength = strlen( $this->hash( '' ) );
 254          }
 255  
 256          return $this->hashLength;
 257      }
 258  
 259      /**
 260       * Generate an acceptably unstable one-way-hash of some text
 261       * making use of the best hash algorithm that we have available.
 262       *
 263       * @param string $data
 264       * @return string A raw hash of the data
 265       */
 266  	protected function hash( $data ) {
 267          return hash( $this->hashAlgo(), $data, true );
 268      }
 269  
 270      /**
 271       * Generate an acceptably unstable one-way-hmac of some text
 272       * making use of the best hash algorithm that we have available.
 273       *
 274       * @param string $data
 275       * @param string $key
 276       * @return string A raw hash of the data
 277       */
 278  	protected function hmac( $data, $key ) {
 279          return hash_hmac( $this->hashAlgo(), $data, $key, true );
 280      }
 281  
 282      /**
 283       * @see self::wasStrong()
 284       */
 285  	public function realWasStrong() {
 286          if ( is_null( $this->strong ) ) {
 287              throw new MWException( __METHOD__ . ' called before generation of random data' );
 288          }
 289  
 290          return $this->strong;
 291      }
 292  
 293      /**
 294       * @see self::generate()
 295       */
 296  	public function realGenerate( $bytes, $forceStrong = false ) {
 297          wfProfileIn( __METHOD__ );
 298  
 299          wfDebug( __METHOD__ . ": Generating cryptographic random bytes for " .
 300              wfGetAllCallers( 5 ) . "\n" );
 301  
 302          $bytes = floor( $bytes );
 303          static $buffer = '';
 304          if ( is_null( $this->strong ) ) {
 305              // Set strength to false initially until we know what source data is coming from
 306              $this->strong = true;
 307          }
 308  
 309          if ( strlen( $buffer ) < $bytes ) {
 310              // If available make use of mcrypt_create_iv URANDOM source to generate randomness
 311              // On unix-like systems this reads from /dev/urandom but does it without any buffering
 312              // and bypasses openbasedir restrictions, so it's preferable to reading directly
 313              // On Windows starting in PHP 5.3.0 Windows' native CryptGenRandom is used to generate
 314              // entropy so this is also preferable to just trying to read urandom because it may work
 315              // on Windows systems as well.
 316              if ( function_exists( 'mcrypt_create_iv' ) ) {
 317                  wfProfileIn( __METHOD__ . '-mcrypt' );
 318                  $rem = $bytes - strlen( $buffer );
 319                  $iv = mcrypt_create_iv( $rem, MCRYPT_DEV_URANDOM );
 320                  if ( $iv === false ) {
 321                      wfDebug( __METHOD__ . ": mcrypt_create_iv returned false.\n" );
 322                  } else {
 323                      $buffer .= $iv;
 324                      wfDebug( __METHOD__ . ": mcrypt_create_iv generated " . strlen( $iv ) .
 325                          " bytes of randomness.\n" );
 326                  }
 327                  wfProfileOut( __METHOD__ . '-mcrypt' );
 328              }
 329          }
 330  
 331          if ( strlen( $buffer ) < $bytes ) {
 332              // If available make use of openssl's random_pseudo_bytes method to
 333              // attempt to generate randomness. However don't do this on Windows
 334              // with PHP < 5.3.4 due to a bug:
 335              // http://stackoverflow.com/questions/1940168/openssl-random-pseudo-bytes-is-slow-php
 336              // http://git.php.net/?p=php-src.git;a=commitdiff;h=cd62a70863c261b07f6dadedad9464f7e213cad5
 337              if ( function_exists( 'openssl_random_pseudo_bytes' )
 338                  && ( !wfIsWindows() || version_compare( PHP_VERSION, '5.3.4', '>=' ) )
 339              ) {
 340                  wfProfileIn( __METHOD__ . '-openssl' );
 341                  $rem = $bytes - strlen( $buffer );
 342                  $openssl_bytes = openssl_random_pseudo_bytes( $rem, $openssl_strong );
 343                  if ( $openssl_bytes === false ) {
 344                      wfDebug( __METHOD__ . ": openssl_random_pseudo_bytes returned false.\n" );
 345                  } else {
 346                      $buffer .= $openssl_bytes;
 347                      wfDebug( __METHOD__ . ": openssl_random_pseudo_bytes generated " .
 348                          strlen( $openssl_bytes ) . " bytes of " .
 349                          ( $openssl_strong ? "strong" : "weak" ) . " randomness.\n" );
 350                  }
 351                  if ( strlen( $buffer ) >= $bytes ) {
 352                      // openssl tells us if the random source was strong, if some of our data was generated
 353                      // using it use it's say on whether the randomness is strong
 354                      $this->strong = !!$openssl_strong;
 355                  }
 356                  wfProfileOut( __METHOD__ . '-openssl' );
 357              }
 358          }
 359  
 360          // Only read from urandom if we can control the buffer size or were passed forceStrong
 361          if ( strlen( $buffer ) < $bytes &&
 362              ( function_exists( 'stream_set_read_buffer' ) || $forceStrong )
 363          ) {
 364              wfProfileIn( __METHOD__ . '-fopen-urandom' );
 365              $rem = $bytes - strlen( $buffer );
 366              if ( !function_exists( 'stream_set_read_buffer' ) && $forceStrong ) {
 367                  wfDebug( __METHOD__ . ": Was forced to read from /dev/urandom " .
 368                      "without control over the buffer size.\n" );
 369              }
 370              // /dev/urandom is generally considered the best possible commonly
 371              // available random source, and is available on most *nix systems.
 372              wfSuppressWarnings();
 373              $urandom = fopen( "/dev/urandom", "rb" );
 374              wfRestoreWarnings();
 375  
 376              // Attempt to read all our random data from urandom
 377              // php's fread always does buffered reads based on the stream's chunk_size
 378              // so in reality it will usually read more than the amount of data we're
 379              // asked for and not storing that risks depleting the system's random pool.
 380              // If stream_set_read_buffer is available set the chunk_size to the amount
 381              // of data we need. Otherwise read 8k, php's default chunk_size.
 382              if ( $urandom ) {
 383                  // php's default chunk_size is 8k
 384                  $chunk_size = 1024 * 8;
 385                  if ( function_exists( 'stream_set_read_buffer' ) ) {
 386                      // If possible set the chunk_size to the amount of data we need
 387                      stream_set_read_buffer( $urandom, $rem );
 388                      $chunk_size = $rem;
 389                  }
 390                  $random_bytes = fread( $urandom, max( $chunk_size, $rem ) );
 391                  $buffer .= $random_bytes;
 392                  fclose( $urandom );
 393                  wfDebug( __METHOD__ . ": /dev/urandom generated " . strlen( $random_bytes ) .
 394                      " bytes of randomness.\n" );
 395  
 396                  if ( strlen( $buffer ) >= $bytes ) {
 397                      // urandom is always strong, set to true if all our data was generated using it
 398                      $this->strong = true;
 399                  }
 400              } else {
 401                  wfDebug( __METHOD__ . ": /dev/urandom could not be opened.\n" );
 402              }
 403              wfProfileOut( __METHOD__ . '-fopen-urandom' );
 404          }
 405  
 406          // If we cannot use or generate enough data from a secure source
 407          // use this loop to generate a good set of pseudo random data.
 408          // This works by initializing a random state using a pile of unstable data
 409          // and continually shoving it through a hash along with a variable salt.
 410          // We hash the random state with more salt to avoid the state from leaking
 411          // out and being used to predict the /randomness/ that follows.
 412          if ( strlen( $buffer ) < $bytes ) {
 413              wfDebug( __METHOD__ .
 414                  ": Falling back to using a pseudo random state to generate randomness.\n" );
 415          }
 416          while ( strlen( $buffer ) < $bytes ) {
 417              wfProfileIn( __METHOD__ . '-fallback' );
 418              $buffer .= $this->hmac( $this->randomState(), mt_rand() );
 419              // This code is never really cryptographically strong, if we use it
 420              // at all, then set strong to false.
 421              $this->strong = false;
 422              wfProfileOut( __METHOD__ . '-fallback' );
 423          }
 424  
 425          // Once the buffer has been filled up with enough random data to fulfill
 426          // the request shift off enough data to handle the request and leave the
 427          // unused portion left inside the buffer for the next request for random data
 428          $generated = substr( $buffer, 0, $bytes );
 429          $buffer = substr( $buffer, $bytes );
 430  
 431          wfDebug( __METHOD__ . ": " . strlen( $buffer ) .
 432              " bytes of randomness leftover in the buffer.\n" );
 433  
 434          wfProfileOut( __METHOD__ );
 435  
 436          return $generated;
 437      }
 438  
 439      /**
 440       * @see self::generateHex()
 441       */
 442  	public function realGenerateHex( $chars, $forceStrong = false ) {
 443          // hex strings are 2x the length of raw binary so we divide the length in half
 444          // odd numbers will result in a .5 that leads the generate() being 1 character
 445          // short, so we use ceil() to ensure that we always have enough bytes
 446          $bytes = ceil( $chars / 2 );
 447          // Generate the data and then convert it to a hex string
 448          $hex = bin2hex( $this->generate( $bytes, $forceStrong ) );
 449  
 450          // A bit of paranoia here, the caller asked for a specific length of string
 451          // here, and it's possible (eg when given an odd number) that we may actually
 452          // have at least 1 char more than they asked for. Just in case they made this
 453          // call intending to insert it into a database that does truncation we don't
 454          // want to give them too much and end up with their database and their live
 455          // code having two different values because part of what we gave them is truncated
 456          // hence, we strip out any run of characters longer than what we were asked for.
 457          return substr( $hex, 0, $chars );
 458      }
 459  
 460      /** Publicly exposed static methods **/
 461  
 462      /**
 463       * Return a singleton instance of MWCryptRand
 464       * @return MWCryptRand
 465       */
 466  	protected static function singleton() {
 467          if ( is_null( self::$singleton ) ) {
 468              self::$singleton = new self;
 469          }
 470  
 471          return self::$singleton;
 472      }
 473  
 474      /**
 475       * Return a boolean indicating whether or not the source used for cryptographic
 476       * random bytes generation in the previously run generate* call
 477       * was cryptographically strong.
 478       *
 479       * @return bool Returns true if the source was strong, false if not.
 480       */
 481  	public static function wasStrong() {
 482          return self::singleton()->realWasStrong();
 483      }
 484  
 485      /**
 486       * Generate a run of (ideally) cryptographically random data and return
 487       * it in raw binary form.
 488       * You can use MWCryptRand::wasStrong() if you wish to know if the source used
 489       * was cryptographically strong.
 490       *
 491       * @param int $bytes The number of bytes of random data to generate
 492       * @param bool $forceStrong Pass true if you want generate to prefer cryptographically
 493       *                          strong sources of entropy even if reading from them may steal
 494       *                          more entropy from the system than optimal.
 495       * @return string Raw binary random data
 496       */
 497  	public static function generate( $bytes, $forceStrong = false ) {
 498          return self::singleton()->realGenerate( $bytes, $forceStrong );
 499      }
 500  
 501      /**
 502       * Generate a run of (ideally) cryptographically random data and return
 503       * it in hexadecimal string format.
 504       * You can use MWCryptRand::wasStrong() if you wish to know if the source used
 505       * was cryptographically strong.
 506       *
 507       * @param int $chars The number of hex chars of random data to generate
 508       * @param bool $forceStrong Pass true if you want generate to prefer cryptographically
 509       *                          strong sources of entropy even if reading from them may steal
 510       *                          more entropy from the system than optimal.
 511       * @return string Hexadecimal random data
 512       */
 513  	public static function generateHex( $chars, $forceStrong = false ) {
 514          return self::singleton()->realGenerateHex( $chars, $forceStrong );
 515      }
 516  }