hg-review: Update documentation.
author |
Steve Losh <steve@stevelosh.com> |
date |
Tue, 13 Jul 2010 01:30:44 -0400 |
parents |
388fd65c29fc |
children |
(none) |
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"
"http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:foaf="http://xmlns.com/foaf/0.1/">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<title>
Garter ยป
Csrf
</title>
<!-- YUI CSS reset, fonts, base -->
<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/combo?3.0.0/build/cssreset/reset-min.css&3.0.0/build/cssfonts/fonts-min.css&3.0.0/build/cssbase/base-min.css" media="screen, projection" />
<link rel="stylesheet" type="text/css" href="media/css/style.css" media="screen, projection" />
<link rel="stylesheet" type="text/css" href="media/css/pygments.css" media="screen, projection" />
<link rel="stylesheet" type="text/css" href="media/css/garter.css" media="screen, projection" />
</head>
<body >
<ol id="breadcrumbs">
<li class="crumb-0 not-last">
<a href="./">index</a>
</li>
<li class="crumb-1 last">
csrf
</li>
</ol> <!-- ol#breadcrumbs -->
<div id="content">
<h1><a href="">CSRF Protection</a></h1>
<p>The internet is a dangerous place. One common type of attack your site's users
can fall victim to is <a href="http://www.squarefree.com/securitytips/web-developers.html#CSRF">Cross-site Request Forgery</a> attacks.</p>
<p>Garter provides a simple way to guard against these attacks, based on <a href="http://flask.pocoo.org/snippets/3/">this
snippet</a> from the Flask snippet site.</p>
<p>To activate CSRF protection for your Flask application you need to do two
things. First, call Garter's <code>csrf</code> function with your Flask app as a
parameter:</p>
<div class="codehilite"><pre><span class="kn">from</span> <span class="nn">garter.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>
<p>Once you do that you'll need to add a CSRF token to every form on your site
that makes an HTTP <code>POST</code> request:</p>
<div class="codehilite"><pre><span class="nt"><input</span> <span class="na">type=</span><span class="s">"hidden"</span> <span class="na">value=</span><span class="s">"{{ csrf_token() }}"</span><span class="nt">></span>
</pre></div>
<p>If you have certain views that need to be excluded from this protection
(perhaps they receive <code>POST</code> requests from a third-party site) you can use the
<code>csrf_exempt</code> decorator to disable protection:</p>
<div class="codehilite"><pre><span class="kn">from</span> <span class="nn">garter.csrf</span> <span class="kn">import</span> <span class="n">csrf</span><span class="p">,</span> <span class="n">csrf_exempt</span>
<span class="nd">@csrf_exempt</span>
<span class="nd">@route</span><span class="p">(</span><span class="s">'/foo/'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">my_receiving_view</span><span class="p">():</span>
<span class="c"># ...</span>
<span class="n">csrf</span><span class="p">(</span><span class="n">app</span><span class="p">)</span>
</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 <code>csrf</code> call and it will be called whenever Garter detects an
attack:</p>
<div class="codehilite"><pre><span class="kn">from</span> <span class="nn">garter.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>
<p>This function must take two parameters:</p>
<ul>
<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>
<hr class="clear" />
</div>
<div id="footer">
<p>
<a href="http://sjl.bitbucket.org/garter/">Garter</a>
was lovingly crafted by
<a href="http://stevelosh.com/">Steve Losh</a>.
The documentation is powered by
<a href="http://markdoc.org/">Markdoc</a>.
</p>
</div>
<hr class="clear" />
</body>
</html>