Release 1.0.5.
[csrf-magic.git] / csrf-magic.php
blobdfbd6d913212e073ccf2b69cbc18aaf164923f3f
1 <?php
3 /**
4 * @file
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).
13 * This library is PHP4 and PHP5 compatible.
16 // CONFIGURATION:
18 /**
19 * Convenience parameter for disabling all of our functionality;
20 * equivalent to setting 'rewrite' to false and 'defer' to true.
22 $GLOBALS['csrf']['disable'] = false;
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.
32 $GLOBALS['csrf']['defer'] = false;
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.
39 $GLOBALS['csrf']['expires'] = 7200;
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.
46 $GLOBALS['csrf']['callback'] = 'csrf_callback';
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.
54 $GLOBALS['csrf']['rewrite-js'] = false;
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.
61 $GLOBALS['csrf']['secret'] = '';
62 // nota bene: library code should use csrf_get_secret() and not access
63 // this global directly
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.
70 $GLOBALS['csrf']['rewrite'] = true;
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.
78 $GLOBALS['csrf']['allow-ip'] = true;
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.
85 $GLOBALS['csrf']['cookie'] = '__csrf_cookie';
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.
93 $GLOBALS['csrf']['user'] = false;
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.
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).
111 $GLOBALS['csrf']['key'] = false;
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" />
117 $GLOBALS['csrf']['input-name'] = '__csrf_magic';
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.
124 $GLOBALS['csrf']['frame-breaker'] = true;
127 * Whether or not CSRF Magic should be allowed to start a new session in order
128 * to determine the key.
130 $GLOBALS['csrf']['auto-session'] = true;
133 * Whether or not csrf-magic should produce XHTML style tags.
135 $GLOBALS['csrf']['xhtml'] = true;
137 // FUNCTIONS:
139 // Don't edit this!
140 $GLOBALS['csrf']['version'] = '1.0.5';
143 * Rewrites <form> on the fly to add CSRF tokens to them. This can also
144 * inject our JavaScript library.
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;
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);
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
176 $script = '<script type="text/javascript">CsrfMagic.end();</script>';
177 $buffer = str_ireplace('</body>', $script . '</body>', $buffer, $count);
178 if (!$count) {
179 $buffer .= $script;
182 return $buffer;
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.
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;
210 return $ok;
214 * Retrieves a valid token(s) for a particular context. Tokens are separated
215 * by semicolons.
217 function csrf_get_tokens() {
218 $has_cookies = !empty($_COOKIE);
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 = '';
230 csrf_start();
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;
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']);
245 if ($GLOBALS['csrf']['allow-ip']) {
246 return ltrim($ip, ';');
248 return 'invalid';
251 function csrf_flattenpost($data) {
252 $ret = array();
253 foreach($data as $n => $v) {
254 $ret = array_merge($ret, csrf_flattenpost2(1, $n, $v));
256 return $ret;
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));
265 return $ret;
269 * @param $tokens is safe for HTML consumption
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).'" />';
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>
289 * Checks if a composite token is valid. Outward facing code should use this
290 * instead of csrf_check_token()
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;
297 return false;
301 * Checks if a token is valid.
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;
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);
338 return false;
342 * Sets a configuration value.
344 function csrf_conf($key, $val) {
345 if (!isset($GLOBALS['csrf'][$key])) {
346 trigger_error('No such configuration ' . $key, E_USER_WARNING);
347 return;
349 $GLOBALS['csrf'][$key] = $val;
353 * Starts a session if we're allowed to.
355 function csrf_start() {
356 if ($GLOBALS['csrf']['auto-session'] && !session_id()) {
357 session_start();
362 * Retrieves the secret, and generates one if necessary.
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;
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;
380 return '';
384 * Generates a random string as the hash of time, microtime, and mt_rand.
386 function csrf_generate_secret($len = 32) {
387 $r = '';
388 for ($i = 0; $i < 32; $i++) {
389 $r .= chr(mt_rand(0, 255));
391 $r .= time() . microtime();
392 return sha1($r);
396 * Generates a hash/expiry double. If time isn't set it will be calculated
397 * from the current time.
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;
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();