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  * Whether or not to use IP addresses when binding a user to a token. This is
  52  * less reliable and less secure than sessions, but is useful when you need
  53  * to give facilities to anonymous users and do not wish to maintain a database
  54  * of valid keys.
  55  */
  56 $GLOBALS['csrf']['allow-ip'] = true;
  57
  58 /**
  59  * If this information is available, set this to a unique identifier (it
  60  * can be an integer or a unique username) for the current "user" of this
  61  * application. The token will then be globally valid for all of that user's
  62  * operations, but no one else. This requires that 'secret' be set.
  63  */
  64 $GLOBALS['csrf']['user'] = false;
  65
  66 /**
  67  * This is an arbitrary secret value associated with the user's session. This
  68  * will most probably be the contents of a cookie, as an attacker cannot easily
  69  * determine this information. Warning: If the attacker knows this value, they
  70  * can easily spoof a token. This is a generic implementation; sessions should
  71  * work in most cases.
  72  *
  73  * Why would you want to use this? Lets suppose you have a squid cache for your
  74  * website, and the presence of a session cookie bypasses it. Let's also say
  75  * you allow anonymous users to interact with the website; submitting forms
  76  * and AJAX. Previously, you didn't have any CSRF protection for anonymous users
  77  * and so they never got sessions; you don't want to start using sessions either,
  78  * otherwise you'll bypass the Squid cache. Setup a different cookie for CSRF
  79  * tokens, and have Squid ignore that cookie for get requests, for anonymous
  80  * users. (If you haven't guessed, this scheme was(?) used for MediaWiki).
  81  */
  82 $GLOBALS['csrf']['key'] = false;
  83
  84 /**
  85  * The name of the magic CSRF token that will be placed in all forms, i.e.
  86  * the contents of <input type="hidden" name="$name" value="CSRF-TOKEN" />
  87  */
  88 $GLOBALS['csrf']['input-name'] = '__csrf_magic';
  89
  90 /**
  91  * Whether or not CSRF Magic should be allowed to start a new session in order
  92  * to determine the key.
  93  */
  94 $GLOBALS['csrf']['auto-session'] = true;
  95
  96 /**
  97  * Whether or not csrf-magic should produce XHTML style tags.
  98  */
  99 $GLOBALS['csrf']['xhtml'] = true;
 100
 101 // FUNCTIONS:
 102
 103 /**
 104  * Rewrites <form> on the fly to add CSRF tokens to them. This can also
 105  * inject our JavaScript library.
 106  */
 107 function csrf_ob_handler($buffer, $flags) {
 108     $token = csrf_get_token();
 109     $name = $GLOBALS['csrf']['input-name'];
 110     $endslash = $GLOBALS['csrf']['xhtml'] ? ' /' : '';
 111     $input = "<input type='hidden' name='$name' value=\"$token\"$endslash>";
 112     $buffer = preg_replace('#(<form[^>]*method\s*=\s*["\']post["\'][^>]*>)#i', '$1' . $input, $buffer);
 113     if ($js = $GLOBALS['csrf']['rewrite-js']) {
 114         $buffer = preg_replace(
 115             '#(</head>)#i',
 116             '<script type="text/javascript">'.
 117                 'var csrfMagicToken = "'.$token.'";'.
 118                 'var csrfMagicName = "'.$name.'";</script>'.
 119             '<script src="'.$js.'" type="text/javascript"></script>$1',
 120             $buffer
 121         );
 122     }
 123     return $buffer;
 124 }
 125
 126 /**
 127  * Checks if this is a post request, and if it is, checks if the nonce is valid.
 128  * @param bool $fatal Whether or not to fatally error out if there is a problem.
 129  * @return True if check passes or is not necessary, false if failure.
 130  */
 131 function csrf_check($fatal = true) {
 132     if ($_SERVER['REQUEST_METHOD'] !== 'POST') return true;
 133     csrf_start();
 134     $name = $GLOBALS['csrf']['input-name'];
 135     $ok = false;
 136     do {
 137         if (!isset($_POST[$name])) break;
 138         // we don't regenerate a token and check it because some token creation
 139         // schemes are volatile.
 140         if (!csrf_check_token($_POST[$name])) break;
 141         $ok = true;
 142     } while (false);
 143     if ($fatal && !$ok) {
 144         $callback = $GLOBALS['csrf']['callback'];
 145         $callback();
 146         exit;
 147     }
 148     return $ok;
 149 }
 150
 151 /**
 152  * Retrieves a valid token for a particular context.
 153  */
 154 function csrf_get_token() {
 155     $secret = csrf_get_secret();
 156     csrf_start();
 157     // These are "strong" algorithms that don't require per se a secret
 158     if (session_id()) return 'sid:' . sha1($secret . session_id());
 159     if ($GLOBALS['csrf']['key']) return 'key:' . sha1($secret . $GLOBALS['csrf']['key']);
 160     // These further algorithms require a server-side secret
 161     if ($secret === '') return 'invalid';
 162     if ($GLOBALS['csrf']['user'] !== false) {
 163         return 'user:' . sha1($secret . $GLOBALS['csrf']['user']);
 164     }
 165     if ($GLOBALS['csrf']['allow-ip']) {
 166         // :TODO: Harden this against proxy-spoofing attacks
 167         return 'ip:' . sha1($secret . $_SERVER['IP_ADDRESS']);
 168     }
 169     return 'invalid';
 170 }
 171
 172 function csrf_callback() {
 173     echo "<html><body>CSRF check failed. Please enable cookies.</body></html>
 174 ";
 175 }
 176
 177 /**
 178  * Checks if a token is valid.
 179  */
 180 function csrf_check_token($token) {
 181     if (strpos($token, ':') === false) return false;
 182     list($type, $value) = explode(':', $token, 2);
 183     $secret = csrf_get_secret();
 184     switch ($type) {
 185         case 'sid':
 186             return $value === sha1($secret . session_id());
 187         case 'key':
 188             if (!$GLOBALS['csrf']['key']) return false;
 189             return $value === sha1($secret . $GLOBALS['csrf']['key']);
 190         // We could disable these 'weaker' checks if 'key' was set, but
 191         // that doesn't make me feel good then about the cookie-based
 192         // implementation.
 193         case 'user':
 194             if ($GLOBALS['csrf']['secret'] === '') return false;
 195             if ($GLOBALS['csrf']['user'] === false) return false;
 196             return $value === sha1($secret . $GLOBALS['csrf']['user']);
 197         case 'ip':
 198             if ($GLOBALS['csrf']['secret'] === '') return false;
 199             // do not allow IP-based checks if the username is set
 200             if ($GLOBALS['csrf']['user'] !== false) return false;
 201             if (!$GLOBALS['csrf']['allow-ip']) return false;
 202             return $value === sha1($secret . $_SERVER['IP_ADDRESS']);
 203     }
 204     return false;
 205 }
 206
 207 /**
 208  * Sets a configuration value.
 209  */
 210 function csrf_conf($key, $val) {
 211     if (!isset($GLOBALS['csrf'][$key])) {
 212         trigger_error('No such configuration ' . $key, E_USER_WARNING);
 213         return;
 214     }
 215     $GLOBALS['csrf'][$key] = $val;
 216 }
 217
 218 /**
 219  * Starts a session if we're allowed to.
 220  */
 221 function csrf_start() {
 222     if ($GLOBALS['csrf']['auto-session'] && !session_id()) {
 223         session_start();
 224     }
 225 }
 226
 227 /**
 228  * Retrieves the secret, and generates one if necessary.
 229  */
 230 function csrf_get_secret() {
 231     if ($GLOBALS['csrf']['secret']) return $GLOBALS['csrf']['secret'];
 232     $dir = dirname(__FILE__);
 233     $file = $dir . '/csrf-secret.php';
 234     $secret = '';
 235     if (file_exists($file)) {
 236         include $file;
 237         return $secret;
 238     }
 239     if (is_writable($dir)) {
 240         for ($i = 0; $i < 32; $i++) $secret .= '\\x' . dechex(mt_rand(32, 126));
 241         $fh = fopen($file, 'w');
 242         fwrite($fh, '<?php $secret = "'.$secret.'";' . PHP_EOL);
 243         fclose($fh);
 244         return $secret;
 245     }
 246     return '';
 247 }
 248
 249 // Initialize our handler
 250 ob_start('csrf_ob_handler');
 251 // Load user configuration
 252 if (function_exists('csrf_startup')) csrf_startup();
 253 // Perform check
 254 if (!$GLOBALS['csrf']['defer']) csrf_check();