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
  14 1.  AJAX
  15
  16 csrf-magic has the ability to dynamically rewrite AJAX requests which use
  17 XMLHttpRequest.  However, due to the invasiveness of this procedure, it is
  18 not enabled by default.  You can enable it by adding this code before you
  19 include csrf-magic.php.
  20
  21     function csrf_startup() {
  22         csrf_conf('rewrite-js', '/web/path/to/csrf-magic.js');
  23     }
  24     // include_once '/path/to/csrf-magic.php';
  25
  26 (Be sure to place csrf-magic.js somewhere web accessible).  csrf-magic.js will
  27 automatically detect and play nice with the following JavaScript frameworks:
  28
  29     * jQuery
  30     * Prototype
  31     * script.aculo.us (via Prototype)
  32     * MooTools
  33     * Yahoo UI Library
  34     * Ext
  35     * Dojo
  36
  37 If you are not using any of these JavaScript libraries, AJAX requests will
  38 only work for browsers with support for XmlHttpRequest.prototype (this excludes
  39 all versions of Internet Explorer).
  40
  41 To rewrite your own JavaScript library to use csrf-magic.js, you should modify
  42 your function that generates XMLHttpRequest to have this at the end:
  43
  44     return new CsrfMagic(xhrObject);
  45
  46 With whatever xhrObject may be. If you have literal instances of XMLHttpRequest
  47 in your code, find and replace ''new XMLHttpRequest'' with ''new CsrfMagic''
  48 (CsrfMagic will automatically instantiate an XMLHttpRequest object in a
  49 cross-platform manner as necessary).
  50
  51 If you don't want csrf-magic monkeying around with your XMLHttpRequest object,
  52 you can manually rewrite your AJAX code to include the variable. The important
  53 information is stored in the global variables csrfMagicName and csrfMagicToken.
  54 CsrfMagic.process may also be of interest, as it takes one parameter, a
  55 querystring, and prepends the CSRF token to the value.
  56
  57
  58 2.  CONFIGURE
  59
  60 csrf-magic has some configuration options that you can set inside the
  61 csrf_startup() function. They are described in csrf-magic.php, and you can
  62 set them using the convenience function csrf_conf($name, $value).
  63
  64 For example, this is a recommended configuration:
  65
  66     /**
  67      * This is a function that gets called if a csrf check fails. csrf-magic will
  68      * then exit afterwards.
  69      */
  70     function my_csrf_callback() {
  71         echo "You're doing bad things young man!";
  72     }
  73
  74     function csrf_startup() {
  75
  76         // While csrf-magic has a handy little heuristic for determining whether
  77         // or not the content in the buffer is HTML or not, you should really
  78         // give it a nudge and turn rewriting *off* when the content is
  79         // not HTML. Implementation details will vary.
  80         if (isset($_POST['ajax'])) csrf_conf('rewrite', false);
  81
  82         // This is a secret value that must be set in order to enable username
  83         // and IP based checks. Don't show this to anyone. A secret id will
  84         // automatically be generated for you if the directory csrf-magic.php
  85         // is placed in is writable.
  86         csrf_conf('secret', 'ABCDEFG123456');
  87
  88         // This enables JavaScript rewriting and will ensure your AJAX calls
  89         // don't stop working.
  90         csrf_conf('rewrite-js', '/csrf-magic.js');
  91
  92         // This makes csrf-magic call my_csrf_callback() before exiting when
  93         // there is a bad csrf token. This lets me customize the error page.
  94         csrf_conf('callback', 'my_csrf_callback');
  95
  96         // While this is enabled by default to boost backwards compatibility,
  97         // for security purposes it should ideally be off. Some users can be
  98         // NATted or have dialup addresses which rotate frequently. Cookies
  99         // are much more reliable.
 100         csrf_conf('allow-ip', false);
 101
 102     }
 103
 104     // Finally, include the library
 105     include_once '/path/to/csrf-magic.php';
 106
 107 Configuration gets stored in the $GLOBALS['csrf'] array.
 108
 109
 110 3.  THANKS
 111
 112 My thanks to Chris Shiflett, for unintentionally inspiring the idea, as well
 113 as telling me the original variant of the Bob and Mallory story,
 114 and the Django CSRF Middleware authors, who thought up of this before me.
 115
 116 http://www.thespanner.co.uk/2007/08/20/protection-against-csrf/ is interesting
 117 esp the frame breaker which we can automatically write in.
 118
 119
 120 4.  FOOTNOTES
 121
 122 [1] There is an experimental attack in which a user makes an invisible iframe
 123     of the website being attacked and overlays this on-top of an element on
 124     their page that a user would normally click.  This iframe has a different
 125     button from the other website which activates the action.  Nonces will
 126     not protect against this type of attack, and csrf-magic doesn't deal with
 127     this type of attack.
 128
 129     See also:
 130         http://own-the.net/cat_CSRF-(XSRF)_news.html