<!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>Cryptographic signing — Django 1.6.7 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.6.7',
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="Django 1.6.7 documentation" href="../index.html" />
<link rel="up" title="Using Django" href="index.html" />
<link rel="next" title="Sending email" href="email.html" />
<link rel="prev" title="Conditional View Processing" href="conditional-view-processing.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.6.7 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="conditional-view-processing.html" title="Conditional View Processing">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="email.html" title="Sending email">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="topics-signing">
<div class="section" id="s-module-django.core.signing">
<span id="s-cryptographic-signing"></span><span id="module-django.core.signing"></span><span id="cryptographic-signing"></span><h1>Cryptographic signing<a class="headerlink" href="#module-django.core.signing" title="Permalink to this headline">¶</a></h1>
<p>The golden rule of Web application security is to never trust data from
untrusted sources. Sometimes it can be useful to pass data through an
untrusted medium. Cryptographically signed values can be passed through an
untrusted channel safe in the knowledge that any tampering will be detected.</p>
<p>Django provides both a low-level API for signing values and a high-level API
for setting and reading signed cookies, one of the most common uses of
signing in Web applications.</p>
<p>You may also find signing useful for the following:</p>
<ul class="simple">
<li>Generating “recover my account” URLs for sending to users who have
lost their password.</li>
<li>Ensuring data stored in hidden form fields has not been tampered with.</li>
<li>Generating one-time secret URLs for allowing temporary access to a
protected resource, for example a downloadable file that a user has
paid for.</li>
</ul>
<div class="section" id="s-protecting-the-secret-key">
<span id="protecting-the-secret-key"></span><h2>Protecting the SECRET_KEY<a class="headerlink" href="#protecting-the-secret-key" title="Permalink to this headline">¶</a></h2>
<p>When you create a new Django project using <a class="reference internal" href="../ref/django-admin.html#django-admin-startproject"><tt class="xref std std-djadmin docutils literal"><span class="pre">startproject</span></tt></a>, the
<tt class="docutils literal"><span class="pre">settings.py</span></tt> file is generated automatically and gets a random
<a class="reference internal" href="../ref/settings.html#std:setting-SECRET_KEY"><tt class="xref std std-setting docutils literal"><span class="pre">SECRET_KEY</span></tt></a> value. This value is the key to securing signed
data – it is vital you keep this secure, or attackers could use it to
generate their own signed values.</p>
</div>
<div class="section" id="s-using-the-low-level-api">
<span id="using-the-low-level-api"></span><h2>Using the low-level API<a class="headerlink" href="#using-the-low-level-api" title="Permalink to this headline">¶</a></h2>
<p>Django’s signing methods live in the <tt class="docutils literal"><span class="pre">django.core.signing</span></tt> module.
To sign a value, first instantiate a <tt class="docutils literal"><span class="pre">Signer</span></tt> instance:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core.signing</span> <span class="kn">import</span> <span class="n">Signer</span>
<span class="gp">>>> </span><span class="n">signer</span> <span class="o">=</span> <span class="n">Signer</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">value</span> <span class="o">=</span> <span class="n">signer</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s">'My string'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">value</span>
<span class="go">'My string:GdMGD6HNQ_qdgxYP8yBZAdAIV1w'</span>
</pre></div>
</div>
<p>The signature is appended to the end of the string, following the colon.
You can retrieve the original value using the <tt class="docutils literal"><span class="pre">unsign</span></tt> method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">original</span> <span class="o">=</span> <span class="n">signer</span><span class="o">.</span><span class="n">unsign</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">original</span>
<span class="go">u'My string'</span>
</pre></div>
</div>
<p>If the signature or value have been altered in any way, a
<tt class="docutils literal"><span class="pre">django.core.signing.BadSignature</span></tt> exception will be raised:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core</span> <span class="kn">import</span> <span class="n">signing</span>
<span class="gp">>>> </span><span class="n">value</span> <span class="o">+=</span> <span class="s">'m'</span>
<span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">original</span> <span class="o">=</span> <span class="n">signer</span><span class="o">.</span><span class="n">unsign</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<span class="gp">... </span><span class="k">except</span> <span class="n">signing</span><span class="o">.</span><span class="n">BadSignature</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"Tampering detected!"</span><span class="p">)</span>
</pre></div>
</div>
<p>By default, the <tt class="docutils literal"><span class="pre">Signer</span></tt> class uses the <a class="reference internal" href="../ref/settings.html#std:setting-SECRET_KEY"><tt class="xref std std-setting docutils literal"><span class="pre">SECRET_KEY</span></tt></a> setting to
generate signatures. You can use a different secret by passing it to the
<tt class="docutils literal"><span class="pre">Signer</span></tt> constructor:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">signer</span> <span class="o">=</span> <span class="n">Signer</span><span class="p">(</span><span class="s">'my-other-secret'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">value</span> <span class="o">=</span> <span class="n">signer</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s">'My string'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">value</span>
<span class="go">'My string:EkfQJafvGyiofrdGnuthdxImIJw'</span>
</pre></div>
</div>
<dl class="class">
<dt id="django.core.signing.Signer">
<em class="property">class </em><tt class="descname">Signer</tt>(<em>key=None</em>, <em>sep=':'</em>, <em>salt=None</em>)<a class="reference internal" href="../_modules/django/core/signing.html#Signer"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.signing.Signer" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a signer which uses <tt class="docutils literal"><span class="pre">key</span></tt> to generate signatures and <tt class="docutils literal"><span class="pre">sep</span></tt> to
separate values. <tt class="docutils literal"><span class="pre">sep</span></tt> cannot be in the <a class="reference external" href="http://tools.ietf.org/html/rfc4648#section-5">URL safe base64 alphabet</a>. This alphabet contains
alphanumeric characters, hyphens, and underscores.</p>
</dd></dl>
<div class="section" id="s-using-the-salt-argument">
<span id="using-the-salt-argument"></span><h3>Using the salt argument<a class="headerlink" href="#using-the-salt-argument" title="Permalink to this headline">¶</a></h3>
<p>If you do not wish for every occurrence of a particular string to have the same
signature hash, you can use the optional <tt class="docutils literal"><span class="pre">salt</span></tt> argument to the <tt class="docutils literal"><span class="pre">Signer</span></tt>
class. Using a salt will seed the signing hash function with both the salt and
your <a class="reference internal" href="../ref/settings.html#std:setting-SECRET_KEY"><tt class="xref std std-setting docutils literal"><span class="pre">SECRET_KEY</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">signer</span> <span class="o">=</span> <span class="n">Signer</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">signer</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s">'My string'</span><span class="p">)</span>
<span class="go">'My string:GdMGD6HNQ_qdgxYP8yBZAdAIV1w'</span>
<span class="gp">>>> </span><span class="n">signer</span> <span class="o">=</span> <span class="n">Signer</span><span class="p">(</span><span class="n">salt</span><span class="o">=</span><span class="s">'extra'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">signer</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s">'My string'</span><span class="p">)</span>
<span class="go">'My string:Ee7vGi-ING6n02gkcJ-QLHg6vFw'</span>
<span class="gp">>>> </span><span class="n">signer</span><span class="o">.</span><span class="n">unsign</span><span class="p">(</span><span class="s">'My string:Ee7vGi-ING6n02gkcJ-QLHg6vFw'</span><span class="p">)</span>
<span class="go">u'My string'</span>
</pre></div>
</div>
<p>Using salt in this way puts the different signatures into different
namespaces. A signature that comes from one namespace (a particular salt
value) cannot be used to validate the same plaintext string in a different
namespace that is using a different salt setting. The result is to prevent an
attacker from using a signed string generated in one place in the code as input
to another piece of code that is generating (and verifying) signatures using a
different salt.</p>
<p>Unlike your <a class="reference internal" href="../ref/settings.html#std:setting-SECRET_KEY"><tt class="xref std std-setting docutils literal"><span class="pre">SECRET_KEY</span></tt></a>, your salt argument does not need to stay
secret.</p>
</div>
<div class="section" id="s-verifying-timestamped-values">
<span id="verifying-timestamped-values"></span><h3>Verifying timestamped values<a class="headerlink" href="#verifying-timestamped-values" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">TimestampSigner</span></tt> is a subclass of <a class="reference internal" href="#django.core.signing.Signer" title="django.core.signing.Signer"><tt class="xref py py-class docutils literal"><span class="pre">Signer</span></tt></a> that appends a signed
timestamp to the value. This allows you to confirm that a signed value was
created within a specified period of time:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core.signing</span> <span class="kn">import</span> <span class="n">TimestampSigner</span>
<span class="gp">>>> </span><span class="n">signer</span> <span class="o">=</span> <span class="n">TimestampSigner</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">value</span> <span class="o">=</span> <span class="n">signer</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s">'hello'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">value</span>
<span class="go">'hello:1NMg5H:oPVuCqlJWmChm1rA2lyTUtelC-c'</span>
<span class="gp">>>> </span><span class="n">signer</span><span class="o">.</span><span class="n">unsign</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<span class="go">u'hello'</span>
<span class="gp">>>> </span><span class="n">signer</span><span class="o">.</span><span class="n">unsign</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">max_age</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">SignatureExpired: Signature age 15.5289158821 > 10 seconds</span>
<span class="gp">>>> </span><span class="n">signer</span><span class="o">.</span><span class="n">unsign</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">max_age</span><span class="o">=</span><span class="mi">20</span><span class="p">)</span>
<span class="go">u'hello'</span>
</pre></div>
</div>
<dl class="class">
<dt id="django.core.signing.TimestampSigner">
<em class="property">class </em><tt class="descname">TimestampSigner</tt>(<em>key=None</em>, <em>sep=':'</em>, <em>salt=None</em>)<a class="reference internal" href="../_modules/django/core/signing.html#TimestampSigner"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.signing.TimestampSigner" title="Permalink to this definition">¶</a></dt>
<dd><dl class="method">
<dt id="django.core.signing.TimestampSigner.sign">
<tt class="descname">sign</tt>(<em>value</em>)<a class="reference internal" href="../_modules/django/core/signing.html#TimestampSigner.sign"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.signing.TimestampSigner.sign" title="Permalink to this definition">¶</a></dt>
<dd><p>Sign <tt class="docutils literal"><span class="pre">value</span></tt> and append current timestamp to it.</p>
</dd></dl>
<dl class="method">
<dt id="django.core.signing.TimestampSigner.unsign">
<tt class="descname">unsign</tt>(<em>value</em>, <em>max_age=None</em>)<a class="reference internal" href="../_modules/django/core/signing.html#TimestampSigner.unsign"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.signing.TimestampSigner.unsign" title="Permalink to this definition">¶</a></dt>
<dd><p>Checks if <tt class="docutils literal"><span class="pre">value</span></tt> was signed less than <tt class="docutils literal"><span class="pre">max_age</span></tt> seconds ago,
otherwise raises <tt class="docutils literal"><span class="pre">SignatureExpired</span></tt>.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="s-protecting-complex-data-structures">
<span id="protecting-complex-data-structures"></span><h3>Protecting complex data structures<a class="headerlink" href="#protecting-complex-data-structures" title="Permalink to this headline">¶</a></h3>
<p>If you wish to protect a list, tuple or dictionary you can do so using the
signing module’s <tt class="docutils literal"><span class="pre">dumps</span></tt> and <tt class="docutils literal"><span class="pre">loads</span></tt> functions. These imitate Python’s
pickle module, but use JSON serialization under the hood. JSON ensures that
even if your <a class="reference internal" href="../ref/settings.html#std:setting-SECRET_KEY"><tt class="xref std std-setting docutils literal"><span class="pre">SECRET_KEY</span></tt></a> is stolen an attacker will not be able
to execute arbitrary commands by exploiting the pickle format.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core</span> <span class="kn">import</span> <span class="n">signing</span>
<span class="gp">>>> </span><span class="n">value</span> <span class="o">=</span> <span class="n">signing</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span><span class="s">"foo"</span><span class="p">:</span> <span class="s">"bar"</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">value</span>
<span class="go">'eyJmb28iOiJiYXIifQ:1NMg1b:zGcDE4-TCkaeGzLeW9UQwZesciI'</span>
<span class="gp">>>> </span><span class="n">signing</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<span class="go">{'foo': 'bar'}</span>
</pre></div>
</div>
<dl class="function">
<dt id="django.core.signing.dumps">
<tt class="descname">dumps</tt>(<em>obj</em>, <em>key=None</em>, <em>salt='django.core.signing'</em>, <em>compress=False</em>)<a class="reference internal" href="../_modules/django/core/signing.html#dumps"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.signing.dumps" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns URL-safe, sha1 signed base64 compressed JSON string. Serialized
object is signed using <a class="reference internal" href="#django.core.signing.TimestampSigner" title="django.core.signing.TimestampSigner"><tt class="xref py py-class docutils literal"><span class="pre">TimestampSigner</span></tt></a>.</p>
</dd></dl>
<dl class="function">
<dt id="django.core.signing.loads">
<tt class="descname">loads</tt>(<em>string</em>, <em>key=None</em>, <em>salt='django.core.signing'</em>, <em>max_age=None</em>)<a class="reference internal" href="../_modules/django/core/signing.html#loads"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.core.signing.loads" title="Permalink to this definition">¶</a></dt>
<dd><p>Reverse of <tt class="docutils literal"><span class="pre">dumps()</span></tt>, raises <tt class="docutils literal"><span class="pre">BadSignature</span></tt> if signature fails.
Checks <tt class="docutils literal"><span class="pre">max_age</span></tt> (in seconds) if given.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Cryptographic signing</a><ul>
<li><a class="reference internal" href="#protecting-the-secret-key">Protecting the SECRET_KEY</a></li>
<li><a class="reference internal" href="#using-the-low-level-api">Using the low-level API</a><ul>
<li><a class="reference internal" href="#using-the-salt-argument">Using the salt argument</a></li>
<li><a class="reference internal" href="#verifying-timestamped-values">Verifying timestamped values</a></li>
<li><a class="reference internal" href="#protecting-complex-data-structures">Protecting complex data structures</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="conditional-view-processing.html">Conditional View Processing</a></li>
<li>Next: <a href="email.html">Sending email</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django 1.6.7 documentation</a>
<ul><li><a href="index.html">Using Django</a>
<ul><li>Cryptographic signing</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/topics/signing.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Sep 26, 2014</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="conditional-view-processing.html" title="Conditional View Processing">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="email.html" title="Sending email">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
