csrf-magic.php

   1 <?php
   2
   3 /**
   4  * @file
   5  *
   6  * csrf-magic is a PHP library that makes adding CSRF-protection to your
   7  * web applications a snap. No need to modify every form or create a database
   8  * of valid nonces; just include this file at the top of every
   9  * web-accessible page (or even better, your common include file included
  10  * in every page), and forget about it! (There are, of course, configuration
  11  * options for advanced users).
  12  *
  13  * This library is PHP4 and PHP5 compatible.
  14  */
  15
  16 // CONFIGURATION:
  17
  18 /**
  19  * Convenience parameter for disabling all of our functionality;
  20  * equivalent to setting 'rewrite' to false and 'defer' to true.
  21  */
  22 $GLOBALS['csrf']['disable'] = false;
  23
  24 /**
  25  * By default, when you include this file csrf-magic will automatically check
  26  * and exit if the CSRF token is invalid. This will defer executing
  27  * csrf_check() until you're ready.  You can also pass false as a parameter to
  28  * that function, in which case the function will not exit but instead return
  29  * a boolean false if the CSRF check failed. This allows for tighter integration
  30  * with your system.
  31  */
  32 $GLOBALS['csrf']['defer'] = false;
  33
  34 /**
  35  * This is the amount of seconds you wish to allow before any token becomes
  36  * invalid; the default is two hours, which should be more than enough for
  37  * most websites.
  38  */
  39 $GLOBALS['csrf']['expires'] = 7200;
  40
  41 /**
  42  * Callback function to execute when there's the CSRF check fails and
  43  * $fatal == true (see csrf_check). This will usually output an error message
  44  * about the failure.
  45  */
  46 $GLOBALS['csrf']['callback'] = 'csrf_callback';
  47
  48 /**
  49  * Whether or not to include our JavaScript library which also rewrites
  50  * AJAX requests on this domain. Set this to the web path. This setting only works
  51  * with supported JavaScript libraries in Internet Explorer; see README.txt for
  52  * a list of supported libraries.
  53  */
  54 $GLOBALS['csrf']['rewrite-js'] = false;
  55
  56 /**
  57  * A secret key used when hashing items. Please generate a random string and
  58  * place it here. If you change this value, all previously generated tokens
  59  * will become invalid.
  60  */
  61 $GLOBALS['csrf']['secret'] = '';
  62 // nota bene: library code should use csrf_get_secret() and not access
  63 // this global directly
  64
  65 /**
  66  * Set this to false to disable csrf-magic's output handler, and therefore,
  67  * its rewriting capabilities. If you're serving non HTML content, you should
  68  * definitely set this false.
  69  */
  70 $GLOBALS['csrf']['rewrite'] = true;
  71
  72 /**
  73  * Whether or not to use IP addresses when binding a user to a token. This is
  74  * less reliable and less secure than sessions, but is useful when you need
  75  * to give facilities to anonymous users and do not wish to maintain a database
  76  * of valid keys.
  77  */
  78 $GLOBALS['csrf']['allow-ip'] = true;
  79
  80 /**
  81  * If this information is available, use the cookie by this name to determine
  82  * whether or not to allow the request. This is a shortcut implementation
  83  * very similar to 'key', but we randomly set the cookie ourselves.
  84  */
  85 $GLOBALS['csrf']['cookie'] = '__csrf_cookie';
  86
  87 /**
  88  * If this information is available, set this to a unique identifier (it
  89  * can be an integer or a unique username) for the current "user" of this
  90  * application. The token will then be globally valid for all of that user's
  91  * operations, but no one else. This requires that 'secret' be set.
  92  */
  93 $GLOBALS['csrf']['user'] = false;
  94
  95 /**
  96  * This is an arbitrary secret value associated with the user's session. This
  97  * will most probably be the contents of a cookie, as an attacker cannot easily
  98  * determine this information. Warning: If the attacker knows this value, they
  99  * can easily spoof a token. This is a generic implementation; sessions should
 100  * work in most cases.
 101  *
 102  * Why would you want to use this? Lets suppose you have a squid cache for your
 103  * website, and the presence of a session cookie bypasses it. Let's also say
 104  * you allow anonymous users to interact with the website; submitting forms
 105  * and AJAX. Previously, you didn't have any CSRF protection for anonymous users
 106  * and so they never got sessions; you don't want to start using sessions either,
 107  * otherwise you'll bypass the Squid cache. Setup a different cookie for CSRF
 108  * tokens, and have Squid ignore that cookie for get requests, for anonymous
 109  * users. (If you haven't guessed, this scheme was(?) used for MediaWiki).
 110  */
 111 $GLOBALS['csrf']['key'] = false;
 112
 113 /**
 114  * The name of the magic CSRF token that will be placed in all forms, i.e.
 115  * the contents of <input type="hidden" name="$name" value="CSRF-TOKEN" />
 116  */
 117 $GLOBALS['csrf']['input-name'] = '__csrf_magic';
 118
 119 /**
 120  * Set this to false if your site must work inside of frame/iframe elements,
 121  * but do so at your own risk: this configuration protects you against CSS
 122  * overlay attacks that defeat tokens.
 123  */
 124 $GLOBALS['csrf']['frame-breaker'] = true;
 125
 126 /**
 127  * Whether or not CSRF Magic should be allowed to start a new session in order
 128  * to determine the key.
 129  */
 130 $GLOBALS['csrf']['auto-session'] = true;
 131
 132 /**
 133  * Whether or not csrf-magic should produce XHTML style tags.
 134  */
 135 $GLOBALS['csrf']['xhtml'] = true;
 136
 137 // FUNCTIONS:
 138
 139 // Don't edit this!
 140 $GLOBALS['csrf']['version'] = '1.0.5';
 141
 142 /**
 143  * Rewrites <form> on the fly to add CSRF tokens to them. This can also
 144  * inject our JavaScript library.
 145  */
 146 function csrf_ob_handler($buffer, $flags) {
 147     // Even though the user told us to rewrite, we should do a quick heuristic
 148     // to check if the page is *actually* HTML. We don't begin rewriting until
 149     // we hit the first <html tag.
 150     static $is_html = false;
 151     if (!$is_html) {
 152         // not HTML until proven otherwise
 153         if (stripos($buffer, '<html') !== false) {
 154             $is_html = true;
 155         } else {
 156             return $buffer;
 157         }
 158     }
 159     $tokens = csrf_get_tokens();
 160     $name = $GLOBALS['csrf']['input-name'];
 161     $endslash = $GLOBALS['csrf']['xhtml'] ? ' /' : '';
 162     $input = "<input type='hidden' name='$name' value=\"$tokens\"$endslash>";
 163     $buffer = preg_replace('#(<form[^>]*method\s*=\s*["\']post["\'][^>]*>)#i', '$1' . $input, $buffer);
 164     if ($GLOBALS['csrf']['frame-breaker']) {
 165         $buffer = str_ireplace('</head>', '<script type="text/javascript">if (top != self) {top.location.href = self.location.href;}</script></head>', $buffer);
 166     }
 167     if ($js = $GLOBALS['csrf']['rewrite-js']) {
 168         $buffer = str_ireplace(
 169             '</head>',
 170             '<script type="text/javascript">'.
 171                 'var csrfMagicToken = "'.$tokens.'";'.
 172                 'var csrfMagicName = "'.$name.'";</script>'.
 173             '<script src="'.$js.'" type="text/javascript"></script></head>',
 174             $buffer
 175         );
 176         $script = '<script type="text/javascript">CsrfMagic.end();</script>';
 177         $buffer = str_ireplace('</body>', $script . '</body>', $buffer, $count);
 178         if (!$count) {
 179             $buffer .= $script;
 180         }
 181     }
 182     return $buffer;
 183 }
 184
 185 /**
 186  * Checks if this is a post request, and if it is, checks if the nonce is valid.
 187  * @param bool $fatal Whether or not to fatally error out if there is a problem.
 188  * @return True if check passes or is not necessary, false if failure.
 189  */
 190 function csrf_check($fatal = true) {
 191     if ($_SERVER['REQUEST_METHOD'] !== 'POST') return true;
 192     csrf_start();
 193     $name = $GLOBALS['csrf']['input-name'];
 194     $ok = false;
 195     $tokens = '';
 196     do {
 197         if (!isset($_POST[$name])) break;
 198         // we don't regenerate a token and check it because some token creation
 199         // schemes are volatile.
 200         $tokens = $_POST[$name];
 201         if (!csrf_check_tokens($tokens)) break;
 202         $ok = true;
 203     } while (false);
 204     if ($fatal && !$ok) {
 205         $callback = $GLOBALS['csrf']['callback'];
 206         if (trim($tokens, 'A..Za..z0..9:;,') !== '') $tokens = 'hidden';
 207         $callback($tokens);
 208         exit;
 209     }
 210     return $ok;
 211 }
 212
 213 /**
 214  * Retrieves a valid token(s) for a particular context. Tokens are separated
 215  * by semicolons.
 216  */
 217 function csrf_get_tokens() {
 218     $has_cookies = !empty($_COOKIE);
 219
 220     // $ip implements a composite key, which is sent if the user hasn't sent
 221     // any cookies. It may or may not be used, depending on whether or not
 222     // the cookies "stick"
 223     $secret = csrf_get_secret();
 224     if (!$has_cookies && $secret) {
 225         // :TODO: Harden this against proxy-spoofing attacks
 226         $ip = ';ip:' . csrf_hash($_SERVER['REMOTE_ADDR']);
 227     } else {
 228         $ip = '';
 229     }
 230     csrf_start();
 231
 232     // These are "strong" algorithms that don't require per se a secret
 233     if (session_id()) return 'sid:' . csrf_hash(session_id()) . $ip;
 234     if ($GLOBALS['csrf']['cookie']) {
 235         $val = csrf_generate_secret();
 236         setcookie($GLOBALS['csrf']['cookie'], $val);
 237         return 'cookie:' . csrf_hash($val) . $ip;
 238     }
 239     if ($GLOBALS['csrf']['key']) return 'key:' . csrf_hash($GLOBALS['csrf']['key']) . $ip;
 240     // These further algorithms require a server-side secret
 241     if (!$secret) return 'invalid';
 242     if ($GLOBALS['csrf']['user'] !== false) {
 243         return 'user:' . csrf_hash($GLOBALS['csrf']['user']);
 244     }
 245     if ($GLOBALS['csrf']['allow-ip']) {
 246         return ltrim($ip, ';');
 247     }
 248     return 'invalid';
 249 }
 250
 251 function csrf_flattenpost($data) {
 252     $ret = array();
 253     foreach($data as $n => $v) {
 254         $ret = array_merge($ret, csrf_flattenpost2(1, $n, $v));
 255     }
 256     return $ret;
 257 }
 258 function csrf_flattenpost2($level, $key, $data) {
 259     if(!is_array($data)) return array($key => $data);
 260     $ret = array();
 261     foreach($data as $n => $v) {
 262         $nk = $level >= 1 ? $key."[$n]" : "[$n]";
 263         $ret = array_merge($ret, csrf_flattenpost2($level+1, $nk, $v));
 264     }
 265     return $ret;
 266 }
 267
 268 /**
 269  * @param $tokens is safe for HTML consumption
 270  */
 271 function csrf_callback($tokens) {
 272     // (yes, $tokens is safe to echo without escaping)
 273     header($_SERVER['SERVER_PROTOCOL'] . ' 403 Forbidden');
 274     $data = '';
 275     foreach (csrf_flattenpost($_POST) as $key => $value) {
 276         if ($key == $GLOBALS['csrf']['input-name']) continue;
 277         $data .= '<input type="hidden" name="'.htmlspecialchars($key).'" value="'.htmlspecialchars($value).'" />';
 278     }
 279     echo "<html><head><title>CSRF check failed</title></head>
 280         <body>
 281         <p>CSRF check failed. Your form session may have expired, or you may not have
 282         cookies enabled.</p>
 283         <form method='post' action=''>$data<input type='submit' value='Try again' /></form>
 284         <p>Debug: $tokens</p></body></html>
 285 ";
 286 }
 287
 288 /**
 289  * Checks if a composite token is valid. Outward facing code should use this
 290  * instead of csrf_check_token()
 291  */
 292 function csrf_check_tokens($tokens) {
 293     if (is_string($tokens)) $tokens = explode(';', $tokens);
 294     foreach ($tokens as $token) {
 295         if (csrf_check_token($token)) return true;
 296     }
 297     return false;
 298 }
 299
 300 /**
 301  * Checks if a token is valid.
 302  */
 303 function csrf_check_token($token) {
 304     if (strpos($token, ':') === false) return false;
 305     list($type, $value) = explode(':', $token, 2);
 306     if (strpos($value, ',') === false) return false;
 307     list($x, $time) = explode(',', $token, 2);
 308     if ($GLOBALS['csrf']['expires']) {
 309         if (time() > $time + $GLOBALS['csrf']['expires']) return false;
 310     }
 311     switch ($type) {
 312         case 'sid':
 313             return $value === csrf_hash(session_id(), $time);
 314         case 'cookie':
 315             $n = $GLOBALS['csrf']['cookie'];
 316             if (!$n) return false;
 317             if (!isset($_COOKIE[$n])) return false;
 318             return $value === csrf_hash($_COOKIE[$n], $time);
 319         case 'key':
 320             if (!$GLOBALS['csrf']['key']) return false;
 321             return $value === csrf_hash($GLOBALS['csrf']['key'], $time);
 322         // We could disable these 'weaker' checks if 'key' was set, but
 323         // that doesn't make me feel good then about the cookie-based
 324         // implementation.
 325         case 'user':
 326             if (!csrf_get_secret()) return false;
 327             if ($GLOBALS['csrf']['user'] === false) return false;
 328             return $value === csrf_hash($GLOBALS['csrf']['user'], $time);
 329         case 'ip':
 330             if (!csrf_get_secret()) return false;
 331             // do not allow IP-based checks if the username is set, or if
 332             // the browser sent cookies
 333             if ($GLOBALS['csrf']['user'] !== false) return false;
 334             if (!empty($_COOKIE)) return false;
 335             if (!$GLOBALS['csrf']['allow-ip']) return false;
 336             return $value === csrf_hash($_SERVER['IP_ADDRESS'], $time);
 337     }
 338     return false;
 339 }
 340
 341 /**
 342  * Sets a configuration value.
 343  */
 344 function csrf_conf($key, $val) {
 345     if (!isset($GLOBALS['csrf'][$key])) {
 346         trigger_error('No such configuration ' . $key, E_USER_WARNING);
 347         return;
 348     }
 349     $GLOBALS['csrf'][$key] = $val;
 350 }
 351
 352 /**
 353  * Starts a session if we're allowed to.
 354  */
 355 function csrf_start() {
 356     if ($GLOBALS['csrf']['auto-session'] && !session_id()) {
 357         session_start();
 358     }
 359 }
 360
 361 /**
 362  * Retrieves the secret, and generates one if necessary.
 363  */
 364 function csrf_get_secret() {
 365     if ($GLOBALS['csrf']['secret']) return $GLOBALS['csrf']['secret'];
 366     $dir = dirname(__FILE__);
 367     $file = $dir . '/csrf-secret.php';
 368     $secret = '';
 369     if (file_exists($file)) {
 370         include $file;
 371         return $secret;
 372     }
 373     if (is_writable($dir)) {
 374         $secret = csrf_generate_secret();
 375         $fh = fopen($file, 'w');
 376         fwrite($fh, '<?php $secret = "'.$secret.'";' . PHP_EOL);
 377         fclose($fh);
 378         return $secret;
 379     }
 380     return '';
 381 }
 382
 383 /**
 384  * Generates a random string as the hash of time, microtime, and mt_rand.
 385  */
 386 function csrf_generate_secret($len = 32) {
 387     $r = '';
 388     for ($i = 0; $i < 32; $i++) {
 389         $r .= chr(mt_rand(0, 255));
 390     }
 391     $r .= time() . microtime();
 392     return sha1($r);
 393 }
 394
 395 /**
 396  * Generates a hash/expiry double. If time isn't set it will be calculated
 397  * from the current time.
 398  */
 399 function csrf_hash($value, $time = null) {
 400     if (!$time) $time = time();
 401     if (function_exists("hash_hmac")) {
 402         return hash_hmac('sha1', $time . ':' . $value, csrf_get_secret()) . ',' . $time;
 403     } else {
 404         $secret = csrf_get_secret();
 405         return sha1($secret . sha1($secret . $time . ':' . $value)) . ',' . $time;
 406     }
 407 }
 408
 409 // Load user configuration
 410 if (function_exists('csrf_startup')) csrf_startup();
 411 if (!$GLOBALS['csrf']['disable']) {
 412     // Initialize our handler
 413     if ($GLOBALS['csrf']['rewrite'])     ob_start('csrf_ob_handler');
 414     // Perform check
 415     if (!$GLOBALS['csrf']['defer'])      csrf_check();
 416 }