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:
  90
  91     function csrf_startup() {
  92         csrf_conf('input-name', 'magic-token');
  93         csrf_conf('secret', 'ABCDEFG123456');
  94         csrf_conf('rewrite-js', '/csrf-magic.js');
  95     }
  96     include_once '/path/to/csrf-magic.php';
  97
  98 Configuration gets stored in the $GLOBALS['csrf'] array.
  99
 100
 101 4.  THANKS
 102
 103 My thanks to Chris Shiflett, for unintentionally inspiring the idea, as well
 104 as telling me the original variant of the Bob and Mallory story,
 105 and the Django CSRF Middleware authors, who thought up of this before me.
 106
 107 http://www.thespanner.co.uk/2007/08/20/protection-against-csrf/ is interesting
 108 esp the frame breaker which we can automatically write in.
 109
 110
 111 5.  FOOTNOTES
 112
 113 [1] There is an experimental attack in which a user makes an invisible iframe
 114     of the website being attacked and overlays this on-top of an element on
 115     their page that a user would normally click.  This iframe has a different
 116     button from the other website which activates the action.  Nonces will
 117     not protect against this type of attack, and csrf-magic doesn't deal with
 118     this type of attack.
 119
 120     See also:
 121         http://own-the.net/cat_CSRF-(XSRF)_news.html