[Summary view] [Print] [Text view]

   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                               TABLE OF CONTENTS
  14                            + ------------------- +
  15                              1. TIPS AND TRICKS
  16                              2. AJAX
  17                              3. CONFIGURE
  18                              4. THANKS
  19                              5. FOOTNOTES
  20                            + ------------------- +
  21  
  22  
  23  1.  TIPS AND TRICKS
  24  
  25      * If your JavaScript and AJAX is persistently getting errors, check the
  26        AJAX section below on how to fix.
  27  
  28      * The CSS overlay protection makes it impossible to display your website
  29        in frame/iframe elements.  You can disable it with
  30        csrf_conf('frame-breaker', false) in your csrf_startup() function.
  31  
  32      * csrf-magic will start a session.  To disable, use csrf_conf('auto-session',
  33        false) in your csrf_startup() function.
  34  
  35      * The default error message is a little user unfriendly.  Write your own
  36        function which outputs an error message and set csrf_conf('callback',
  37        'myCallbackFunction') in your csrf_startup() function.
  38  
  39      * Make sure csrf_conf('secret', 'ABCDEFG') has something random in it.  If
  40        the directory csrf-magic.php is in is writable, csrf-magic will generate
  41        a secret key for you in the csrf-secret.php file.
  42  
  43      * Remember you can use auto_prepend to include csrf-magic.php on all your
  44        pages.  You may want to create a stub file which you can include that
  45        includes csrf-magic.php as well as performs configuration.
  46  
  47      * The default expiration time for tokens is two hours. If you expect your
  48        users to need longer to fill out forms, be sure to enable double
  49        submission when the token is invalid.
  50  
  51  
  52  2.  AJAX
  53  
  54  csrf-magic has the ability to dynamically rewrite AJAX requests which use
  55  XMLHttpRequest.  However, due to the invasiveness of this procedure, it is
  56  not enabled by default.  You can enable it by adding this code before you
  57  include csrf-magic.php.
  58  
  59      function csrf_startup() {
  60          csrf_conf('rewrite-js', '/web/path/to/csrf-magic.js');
  61      }
  62      // include_once '/path/to/csrf-magic.php';
  63  
  64  (Be sure to place csrf-magic.js somewhere web accessible).
  65  
  66  The default method CSRF Magic uses to rewrite AJAX requests will
  67  only work for browsers with support for XmlHttpRequest.prototype (this excludes
  68  all versions of Internet Explorer).  See this page for more information:
  69  http://stackoverflow.com/questions/664315/internet-explorer-8-prototypes-and-xmlhttprequest
  70  
  71  However, csrf-magic.js will
  72  automatically detect and play nice with the following JavaScript frameworks:
  73  
  74      * jQuery
  75      * Prototype
  76      * MooTools
  77      * Ext
  78      * Dojo
  79  
  80  (Note 2013-07-16: It has been a long time since this manual support has
  81  been updated, and some JavaScript libraries have placed their copies of XHR
  82  in local variables in closures, which makes it difficult for us to monkey-patch
  83  it in automatically.)
  84  
  85  To rewrite your own JavaScript library to use csrf-magic.js, you should modify
  86  your function that generates XMLHttpRequest to have this at the end:
  87  
  88      return new CsrfMagic(xhrObject);
  89  
  90  With whatever xhrObject may be. If you have literal instances of XMLHttpRequest
  91  in your code, find and replace ''new XMLHttpRequest'' with ''new CsrfMagic''
  92  (CsrfMagic will automatically instantiate an XMLHttpRequest object in a
  93  cross-platform manner as necessary).
  94  
  95  If you don't want csrf-magic monkeying around with your XMLHttpRequest object,
  96  you can manually rewrite your AJAX code to include the variable. The important
  97  information is stored in the global variables csrfMagicName and csrfMagicToken.
  98  CsrfMagic.process may also be of interest, as it takes one parameter, a
  99  querystring, and prepends the CSRF token to the value.
 100  
 101  
 102  3.  CONFIGURE
 103  
 104  csrf-magic has some configuration options that you can set inside the
 105  csrf_startup() function. They are described in csrf-magic.php, and you can
 106  set them using the convenience function csrf_conf($name, $value).
 107  
 108  For example, this is a recommended configuration:
 109  
 110      /**
 111       * This is a function that gets called if a csrf check fails. csrf-magic will
 112       * then exit afterwards.
 113       */
 114      function my_csrf_callback() {
 115          echo "You're doing bad things young man!";
 116      }
 117  
 118      function csrf_startup() {
 119  
 120          // While csrf-magic has a handy little heuristic for determining whether
 121          // or not the content in the buffer is HTML or not, you should really
 122          // give it a nudge and turn rewriting *off* when the content is
 123          // not HTML. Implementation details will vary.
 124          if (isset($_POST['ajax'])) csrf_conf('rewrite', false);
 125  
 126          // This is a secret value that must be set in order to enable username
 127          // and IP based checks. Don't show this to anyone. A secret id will
 128          // automatically be generated for you if the directory csrf-magic.php
 129          // is placed in is writable.
 130          csrf_conf('secret', 'ABCDEFG123456');
 131  
 132          // This enables JavaScript rewriting and will ensure your AJAX calls
 133          // don't stop working.
 134          csrf_conf('rewrite-js', '/csrf-magic.js');
 135  
 136          // This makes csrf-magic call my_csrf_callback() before exiting when
 137          // there is a bad csrf token. This lets me customize the error page.
 138          csrf_conf('callback', 'my_csrf_callback');
 139  
 140          // While this is enabled by default to boost backwards compatibility,
 141          // for security purposes it should ideally be off. Some users can be
 142          // NATted or have dialup addresses which rotate frequently. Cookies
 143          // are much more reliable.
 144          csrf_conf('allow-ip', false);
 145  
 146      }
 147  
 148      // Finally, include the library
 149      include_once '/path/to/csrf-magic.php';
 150  
 151  Configuration gets stored in the $GLOBALS['csrf'] array.
 152  
 153  
 154  4.  THANKS
 155  
 156  My thanks to Chris Shiflett, for unintentionally inspiring the idea, as well
 157  as telling me the original variant of the Bob and Mallory story,
 158  and the Django CSRF Middleware authors, who thought up of this before me.
 159  Gareth Heyes suggested using the frame-breaker option to protect against
 160  CSS overlay attacks.