Fix broken secret-detection algorithm, making anonymous users vulnerable.
[csrf-magic.git] / README.txt
blob327bc5d2c4141ecbe011c8b931c3d8c1849ea279
2                             [[  csrf-magic  ]]
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.
7     include_once '/path/to/csrf-magic.php';
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.
13                              TABLE OF CONTENTS
14                           + ------------------- +
15                             1. TIPS AND TRICKS
16                             2. AJAX
17                             3. CONFIGURE
18                             4. THANKS
19                             5. FOOTNOTES
20                           + ------------------- +
23 1.  TIPS AND TRICKS
25     * If your JavaScript and AJAX is persistently getting errors, check the
26       AJAX section below on how to fix.
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.
32     * csrf-magic will start a session.  To disable, use csrf_conf('auto-session',
33       false) in your csrf_startup() function.
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.
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.
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.
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.
52 2.  AJAX
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.
59     function csrf_startup() {
60         csrf_conf('rewrite-js', '/web/path/to/csrf-magic.js');
61     }
62     // include_once '/path/to/csrf-magic.php';
64 (Be sure to place csrf-magic.js somewhere web accessible).  csrf-magic.js will
65 automatically detect and play nice with the following JavaScript frameworks:
67     * jQuery
68     * Prototype
69     * script.aculo.us (via Prototype)
70     * MooTools
71     * Yahoo UI Library
72     * Ext
73     * Dojo
75 If you are not using any of these JavaScript libraries, AJAX requests will
76 only work for browsers with support for XmlHttpRequest.prototype (this excludes
77 all versions of Internet Explorer).
79 To rewrite your own JavaScript library to use csrf-magic.js, you should modify
80 your function that generates XMLHttpRequest to have this at the end:
82     return new CsrfMagic(xhrObject);
84 With whatever xhrObject may be. If you have literal instances of XMLHttpRequest
85 in your code, find and replace ''new XMLHttpRequest'' with ''new CsrfMagic''
86 (CsrfMagic will automatically instantiate an XMLHttpRequest object in a
87 cross-platform manner as necessary).
89 If you don't want csrf-magic monkeying around with your XMLHttpRequest object,
90 you can manually rewrite your AJAX code to include the variable. The important
91 information is stored in the global variables csrfMagicName and csrfMagicToken.
92 CsrfMagic.process may also be of interest, as it takes one parameter, a
93 querystring, and prepends the CSRF token to the value.
96 3.  CONFIGURE
98 csrf-magic has some configuration options that you can set inside the
99 csrf_startup() function. They are described in csrf-magic.php, and you can
100 set them using the convenience function csrf_conf($name, $value).
102 For example, this is a recommended configuration:
104     /**
105      * This is a function that gets called if a csrf check fails. csrf-magic will
106      * then exit afterwards.
107      */
108     function my_csrf_callback() {
109         echo "You're doing bad things young man!";
110     }
112     function csrf_startup() {
114         // While csrf-magic has a handy little heuristic for determining whether
115         // or not the content in the buffer is HTML or not, you should really
116         // give it a nudge and turn rewriting *off* when the content is
117         // not HTML. Implementation details will vary.
118         if (isset($_POST['ajax'])) csrf_conf('rewrite', false);
120         // This is a secret value that must be set in order to enable username
121         // and IP based checks. Don't show this to anyone. A secret id will
122         // automatically be generated for you if the directory csrf-magic.php
123         // is placed in is writable.
124         csrf_conf('secret', 'ABCDEFG123456');
126         // This enables JavaScript rewriting and will ensure your AJAX calls
127         // don't stop working.
128         csrf_conf('rewrite-js', '/csrf-magic.js');
130         // This makes csrf-magic call my_csrf_callback() before exiting when
131         // there is a bad csrf token. This lets me customize the error page.
132         csrf_conf('callback', 'my_csrf_callback');
134         // While this is enabled by default to boost backwards compatibility,
135         // for security purposes it should ideally be off. Some users can be
136         // NATted or have dialup addresses which rotate frequently. Cookies
137         // are much more reliable.
138         csrf_conf('allow-ip', false);
140     }
142     // Finally, include the library
143     include_once '/path/to/csrf-magic.php';
145 Configuration gets stored in the $GLOBALS['csrf'] array.
148 4.  THANKS
150 My thanks to Chris Shiflett, for unintentionally inspiring the idea, as well
151 as telling me the original variant of the Bob and Mallory story,
152 and the Django CSRF Middleware authors, who thought up of this before me.
153 Gareth Heyes suggested using the frame-breaker option to protect against
154 CSS overlay attacks.