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     $token = csrf_get_token();
 131     $name = $GLOBALS['csrf']['input-name'];
 132     $endslash = $GLOBALS['csrf']['xhtml'] ? ' /' : '';
 133     $input = "<input type='hidden' name='$name' value=\"$token\"$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 = "'.$token.'";'.
 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_token($_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 for a particular context.
 180  */
 181 function csrf_get_token() {
 182     $secret = csrf_get_secret();
 183     csrf_start();
 184     // These are "strong" algorithms that don't require per se a secret
 185     if (session_id()) return 'sid:' . sha1($secret . session_id());
 186     if ($GLOBALS['csrf']['key']) return 'key:' . sha1($secret . $GLOBALS['csrf']['key']);
 187     // These further algorithms require a server-side secret
 188     if ($secret === '') return 'invalid';
 189     if ($GLOBALS['csrf']['user'] !== false) {
 190         return 'user:' . sha1($secret . $GLOBALS['csrf']['user']);
 191     }
 192     if ($GLOBALS['csrf']['allow-ip']) {
 193         // :TODO: Harden this against proxy-spoofing attacks
 194         return 'ip:' . sha1($secret . $_SERVER['IP_ADDRESS']);
 195     }
 196     return 'invalid';
 197 }
 198
 199 function csrf_callback() {
 200     header($_SERVER['SERVER_PROTOCOL'] . ' 403 Forbidden');
 201     echo "<html><head><title>CSRF check failed</title></head><body>CSRF check failed. Please enable cookies.</body></html>
 202 ";
 203 }
 204
 205 /**
 206  * Checks if a token is valid.
 207  */
 208 function csrf_check_token($token) {
 209     if (strpos($token, ':') === false) return false;
 210     list($type, $value) = explode(':', $token, 2);
 211     $secret = csrf_get_secret();
 212     switch ($type) {
 213         case 'sid':
 214             return $value === sha1($secret . session_id());
 215         case 'key':
 216             if (!$GLOBALS['csrf']['key']) return false;
 217             return $value === sha1($secret . $GLOBALS['csrf']['key']);
 218         // We could disable these 'weaker' checks if 'key' was set, but
 219         // that doesn't make me feel good then about the cookie-based
 220         // implementation.
 221         case 'user':
 222             if ($GLOBALS['csrf']['secret'] === '') return false;
 223             if ($GLOBALS['csrf']['user'] === false) return false;
 224             return $value === sha1($secret . $GLOBALS['csrf']['user']);
 225         case 'ip':
 226             if ($GLOBALS['csrf']['secret'] === '') return false;
 227             // do not allow IP-based checks if the username is set
 228             if ($GLOBALS['csrf']['user'] !== false) return false;
 229             if (!$GLOBALS['csrf']['allow-ip']) return false;
 230             return $value === sha1($secret . $_SERVER['IP_ADDRESS']);
 231     }
 232     return false;
 233 }
 234
 235 /**
 236  * Sets a configuration value.
 237  */
 238 function csrf_conf($key, $val) {
 239     if (!isset($GLOBALS['csrf'][$key])) {
 240         trigger_error('No such configuration ' . $key, E_USER_WARNING);
 241         return;
 242     }
 243     $GLOBALS['csrf'][$key] = $val;
 244 }
 245
 246 /**
 247  * Starts a session if we're allowed to.
 248  */
 249 function csrf_start() {
 250     if ($GLOBALS['csrf']['auto-session'] && !session_id()) {
 251         session_start();
 252     }
 253 }
 254
 255 /**
 256  * Retrieves the secret, and generates one if necessary.
 257  */
 258 function csrf_get_secret() {
 259     if ($GLOBALS['csrf']['secret']) return $GLOBALS['csrf']['secret'];
 260     $dir = dirname(__FILE__);
 261     $file = $dir . '/csrf-secret.php';
 262     $secret = '';
 263     if (file_exists($file)) {
 264         include $file;
 265         return $secret;
 266     }
 267     if (is_writable($dir)) {
 268         for ($i = 0; $i < 32; $i++) $secret .= '\\x' . dechex(mt_rand(32, 126));
 269         $fh = fopen($file, 'w');
 270         fwrite($fh, '<?php $secret = "'.$secret.'";' . PHP_EOL);
 271         fclose($fh);
 272         return $secret;
 273     }
 274     return '';
 275 }
 276
 277 // Load user configuration
 278 if (function_exists('csrf_startup')) csrf_startup();
 279 // Initialize our handler
 280 if ($GLOBALS['csrf']['rewrite'])     ob_start('csrf_ob_handler');
 281 // Perform check
 282 if (!$GLOBALS['csrf']['defer'])      csrf_check();