3 * A static 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.
11 final class MWCryptRand
{
14 * Initialize an initial random state based off of whatever we can find
16 private static function initialRandomState() {
17 // $_SERVER contains a variety of unstable user and system specific information
18 // It'll vary a little with each page, and vary even more with separate users
19 // It'll also vary slightly across different machines
20 $state = serialize( $_SERVER );
22 // To try and vary the system information of the state a bit more
23 // by including the system's hostname into the state
24 $state .= wfHostname();
26 // Try and make this a little more unstable by including the varying process
27 // id of the php process we are running inside of if we are able to access it
28 if ( function_exists( 'getmypid' ) ) {
32 // If available try to increase the instability of the data by throwing in
33 // the precise amount of memory that we happen to be using at the moment.
34 if ( function_exists( 'memory_get_usage' ) ) {
35 $state .= memory_get_usage( true );
38 // It's mostly worthless but throw the wiki's id into the data for a little more variance
41 // If we have a secret key or proxy key set then throw it into the state as well
42 global $wgSecretKey, $wgProxyKey;
44 $state .= $wgSecretKey;
45 } elseif ( $wgProxyKey ) {
46 $state .= $wgProxyKey;
53 * Return a rolling random state initially build using data from unstable sources
54 * @return A new weak random state
56 public static function randomState() {
58 if ( is_null( $state ) ) {
59 // Initialize the state with whatever unstable data we can find
60 // It's important that this data is hashed right afterwards to prevent
61 // it from being leaked into the output stream
62 $state = self
::initialRandomState();
64 // Generate a new random state based on the initial random state or previous
65 // random state by combining it with both the current time and a random value
66 // Simple append/prepend based methods of combining data and a salt have
67 // weaknesses in them, take advantage of the availability of hmac to abuse
68 // it's method of combining data and a key into a hash which is free of
69 // the typical weakness of simple concatenation
70 // Note that in hmac large keys are reduced in size and the key is then
71 // xor-ed to create two separate keys. For this reason we use the smaller
72 // time+rand as the key and the larger state as the data.
73 // We also don't bother passing numbers to mt_rand since you can't make
74 // it generate with any more entropy than it's default max value.
75 $state = self
::hmac( $state, microtime() . mt_rand() );
80 * Decide on the best acceptable hash algorithm we have available for hash()
81 * @return String A hash algorithm
83 private static function hashAlgo() {
85 if ( !is_null( $algo ) ) {
89 $algos = hash_algos();
90 $preference = array( 'whirlpool', 'sha256', 'sha1', 'md5' );
92 foreach ( $preference as $algorithm ) {
93 if ( in_array( $algorithm, $algos ) ) {
94 $algo = $algorithm; # assign to static
99 // We only reach here if no acceptable hash is found in the list, this should
100 // be a technical impossibility since most of php's hash list is fixed and
101 // some of the ones we list are available as their own native functions
102 // But since we already require at least 5.2 and hash() was default in
103 // 5.1.2 we don't bother falling back to methods like sha1 and md5.
104 throw new MWException( "Could not find an acceptable hashing function in hash_algos()" );
108 * Generate an acceptably unstable one-way-hash of some text
109 * making use of the best hash algorithm that we have available.
111 * @return String A raw hash of the data
113 private static function hash( $data ) {
114 return hash( self
::hashAlgo(), $data, true );
118 * Generate an acceptably unstable one-way-hmac of some text
119 * making use of the best hash algorithm that we have available.
121 * @return String A raw hash of the data
123 private static function hmac( $data, $key ) {
124 return hash_hmac( self
::hashAlgo(), $data, $key, true );
129 private static $strong = null;
132 * Return a boolean indicating whether or not the source used for cryptographic
133 * random bytes generation in the previously run generate* call
134 * was cryptographically strong.
136 * @return bool Returns true if the source was strong, false if not.
138 public static function wasStrong() {
139 if ( is_null( self
::$strong ) ) {
140 throw new MWException( __METHOD__
. ' called before generation of random data' );
142 return self
::$strong;
146 * Generate a run of (ideally) cryptographically random data and return
147 * it in raw binary form.
148 * You can use MWCryptRand::wasStrong() if you wish to know if the source used
149 * was cryptographically strong.
151 * @param $bytes int the number of bytes of random data to generate
152 * @return String Raw binary random data
154 public static function generate( $bytes ) {
155 $bytes = floor( $bytes );
157 if ( is_null( self
::$strong ) ) {
158 // Set strength to false initially until we know what source data is coming from
159 self
::$strong = true;
162 if ( strlen( $buffer ) < $bytes ) {
163 // /dev/urandom is generally considered the best possible commonly
164 // available random source, and is available on most *nix systems.
165 wfSuppressWarnings();
166 $urandom = fopen( "/dev/urandom", "rb" );
169 // Attempt to read all our random data from urandom
170 // php's fread always does buffered reads based on the stream's chunk_size
171 // so in reality it will usually read more than the amount of data we're
172 // asked for and it doesn't cost anything extra to store that.
173 // We don't have access to the stream's chunk_size, fread maxes out at 8k
174 // so we'll go along with Drupal's decision to read at least 4k
176 $buffer .= fread( $urandom, max( 1024 * 4, $bytes ) );
178 if ( strlen( $buffer ) >= $bytes ) {
179 // urandom is always strong, set to true if all our data was generated using it
180 self
::$strong = true;
185 if ( strlen( $buffer ) < $bytes ) {
186 // If available and we failed to read enough data out of urandom make use
187 // of openssl's random_pesudo_bytes method to attempt to generate randomness.
188 // However don't do this on Windows with PHP < 5.3.4 due to a bug:
189 // http://stackoverflow.com/questions/1940168/openssl-random-pseudo-bytes-is-slow-php
190 if ( ( $bytes - strlen( $buffer ) > 0 )
191 && function_exists( 'openssl_random_pseudo_bytes' )
192 && ( !wfIsWindows() ||
version_compare( PHP_VERSION
, '5.3.4', '>=' ) )
194 $buffer .= openssl_random_pseudo_bytes( $bytes - strlen( $buffer ), $openssl_strong );
195 if ( strlen( $buffer ) >= $bytes ) {
196 // openssl tells us if the random source was strong, if some of our data was generated
197 // using it use it's say on whether the randomness is strong
198 self
::$strong = !!$openssl_strong;
204 // If we cannot use or generate enough data from /dev/urandom or openssl
205 // use this loop to generate a good set of pesudo random data.
206 // This works by initializing a random state using a pile of unstable data
207 // and continually shoving it through a hash along with a variable salt.
208 // We hash the random state with more salt to avoid the state from leaking
209 // out and being used to predict the /randomness/ that follows.
210 while ( strlen( $buffer ) < $bytes ) {
211 $buffer .= self
::hmac( self
::randomState(), mt_rand() );
212 // This code is never really cryptographically strong, if we use it
213 // at all, then set strong to false.
214 self
::$strong = false;
217 // Once the buffer has been filled up with enough random data to fulfill
218 // the request shift off enough data to handle the request and leave the
219 // unused portion left inside the buffer for the next request for random data
220 $generated = substr( $buffer, 0, $bytes );
221 $buffer = substr( $buffer, $bytes );
227 * Generate a run of (ideally) cryptographically random data and return
228 * it in hexadecimal string format.
229 * You can use MWCryptRand::wasStrong() if you wish to know if the source used
230 * was cryptographically strong.
232 * @param $chars int the number of hex chars of random data to generate
233 * @return String Hexadecimal random data
235 public static function generateHex( $chars ) {
236 // hex strings are 2x the length of raw binary so we divide the length in half
237 // odd numbers will result in a .5 that leads the generate() being 1 character
238 // short, so we use ceil() to ensure that we always have enough bytes
239 $bytes = ceil( $chars / 2 );
240 // Generate the data and then convert it to a hex string
241 $hex = bin2hex( self
::generate( $bytes ) );
242 // A bit of paranoia here, the caller asked for a specific length of string
243 // here, and it's possible (eg when given an odd number) that we may actually
244 // have at least 1 char more than they asked for. Just in case they made this
245 // call intending to insert it into a database that does truncation we don't
246 // want to give them too much and end up with their database and their live
247 // code having two different values because part of what we gave them is truncated
248 // hence, we strip out any run of characters longer than what we were asked for.
249 return substr( $hex, 0, $chars );