README.txt

   1
   2 [[  csrf-magic  ]]
   3
   4 Add the following line to the top of all web-accessible PHP pages. If you have
   5 a common file included by everything, put it there.
   6
   7     include_once '/path/to/csrf-magic.php';
   8
   9 Do it, test it, then forget about it. csrf-magic is protecting you if nothing
  10 bad happens. Read on if you run into problems.
  11
  12
  13 1.  WHAT DOES IT DO?
  14
  15 CSRF, or cross-site request forgery, is a relatively new attack vector on
  16 websites today.  It involves an attacker tricking a browser into performing
  17 an action on another website.  For example, Bob is the human resources manager
  18 for a large and important company.  He has the ability to hire and fire with
  19 a click of a button... specifically, a web form button.  Mallory, as a practical
  20 joke, decides to setup a CSRF attack against Bob; she crafts a webpage which
  21 submits a form onto the internal website that performs hirings and firings; then
  22 she sends Bob an email to this webpage.  The next day, every employee wakes up
  23 to find a rather nasty pink slip in their inbox.
  24
  25 The current standard for preventing CSRF is creating a nonce that every user
  26 submits with any form he/she submits.  This is reasonably effective [1], but
  27 incredibly tedious work; if you were hand-writing your forms or have multiple
  28 avenues for POST data to enter your application, adding CSRF protection may not
  29 seem worth the trouble (trust me, it certainly is).
  30
  31 This is where csrf-magic comes into play.  csrf-magic uses PHP's output
  32 buffering capabilities to dynamically rewrite forms and scripts in your document.
  33 It will also intercept POST requests and check their token (various algorithms
  34 are used, some generate nonces, some generate user-specific tokens).  This means
  35 with a traditional website with forms, you can drop it into your application,
  36 and forget about it!
  37
  38
  39 2.  AJAX
  40
  41 csrf-magic has the ability to dynamically rewrite AJAX requests which use
  42 XMLHttpRequest.  However, due to the invasiveness of this procedure, it is
  43 not enabled by default.  You can enable it by adding this code before you
  44 include csrf-magic.php.
  45
  46     function csrf_startup() {
  47         csrf_conf('rewrite-js', '/web/path/to/csrf-magic.js');
  48     }
  49     // include_once '/path/to/csrf-magic.php';
  50
  51 (Be sure to place csrf-magic.js somewhere web accessible).  csrf-magic.js will
  52 automatically detect and play nice with the following JavaScript frameworks:
  53
  54     * jQuery
  55     * Prototype
  56     * script.aculo.us (via Prototype)
  57     * MooTools
  58     * Yahoo UI Library
  59     * Ext
  60     * Dojo
  61
  62 If you are not using any of these JavaScript libraries, AJAX requests will
  63 only work for browsers with support for XmlHttpRequest.prototype (this excludes
  64 all versions of Internet Explorer).
  65
  66 To rewrite your own JavaScript library to use csrf-magic.js, you should modify
  67 your function that generates XMLHttpRequest to have this at the end:
  68
  69     return new CsrfMagic(xhrObject);
  70
  71 With whatever xhrObject may be. If you have literal instances of XMLHttpRequest
  72 in your code, find and replace ''new XMLHttpRequest'' with ''new CsrfMagic''
  73 (CsrfMagic will automatically instantiate an XMLHttpRequest object in a
  74 cross-platform manner as necessary).
  75
  76 If you don't want csrf-magic monkeying around with your XMLHttpRequest object,
  77 you can manually rewrite your AJAX code to include the variable. The important
  78 information is stored in the global variables csrfMagicName and csrfMagicToken.
  79 CsrfMagic.process may also be of interest, as it takes one parameter, a
  80 querystring, and prepends the CSRF token to the value.
  81
  82
  83 3.  CONFIGURE
  84
  85 csrf-magic has some configuration options that you can set inside the
  86 csrf_startup() function. They are described in csrf-magic.php, and you can
  87 set them using the convenience function csrf_conf($name, $value).
  88
  89 For example, this is a recommended configuration:
  90
  91     /**
  92      * This is a function that gets called if a csrf check fails. csrf-magic will
  93      * then exit afterwards.
  94      */
  95     function my_csrf_callback() {
  96         echo "You're doing bad things young man!";
  97     }
  98
  99     function csrf_startup() {
 100
 101         // This is a secret value that must be set in order to enable username
 102         // and IP based checks. Don't show this to anyone.
 103         csrf_conf('secret', 'ABCDEFG123456');
 104
 105         // This enables JavaScript rewriting and will ensure your AJAX calls
 106         // don't stop working.
 107         csrf_conf('rewrite-js', '/csrf-magic.js');
 108
 109         // This makes csrf-magic call my_csrf_callback() before exiting when
 110         // there is a bad csrf token. This lets me customize the error page.
 111         csrf_conf('callback', 'my_csrf_callback');
 112
 113         // While this is enabled by default to boost backwards compatibility,
 114         // for security purposes it should ideally be off. Some users can be
 115         // NATted or have dialup addresses which rotate frequently. Cookies
 116         // are much more reliable.
 117         csrf_conf('allow-ip', false);
 118
 119     }
 120
 121     // Finally, include the library
 122     include_once '/path/to/csrf-magic.php';
 123
 124 Configuration gets stored in the $GLOBALS['csrf'] array.
 125
 126
 127 4.  THANKS
 128
 129 My thanks to Chris Shiflett, for unintentionally inspiring the idea, as well
 130 as telling me the original variant of the Bob and Mallory story,
 131 and the Django CSRF Middleware authors, who thought up of this before me.
 132
 133 http://www.thespanner.co.uk/2007/08/20/protection-against-csrf/ is interesting
 134 esp the frame breaker which we can automatically write in.
 135
 136
 137 5.  FOOTNOTES
 138
 139 [1] There is an experimental attack in which a user makes an invisible iframe
 140     of the website being attacked and overlays this on-top of an element on
 141     their page that a user would normally click.  This iframe has a different
 142     button from the other website which activates the action.  Nonces will
 143     not protect against this type of attack, and csrf-magic doesn't deal with
 144     this type of attack.
 145
 146     See also:
 147         http://own-the.net/cat_CSRF-(XSRF)_news.html
 148
 149
 150 6.   KNOWN BUGS
 151
 152 When an AJAX call is performed within an iframe, our rewriting of XMLHttpRequest
 153 my fail for the first page load.  Subsequent page loads will work properly.
 154
 155
 156 7.   TODO
 157
 158     * Minify csrf-magic.js for performance.
 159
 160     * Optional PHP5 exception support.
 161
 162     * Auto-generate secret.
 163
 164     * Make "first time" session more robust by double-submitting.
 165
 166     * Test manual JavaScript overloading instructions.
 167
 168     * Account for JavaScript generated-forms with some JavaScript that loads into
 169       some global onsubmit handler and checks form submissions accordingly.