csrf-magic.php 14.3 KB
Newer Older
Ad Schellevis's avatar
Ad Schellevis committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
<?php

/**
 * @file
 *
 * csrf-magic is a PHP library that makes adding CSRF-protection to your
 * web applications a snap. No need to modify every form or create a database
 * of valid nonces; just include this file at the top of every
 * web-accessible page (or even better, your common include file included
 * in every page), and forget about it! (There are, of course, configuration
 * options for advanced users).
 *
 * This library is PHP4 and PHP5 compatible.
 */

// CONFIGURATION:

/**
 * By default, when you include this file csrf-magic will automatically check
 * and exit if the CSRF token is invalid. This will defer executing
 * csrf_check() until you're ready.  You can also pass false as a parameter to
 * that function, in which case the function will not exit but instead return
 * a boolean false if the CSRF check failed. This allows for tighter integration
 * with your system.
 */
$GLOBALS['csrf']['defer'] = false;

/**
 * This is the amount of seconds you wish to allow before any token becomes
 * invalid; the default is two hours, which should be more than enough for
 * most websites.
 */
$GLOBALS['csrf']['expires'] = 7200;

/**
 * Callback function to execute when there's the CSRF check fails and
 * $fatal == true (see csrf_check). This will usually output an error message
 * about the failure.
 */
$GLOBALS['csrf']['callback'] = 'csrf_callback';

/**
 * Whether or not to include our JavaScript library which also rewrites
 * AJAX requests on this domain. Set this to the web path. This setting only works
 * with supported JavaScript libraries in Internet Explorer; see README.txt for
 * a list of supported libraries.
 */
$GLOBALS['csrf']['rewrite-js'] = false;

/**
 * A secret key used when hashing items. Please generate a random string and
 * place it here. If you change this value, all previously generated tokens
 * will become invalid.
 */
$GLOBALS['csrf']['secret'] = '';
// nota bene: library code should use csrf_get_secret() and not access
// this global directly

/**
 * Set this to false to disable csrf-magic's output handler, and therefore,
 * its rewriting capabilities. If you're serving non HTML content, you should
 * definitely set this false.
 */
$GLOBALS['csrf']['rewrite'] = true;

/**
 * Whether or not to use IP addresses when binding a user to a token. This is
 * less reliable and less secure than sessions, but is useful when you need
 * to give facilities to anonymous users and do not wish to maintain a database
 * of valid keys.
 */
$GLOBALS['csrf']['allow-ip'] = true;

/**
 * If this information is available, use the cookie by this name to determine
 * whether or not to allow the request. This is a shortcut implementation
 * very similar to 'key', but we randomly set the cookie ourselves.
 */
$GLOBALS['csrf']['cookie'] = '__csrf_cookie';

/**
 * If this information is available, set this to a unique identifier (it
 * can be an integer or a unique username) for the current "user" of this
 * application. The token will then be globally valid for all of that user's
 * operations, but no one else. This requires that 'secret' be set.
 */
$GLOBALS['csrf']['user'] = false;

/**
 * This is an arbitrary secret value associated with the user's session. This
 * will most probably be the contents of a cookie, as an attacker cannot easily
 * determine this information. Warning: If the attacker knows this value, they
 * can easily spoof a token. This is a generic implementation; sessions should
 * work in most cases.
 *
 * Why would you want to use this? Lets suppose you have a squid cache for your
 * website, and the presence of a session cookie bypasses it. Let's also say
 * you allow anonymous users to interact with the website; submitting forms
 * and AJAX. Previously, you didn't have any CSRF protection for anonymous users
 * and so they never got sessions; you don't want to start using sessions either,
 * otherwise you'll bypass the Squid cache. Setup a different cookie for CSRF
 * tokens, and have Squid ignore that cookie for get requests, for anonymous
 * users. (If you haven't guessed, this scheme was(?) used for MediaWiki).
 */
$GLOBALS['csrf']['key'] = false;

/**
 * The name of the magic CSRF token that will be placed in all forms, i.e.
 * the contents of <input type="hidden" name="$name" value="CSRF-TOKEN" />
 */
$GLOBALS['csrf']['input-name'] = '__csrf_magic';

/**
 * Set this to false if your site must work inside of frame/iframe elements,
 * but do so at your own risk: this configuration protects you against CSS
 * overlay attacks that defeat tokens.
 */
$GLOBALS['csrf']['frame-breaker'] = true;

/**
 * Whether or not CSRF Magic should be allowed to start a new session in order
 * to determine the key.
 */
$GLOBALS['csrf']['auto-session'] = true;

/**
 * Whether or not csrf-magic should produce XHTML style tags.
 */
$GLOBALS['csrf']['xhtml'] = true;

// FUNCTIONS:

// Don't edit this!
$GLOBALS['csrf']['version'] = '1.0.4';

/**
 * Rewrites <form> on the fly to add CSRF tokens to them. This can also
 * inject our JavaScript library.
 */
140 141
function csrf_ob_handler($buffer, $flags)
{
Ad Schellevis's avatar
Ad Schellevis committed
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
    // Even though the user told us to rewrite, we should do a quick heuristic
    // to check if the page is *actually* HTML. We don't begin rewriting until
    // we hit the first <html tag.
    static $is_html = false;
    if (!$is_html) {
        // not HTML until proven otherwise
        if (stripos($buffer, '<html') !== false) {
            $is_html = true;
        } else {
            return $buffer;
        }
    }
    $tokens = csrf_get_tokens();
    $name = $GLOBALS['csrf']['input-name'];
    $endslash = $GLOBALS['csrf']['xhtml'] ? ' /' : '';
    $input = "<input type='hidden' name='$name' value=\"$tokens\"$endslash>";
    $buffer = preg_replace('#(<form[^>]*method\s*=\s*["\']post["\'][^>]*>)#i', '$1' . $input, $buffer);
    if ($GLOBALS['csrf']['frame-breaker']) {
        $buffer = str_ireplace('</head>', '<script type="text/javascript">if (top != self) {top.location.href = self.location.href;}</script></head>', $buffer);
    }
    if ($js = $GLOBALS['csrf']['rewrite-js']) {
        $buffer = str_ireplace(
            '</head>',
            '<script type="text/javascript">'.
166 167
            'var csrfMagicToken = "'.$tokens.'";'.
            'var csrfMagicName = "'.$name.'";</script>'.
Ad Schellevis's avatar
Ad Schellevis committed
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
            '<script src="'.$js.'" type="text/javascript"></script></head>',
            $buffer
        );
        $script = '<script type="text/javascript">CsrfMagic.end();</script>';
        $buffer = str_ireplace('</body>', $script . '</body>', $buffer, $count);
        if (!$count) {
            $buffer .= $script;
        }
    }
    return $buffer;
}

/**
 * Checks if this is a post request, and if it is, checks if the nonce is valid.
 * @param bool $fatal Whether or not to fatally error out if there is a problem.
 * @return True if check passes or is not necessary, false if failure.
 */
185 186 187 188 189
function csrf_check($fatal = true)
{
    if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
        return true;
    }
Ad Schellevis's avatar
Ad Schellevis committed
190 191 192 193 194
    csrf_start();
    $name = $GLOBALS['csrf']['input-name'];
    $ok = false;
    $tokens = '';
    do {
195 196 197
        if (!isset($_POST[$name])) {
            break;
        }
Ad Schellevis's avatar
Ad Schellevis committed
198 199 200
        // we don't regenerate a token and check it because some token creation
        // schemes are volatile.
        $tokens = $_POST[$name];
201 202 203
        if (!csrf_check_tokens($tokens)) {
            break;
        }
Ad Schellevis's avatar
Ad Schellevis committed
204 205 206 207
        $ok = true;
    } while (false);
    if ($fatal && !$ok) {
        $callback = $GLOBALS['csrf']['callback'];
208 209 210
        if (trim($tokens, 'A..Za..z0..9:;,') !== '') {
            $tokens = 'hidden';
        }
Ad Schellevis's avatar
Ad Schellevis committed
211 212 213 214 215 216 217 218 219 220
        $callback($tokens);
        exit;
    }
    return $ok;
}

/**
 * Retrieves a valid token(s) for a particular context. Tokens are separated
 * by semicolons.
 */
221 222
function csrf_get_tokens()
{
Ad Schellevis's avatar
Ad Schellevis committed
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
    $has_cookies = !empty($_COOKIE);

    // $ip implements a composite key, which is sent if the user hasn't sent
    // any cookies. It may or may not be used, depending on whether or not
    // the cookies "stick"
    $secret = csrf_get_secret();
    if (!$has_cookies && $secret) {
        // :TODO: Harden this against proxy-spoofing attacks
        $ip = ';ip:' . csrf_hash($_SERVER['IP_ADDRESS']);
    } else {
        $ip = '';
    }
    csrf_start();

    // These are "strong" algorithms that don't require per se a secret
238 239 240
    if (session_id()) {
        return 'sid:' . csrf_hash(session_id()) . $ip;
    }
Ad Schellevis's avatar
Ad Schellevis committed
241 242 243 244 245
    if ($GLOBALS['csrf']['cookie']) {
        $val = csrf_generate_secret();
        setcookie($GLOBALS['csrf']['cookie'], $val);
        return 'cookie:' . csrf_hash($val) . $ip;
    }
246 247 248
    if ($GLOBALS['csrf']['key']) {
        return 'key:' . csrf_hash($GLOBALS['csrf']['key']) . $ip;
    }
Ad Schellevis's avatar
Ad Schellevis committed
249
    // These further algorithms require a server-side secret
250 251 252
    if (!$secret) {
        return 'invalid';
    }
Ad Schellevis's avatar
Ad Schellevis committed
253 254 255 256 257 258 259 260 261
    if ($GLOBALS['csrf']['user'] !== false) {
        return 'user:' . csrf_hash($GLOBALS['csrf']['user']);
    }
    if ($GLOBALS['csrf']['allow-ip']) {
        return ltrim($ip, ';');
    }
    return 'invalid';
}

262 263
function csrf_flattenpost($data)
{
Ad Schellevis's avatar
Ad Schellevis committed
264
    $ret = array();
265
    foreach ($data as $n => $v) {
Ad Schellevis's avatar
Ad Schellevis committed
266 267 268 269
        $ret = array_merge($ret, csrf_flattenpost2(1, $n, $v));
    }
    return $ret;
}
270 271 272 273 274
function csrf_flattenpost2($level, $key, $data)
{
    if (!is_array($data)) {
        return array($key => $data);
    }
Ad Schellevis's avatar
Ad Schellevis committed
275
    $ret = array();
276
    foreach ($data as $n => $v) {
Ad Schellevis's avatar
Ad Schellevis committed
277 278 279 280 281 282 283 284 285
        $nk = $level >= 1 ? $key."[$n]" : "[$n]";
        $ret = array_merge($ret, csrf_flattenpost2($level+1, $nk, $v));
    }
    return $ret;
}

/**
 * @param $tokens is safe for HTML consumption
 */
286 287
function csrf_callback($tokens)
{
Ad Schellevis's avatar
Ad Schellevis committed
288 289 290 291
    // (yes, $tokens is safe to echo without escaping)
    header($_SERVER['SERVER_PROTOCOL'] . ' 403 Forbidden');
    $data = '';
    foreach (csrf_flattenpost($_POST) as $key => $value) {
292 293 294
        if ($key == $GLOBALS['csrf']['input-name']) {
            continue;
        }
Ad Schellevis's avatar
Ad Schellevis committed
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309
        $data .= '<input type="hidden" name="'.htmlspecialchars($key).'" value="'.htmlspecialchars($value).'" />';
    }
    echo "<html><head><title>CSRF check failed</title></head>
        <body>
        <p>CSRF check failed. Your form session may have expired, or you may not have
        cookies enabled.</p>
        <form method='post' action=''>$data<input type='submit' value='Try again' /></form>
        <p>Debug: $tokens</p></body></html>
";
}

/**
 * Checks if a composite token is valid. Outward facing code should use this
 * instead of csrf_check_token()
 */
310 311 312 313 314
function csrf_check_tokens($tokens)
{
    if (is_string($tokens)) {
        $tokens = explode(';', $tokens);
    }
Ad Schellevis's avatar
Ad Schellevis committed
315
    foreach ($tokens as $token) {
316 317 318
        if (csrf_check_token($token)) {
            return true;
        }
Ad Schellevis's avatar
Ad Schellevis committed
319 320 321 322 323 324 325
    }
    return false;
}

/**
 * Checks if a token is valid.
 */
326 327 328 329 330
function csrf_check_token($token)
{
    if (strpos($token, ':') === false) {
        return false;
    }
Ad Schellevis's avatar
Ad Schellevis committed
331
    list($type, $value) = explode(':', $token, 2);
332 333 334
    if (strpos($value, ',') === false) {
        return false;
    }
Ad Schellevis's avatar
Ad Schellevis committed
335 336
    list($x, $time) = explode(',', $token, 2);
    if ($GLOBALS['csrf']['expires']) {
337 338 339
        if (time() > $time + $GLOBALS['csrf']['expires']) {
            return false;
        }
Ad Schellevis's avatar
Ad Schellevis committed
340 341 342 343 344 345
    }
    switch ($type) {
        case 'sid':
            return $value === csrf_hash(session_id(), $time);
        case 'cookie':
            $n = $GLOBALS['csrf']['cookie'];
346 347 348 349 350 351
            if (!$n) {
                return false;
            }
            if (!isset($_COOKIE[$n])) {
                return false;
            }
Ad Schellevis's avatar
Ad Schellevis committed
352 353
            return $value === csrf_hash($_COOKIE[$n], $time);
        case 'key':
354 355 356
            if (!$GLOBALS['csrf']['key']) {
                return false;
            }
Ad Schellevis's avatar
Ad Schellevis committed
357 358 359 360 361
            return $value === csrf_hash($GLOBALS['csrf']['key'], $time);
        // We could disable these 'weaker' checks if 'key' was set, but
        // that doesn't make me feel good then about the cookie-based
        // implementation.
        case 'user':
362 363 364 365 366 367
            if (!csrf_get_secret()) {
                return false;
            }
            if ($GLOBALS['csrf']['user'] === false) {
                return false;
            }
Ad Schellevis's avatar
Ad Schellevis committed
368 369
            return $value === csrf_hash($GLOBALS['csrf']['user'], $time);
        case 'ip':
370 371 372
            if (!csrf_get_secret()) {
                return false;
            }
Ad Schellevis's avatar
Ad Schellevis committed
373 374
            // do not allow IP-based checks if the username is set, or if
            // the browser sent cookies
375 376 377 378 379 380 381 382 383
            if ($GLOBALS['csrf']['user'] !== false) {
                return false;
            }
            if (!empty($_COOKIE)) {
                return false;
            }
            if (!$GLOBALS['csrf']['allow-ip']) {
                return false;
            }
Ad Schellevis's avatar
Ad Schellevis committed
384 385 386 387 388 389 390 391
            return $value === csrf_hash($_SERVER['IP_ADDRESS'], $time);
    }
    return false;
}

/**
 * Sets a configuration value.
 */
392 393
function csrf_conf($key, $val)
{
Ad Schellevis's avatar
Ad Schellevis committed
394 395 396 397 398 399 400 401 402 403
    if (!isset($GLOBALS['csrf'][$key])) {
        trigger_error('No such configuration ' . $key, E_USER_WARNING);
        return;
    }
    $GLOBALS['csrf'][$key] = $val;
}

/**
 * Starts a session if we're allowed to.
 */
404 405
function csrf_start()
{
406
    if ($GLOBALS['csrf']['auto-session'] && session_status() == PHP_SESSION_NONE) {
Ad Schellevis's avatar
Ad Schellevis committed
407 408 409 410 411 412 413
        session_start();
    }
}

/**
 * Retrieves the secret, and generates one if necessary.
 */
414 415 416 417 418
function csrf_get_secret()
{
    if ($GLOBALS['csrf']['secret']) {
        return $GLOBALS['csrf']['secret'];
    }
Ad Schellevis's avatar
Ad Schellevis committed
419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438
    $dir = dirname(__FILE__);
    $file = $dir . '/csrf-secret.php';
    $secret = '';
    if (file_exists($file)) {
        include $file;
        return $secret;
    }
    if (is_writable($dir)) {
        $secret = csrf_generate_secret();
        $fh = fopen($file, 'w');
        fwrite($fh, '<?php $secret = "'.$secret.'";' . PHP_EOL);
        fclose($fh);
        return $secret;
    }
    return '';
}

/**
 * Generates a random string as the hash of time, microtime, and mt_rand.
 */
439 440
function csrf_generate_secret($len = 32)
{
Ad Schellevis's avatar
Ad Schellevis committed
441 442 443 444 445 446 447 448 449 450 451 452
    $r = '';
    for ($i = 0; $i < 32; $i++) {
        $r .= chr(mt_rand(0, 255));
    }
    $r .= time() . microtime();
    return sha1($r);
}

/**
 * Generates a hash/expiry double. If time isn't set it will be calculated
 * from the current time.
 */
453 454 455 456 457
function csrf_hash($value, $time = null)
{
    if (!$time) {
        $time = time();
    }
Ad Schellevis's avatar
Ad Schellevis committed
458 459 460 461
    return sha1(csrf_get_secret() . $value . $time) . ',' . $time;
}

// Load user configuration
462 463 464
if (function_exists('csrf_startup')) {
    csrf_startup();
}
Ad Schellevis's avatar
Ad Schellevis committed
465
// Initialize our handler
466 467 468
if ($GLOBALS['csrf']['rewrite']) {
    ob_start('csrf_ob_handler');
}
Ad Schellevis's avatar
Ad Schellevis committed
469
// Perform check
470 471 472
if (!$GLOBALS['csrf']['defer']) {
    csrf_check();
}