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  * By default, when you include this file csrf-magic will automatically check
  20  * and exit if the CSRF token is invalid. This will defer executing
  21  * csrf_check() until you're ready. You can also pass false as a parameter to
  22  * that function, in which case the function will not exit but instead return
  23  * a boolean false if the CSRF check failed. This allows for tighter integration
  24  * with your system.
  25  */
  26 $GLOBALS['csrf']['defer'] = false;
  27
  28 /**
  29  * Callback function to execute when there's the CSRF check fails and
  30  * $fatal == true (see csrf_check). This will usually output an error message
  31  * about the failure.
  32  */
  33 $GLOBALS['csrf']['callback'] = 'csrf_callback';
  34
  35 /**
  36  * Whether or not to include our JavaScript library which also rewrites
  37  * AJAX requests on this domain. Set this to the web path. This setting only works
  38  * with supported JavaScript libraries in Internet Explorer; see README.txt for
  39  * a list of supported libraries.
  40  */
  41 $GLOBALS['csrf']['rewrite-js'] = false;
  42
  43 /**
  44  * A secret key used when hashing items. Please generate a random string and
  45  * place it here. If you change this value, all previously generated tokens
  46  * will become invalid.
  47  */
  48 $GLOBALS['csrf']['secret'] = '';
  49
  50 /**
  51  * Set this to false to disable csrf-magic's output handler, and therefore,
  52  * its rewriting capabilities. If you're serving non HTML content, you should
  53  * definitely set this false.
  54  */
  55 $GLOBALS['csrf']['rewrite'] = true;
  56
  57 /**
  58  * Whether or not to use IP addresses when binding a user to a token. This is
  59  * less reliable and less secure than sessions, but is useful when you need
  60  * to give facilities to anonymous users and do not wish to maintain a database
  61  * of valid keys.
  62  */
  63 $GLOBALS['csrf']['allow-ip'] = true;
  64
  65 /**
  66  * If this information is available, set this to a unique identifier (it
  67  * can be an integer or a unique username) for the current "user" of this
  68  * application. The token will then be globally valid for all of that user's
  69  * operations, but no one else. This requires that 'secret' be set.
  70  */
  71 $GLOBALS['csrf']['user'] = false;
  72
  73 /**
  74  * This is an arbitrary secret value associated with the user's session. This
  75  * will most probably be the contents of a cookie, as an attacker cannot easily
  76  * determine this information. Warning: If the attacker knows this value, they
  77  * can easily spoof a token. This is a generic implementation; sessions should
  78  * work in most cases.
  79  *
  80  * Why would you want to use this? Lets suppose you have a squid cache for your
  81  * website, and the presence of a session cookie bypasses it. Let's also say
  82  * you allow anonymous users to interact with the website; submitting forms
  83  * and AJAX. Previously, you didn't have any CSRF protection for anonymous users
  84  * and so they never got sessions; you don't want to start using sessions either,
  85  * otherwise you'll bypass the Squid cache. Setup a different cookie for CSRF
  86  * tokens, and have Squid ignore that cookie for get requests, for anonymous
  87  * users. (If you haven't guessed, this scheme was(?) used for MediaWiki).
  88  */
  89 $GLOBALS['csrf']['key'] = false;
  90
  91 /**
  92  * The name of the magic CSRF token that will be placed in all forms, i.e.
  93  * the contents of <input type="hidden" name="$name" value="CSRF-TOKEN" />
  94  */
  95 $GLOBALS['csrf']['input-name'] = '__csrf_magic';
  96
  97 /**
  98  * Whether or not CSRF Magic should be allowed to start a new session in order
  99  * to determine the key.
 100  */
 101 $GLOBALS['csrf']['auto-session'] = true;
 102
 103 /**
 104  * Whether or not csrf-magic should produce XHTML style tags.
 105  */
 106 $GLOBALS['csrf']['xhtml'] = true;
 107
 108 // FUNCTIONS:
 109
 110 // Don't edit this!
 111 $GLOBALS['csrf']['version'] = '1.0.0';
 112
 113 /**
 114  * Rewrites <form> on the fly to add CSRF tokens to them. This can also
 115  * inject our JavaScript library.
 116  */
 117 function csrf_ob_handler($buffer, $flags) {
 118     // Even though the user told us to rewrite, we should do a quick heuristic
 119     // to check if the page is *actually* HTML. We don't begin rewriting until
 120     // we hit the first <html tag.
 121     static $is_html = false;
 122     if (!$is_html) {
 123         // not HTML until proven otherwise
 124         if (stripos($buffer, '<html') !== false) {
 125             $is_html = true;
 126         } else {
 127             return $buffer;
 128         }
 129     }
 130     $tokens = csrf_get_tokens();
 131     $name = $GLOBALS['csrf']['input-name'];
 132     $endslash = $GLOBALS['csrf']['xhtml'] ? ' /' : '';
 133     $input = "<input type='hidden' name='$name' value=\"$tokens\"$endslash>";
 134     $buffer = preg_replace('#(<form[^>]*method\s*=\s*["\']post["\'][^>]*>)#i', '$1' . $input, $buffer);
 135     if ($js = $GLOBALS['csrf']['rewrite-js']) {
 136         $buffer = preg_replace(
 137             '#(</head>)#i',
 138             '<script type="text/javascript">'.
 139                 'var csrfMagicToken = "'.$tokens.'";'.
 140                 'var csrfMagicName = "'.$name.'";</script>'.
 141             '<script src="'.$js.'" type="text/javascript"></script>$1',
 142             $buffer
 143         );
 144         $script = '<script type="text/javascript">CsrfMagic.end();</script>';
 145         $buffer = str_ireplace('</body>', $script . '</body>', $buffer, $count);
 146         if (!$count) {
 147             $buffer .= $script;
 148         }
 149     }
 150     return $buffer;
 151 }
 152
 153 /**
 154  * Checks if this is a post request, and if it is, checks if the nonce is valid.
 155  * @param bool $fatal Whether or not to fatally error out if there is a problem.
 156  * @return True if check passes or is not necessary, false if failure.
 157  */
 158 function csrf_check($fatal = true) {
 159     if ($_SERVER['REQUEST_METHOD'] !== 'POST') return true;
 160     csrf_start();
 161     $name = $GLOBALS['csrf']['input-name'];
 162     $ok = false;
 163     do {
 164         if (!isset($_POST[$name])) break;
 165         // we don't regenerate a token and check it because some token creation
 166         // schemes are volatile.
 167         if (!csrf_check_tokens($_POST[$name])) break;
 168         $ok = true;
 169     } while (false);
 170     if ($fatal && !$ok) {
 171         $callback = $GLOBALS['csrf']['callback'];
 172         $callback();
 173         exit;
 174     }
 175     return $ok;
 176 }
 177
 178 /**
 179  * Retrieves a valid token(s) for a particular context. Tokens are separated
 180  * by semicolons.
 181  */
 182 function csrf_get_tokens() {
 183     $secret = csrf_get_secret();
 184     $has_cookies = !empty($_COOKIE);
 185
 186     // $ip implements a composite key, which is sent if the user hasn't sent
 187     // any cookies. It may or may not be used, depending on whether or not
 188     // the cookies "stick"
 189     if (!$has_cookies && $secret) {
 190         // :TODO: Harden this against proxy-spoofing attacks
 191         $ip = ';ip:' . sha1($secret . $_SERVER['IP_ADDRESS']);
 192     } else {
 193         $ip = '';
 194     }
 195     csrf_start();
 196
 197     // These are "strong" algorithms that don't require per se a secret
 198     if (session_id()) return 'sid:' . sha1($secret . session_id()) . $ip;
 199     if ($GLOBALS['csrf']['key']) return 'key:' . sha1($secret . $GLOBALS['csrf']['key']) . $ip;
 200     // These further algorithms require a server-side secret
 201     if ($secret === '') return 'invalid';
 202     if ($GLOBALS['csrf']['user'] !== false) {
 203         return 'user:' . sha1($secret . $GLOBALS['csrf']['user']);
 204     }
 205     if ($GLOBALS['csrf']['allow-ip']) {
 206         return ltrim($ip, ';');
 207     }
 208     return 'invalid';
 209 }
 210
 211 function csrf_callback() {
 212     header($_SERVER['SERVER_PROTOCOL'] . ' 403 Forbidden');
 213     echo "<html><head><title>CSRF check failed</title></head><body>CSRF check failed. Please enable cookies.</body></html>
 214 ";
 215 }
 216
 217 /**
 218  * Checks if a composite token is valid. Outward facing code should use this
 219  * instead of csrf_check_token()
 220  */
 221 function csrf_check_tokens($tokens) {
 222     if (is_string($tokens)) $tokens = explode(';', $tokens);
 223     foreach ($tokens as $token) {
 224         if (csrf_check_token($token)) return true;
 225     }
 226     return false;
 227 }
 228
 229 /**
 230  * Checks if a token is valid.
 231  */
 232 function csrf_check_token($token) {
 233     if (strpos($token, ':') === false) return false;
 234     list($type, $value) = explode(':', $token, 2);
 235     $secret = csrf_get_secret();
 236     switch ($type) {
 237         case 'sid':
 238             return $value === sha1($secret . session_id());
 239         case 'key':
 240             if (!$GLOBALS['csrf']['key']) return false;
 241             return $value === sha1($secret . $GLOBALS['csrf']['key']);
 242         // We could disable these 'weaker' checks if 'key' was set, but
 243         // that doesn't make me feel good then about the cookie-based
 244         // implementation.
 245         case 'user':
 246             if ($GLOBALS['csrf']['secret'] === '') return false;
 247             if ($GLOBALS['csrf']['user'] === false) return false;
 248             return $value === sha1($secret . $GLOBALS['csrf']['user']);
 249         case 'ip':
 250             if (csrf_get_secret() === '') return false;
 251             // do not allow IP-based checks if the username is set, or if
 252             // the browser sent cookies
 253             if ($GLOBALS['csrf']['user'] !== false) return false;
 254             if (!empty($_COOKIE)) return false;
 255             if (!$GLOBALS['csrf']['allow-ip']) return false;
 256             return $value === sha1($secret . $_SERVER['IP_ADDRESS']);
 257     }
 258     return false;
 259 }
 260
 261 /**
 262  * Sets a configuration value.
 263  */
 264 function csrf_conf($key, $val) {
 265     if (!isset($GLOBALS['csrf'][$key])) {
 266         trigger_error('No such configuration ' . $key, E_USER_WARNING);
 267         return;
 268     }
 269     $GLOBALS['csrf'][$key] = $val;
 270 }
 271
 272 /**
 273  * Starts a session if we're allowed to.
 274  */
 275 function csrf_start() {
 276     if ($GLOBALS['csrf']['auto-session'] && !session_id()) {
 277         session_start();
 278     }
 279 }
 280
 281 /**
 282  * Retrieves the secret, and generates one if necessary.
 283  */
 284 function csrf_get_secret() {
 285     if ($GLOBALS['csrf']['secret']) return $GLOBALS['csrf']['secret'];
 286     $dir = dirname(__FILE__);
 287     $file = $dir . '/csrf-secret.php';
 288     $secret = '';
 289     if (file_exists($file)) {
 290         include $file;
 291         return $secret;
 292     }
 293     if (is_writable($dir)) {
 294         for ($i = 0; $i < 32; $i++) $secret .= '\\x' . dechex(mt_rand(32, 126));
 295         $fh = fopen($file, 'w');
 296         fwrite($fh, '<?php $secret = "'.$secret.'";' . PHP_EOL);
 297         fclose($fh);
 298         return $secret;
 299     }
 300     return '';
 301 }
 302
 303 // Load user configuration
 304 if (function_exists('csrf_startup')) csrf_startup();
 305 // Initialize our handler
 306 if ($GLOBALS['csrf']['rewrite'])     ob_start('csrf_ob_handler');
 307 // Perform check
 308 if (!$GLOBALS['csrf']['defer'])      csrf_check();