birdgrinder: Update documentation.
| author |
Steve Losh <steve@stevelosh.com> |
| date |
Sun, 25 Jul 2010 02:28:38 -0400 |
| parents |
78f0cc982dec |
| children |
9ae2223d1010 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Welcome to flask-csrf’s documentation! — flask-csrf v0.9.1 documentation</title>
<link rel="stylesheet" href="_static/flasky.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.9.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="flask-csrf v0.9.1 documentation" href="#" />
</head>
<body>
<div class=indexwrapper>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="welcome-to-flask-csrf-s-documentation">
<h1>Welcome to flask-csrf’s documentation!<a class="headerlink" href="#welcome-to-flask-csrf-s-documentation" title="Permalink to this headline">¶</a></h1>
<p>The internet is a dangerous place. One common type of attack your site’s users
can fall victim to is <a class="reference external" href="http://www.squarefree.com/securitytips/web-developers.html#CSRF">Cross-Site Request Forgery</a> attacks.</p>
<p>flask-csrf is a small extension to Flask that makes adding CSRF protection to
your <a class="reference external" href="http://flask.pocoo.org/">Flask</a> application quick and easy. It’s based on <a class="reference external" href="http://flask.pocoo.org/snippets/3/">this snippet</a> from
the Flask snippet site.</p>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>Install flask-csrf with <a class="reference external" href="http://pip.openplans.org/">pip</a>:</p>
<div class="highlight-python"><pre>pip install -e 'hg+http://bitbucket.org/sjl/flask-csrf@v0.9.1#egg=flask-csrf'</pre>
</div>
<p>Prefer <a class="reference external" href="http://git-scm.com/">git</a> to <a class="reference external" href="http://hg-scm.org/">Mercurial</a>?</p>
<div class="highlight-python"><pre>pip install -e 'git+http://github.com/sjl/flask-csrf.git@v0.9.1#egg=flask-csrf'</pre>
</div>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>To activate CSRF protection for your Flask application you need to do two
things. First, call the <tt class="docutils literal"><span class="pre">csrf</span></tt> function with your Flask app as a parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flaskext.csrf</span> <span class="kn">import</span> <span class="n">csrf</span>
<span class="n">csrf</span><span class="p">(</span><span class="n">app</span><span class="p">)</span>
</pre></div>
</div>
<p>Once you do that you’ll need to add a CSRF token to every form on your site
that makes an HTTP <tt class="docutils literal"><span class="pre">POST</span></tt> request:</p>
<div class="highlight-python"><pre><input type="hidden" value="{{ csrf_token() }}"></pre>
</div>
<p>If you have certain views that need to be excluded from this protection
(perhaps they receive <tt class="docutils literal"><span class="pre">POST</span></tt> requests from a third-party site) you can use
the <tt class="docutils literal"><span class="pre">csrf_exempt</span></tt> decorator to disable protection:</p>
<div class="highlight-python"><pre>from flaskext.csrf import csrf, csrf_exempt
@csrf_exempt
@route('/foo/')
def my_receiving_view():
# ...
csrf(app)</pre>
</div>
<p>If for some reason you want to know <em>when</em> a CSRF attack happens, you can pass
a function to the <tt class="docutils literal"><span class="pre">csrf</span></tt> call and it will be called whenever an attack is
detected:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">flaskext.csrf</span> <span class="kn">import</span> <span class="n">csrf</span>
<span class="n">attacks</span> <span class="o">=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">count_csrf_attacks</span><span class="p">(</span><span class="n">endpoint</span><span class="p">,</span> <span class="n">arguments</span><span class="p">):</span>
<span class="n">attacks</span> <span class="o">+=</span> <span class="mi">1</span>
<span class="n">csrf</span><span class="p">(</span><span class="n">app</span><span class="p">,</span> <span class="n">on_csrf</span><span class="o">=</span><span class="n">count_csrf_attacks</span><span class="p">)</span>
</pre></div>
</div>
<p>This function must take two parameters:</p>
<ul class="simple">
<li><strong>endpoint</strong> - A string representing the view that would
normally handle this request.</li>
<li><strong>arguments</strong> - The arguments that would normally be passed (if
any) to that view.</li>
</ul>
<p>You can use this function to do anything you like; counting attacks is just
a simple example.</p>
</div>
<div class="section" id="contribute">
<h2>Contribute<a class="headerlink" href="#contribute" title="Permalink to this headline">¶</a></h2>
<p>flask-csrf is open source and MIT licensed. If you want to contribute feel
free to fork the <a class="reference external" href="http://bitbucket.org/sjl/flask-csrf/">Mercurial repository</a> or <a class="reference external" href="http://github.com/sjl/flask-csrf/">git repository</a> and send a pull
request.</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">Created by <a href="http://stevelosh.com/">Steve Losh</a></p>
</div>
</body>
</html>