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
  60 We are currently implementing support for these JavaScript libraries:
  61
  62 * Ext
  63 * Dojo
  64
  65 If you are not using any of these JavaScript libraries, AJAX requests will
  66 only work for browsers with support for XmlHttpRequest.prototype (this excludes
  67 all versions of Internet Explorer).
  68
  69 To rewrite your own JavaScript library to use csrf-magic.js, note that when
  70 JavaScript is enabled the csrfMagicName and csrfMagicToken global variables
  71 become available.  Simply add this to all POST AJAX requests as:
  72
  73     csrfMagicName + '=' + csrfMagicToken
  74
  75 You can see examples of these implementations in csrf-magic.js. Also, feel free
  76 to prune csrf-magic.js to the code you need (just be careful when updating!)
  77
  78
  79 3.  CONFIGURE
  80
  81 csrf-magic has some configuration options that you can set inside the
  82 csrf_startup() function. They are described in csrf-magic.php, and you can
  83 set them using the convenience function csrf_conf($name, $value).
  84
  85 For example:
  86
  87     function csrf_startup() {
  88         csrf_conf('input-name', 'magic-token');
  89         csrf_conf('secret', 'ABCDEFG123456');
  90         csrf_conf('rewrite-js', '/csrf-magic.js');
  91     }
  92     include_once '/path/to/csrf-magic.php';
  93
  94
  95 4.  THANKS
  96
  97 My thanks to Chris Shiflett, for unintentionally inspiring the idea, as well
  98 as telling me the original variant of the Bob and Mallory story,
  99 and the Django CSRF Middleware authors, who thought up of this before me.
 100
 101 http://www.thespanner.co.uk/2007/08/20/protection-against-csrf/ is interesting
 102 esp the frame breaker which we can automatically write in.
 103
 104
 105 5.  FOOTNOTES
 106
 107 [1] There is an experimental attack in which a user makes an invisible iframe
 108     of the website being attacked and overlays this on-top of an element on
 109     their page that a user would normally click.  This iframe has a different
 110     button from the other website which activates the action.  Nonces will
 111     not protect against this type of attack, and csrf-magic doesn't deal with
 112     this type of attack.
 113
 114     See also:
 115         http://own-the.net/cat_CSRF-(XSRF)_news.html