<!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" lang="">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Cryptographic signing — Django 1.11.20 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" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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>
<script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.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.11.20 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 <code class="docutils literal notranslate"><span class="pre">SECRET_KEY</span></code><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"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">startproject</span></code></a>, the
<code class="docutils literal notranslate"><span class="pre">settings.py</span></code> file is generated automatically and gets a random
<a class="reference internal" href="../ref/settings.html#std:setting-SECRET_KEY"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SECRET_KEY</span></code></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 <code class="docutils literal notranslate"><span class="pre">django.core.signing</span></code> module.
To sign a value, first instantiate a <code class="docutils literal notranslate"><span class="pre">Signer</span></code> instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core.signing</span> <span class="k">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="s1">'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 <code class="docutils literal notranslate"><span class="pre">unsign</span></code> method:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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="n">original</span>
<span class="go">'My string'</span>
</pre></div>
</div>
<p>If the signature or value have been altered in any way, a
<code class="docutils literal notranslate"><span class="pre">django.core.signing.BadSignature</span></code> exception will be raised:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core</span> <span class="k">import</span> <span class="n">signing</span>
<span class="gp">>>> </span><span class="n">value</span> <span class="o">+=</span> <span class="s1">'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="nb">print</span><span class="p">(</span><span class="s2">"Tampering detected!"</span><span class="p">)</span>
</pre></div>
</div>
<p>By default, the <code class="docutils literal notranslate"><span class="pre">Signer</span></code> class uses the <a class="reference internal" href="../ref/settings.html#std:setting-SECRET_KEY"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SECRET_KEY</span></code></a> setting to
generate signatures. You can use a different secret by passing it to the
<code class="docutils literal notranslate"><span class="pre">Signer</span></code> constructor:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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="s1">'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="s1">'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><code class="descname">Signer</code>(<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 <code class="docutils literal notranslate"><span class="pre">key</span></code> to generate signatures and <code class="docutils literal notranslate"><span class="pre">sep</span></code> to
separate values. <code class="docutils literal notranslate"><span class="pre">sep</span></code> cannot be in the <a class="reference external" href="https://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 <code class="docutils literal notranslate"><span class="pre">salt</span></code> 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 <code class="docutils literal notranslate"><span class="pre">salt</span></code> argument to the <code class="docutils literal notranslate"><span class="pre">Signer</span></code>
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"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SECRET_KEY</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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">signer</span><span class="o">.</span><span class="n">sign</span><span class="p">(</span><span class="s1">'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="s1">'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="s1">'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="s1">'My string:Ee7vGi-ING6n02gkcJ-QLHg6vFw'</span><span class="p">)</span>
<span class="go">'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"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SECRET_KEY</span></code></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><code class="docutils literal notranslate"><span class="pre">TimestampSigner</span></code> is a subclass of <a class="reference internal" href="#django.core.signing.Signer" title="django.core.signing.Signer"><code class="xref py py-class docutils literal notranslate"><span class="pre">Signer</span></code></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-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">datetime</span> <span class="k">import</span> <span class="n">timedelta</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core.signing</span> <span class="k">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="s1">'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">'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">'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="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="mi">20</span><span class="p">))</span>
<span class="go">'hello'</span>
</pre></div>
</div>
<dl class="class">
<dt id="django.core.signing.TimestampSigner">
<em class="property">class </em><code class="descname">TimestampSigner</code>(<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">
<code class="descname">sign</code>(<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 <code class="docutils literal notranslate"><span class="pre">value</span></code> and append current timestamp to it.</p>
</dd></dl>
<dl class="method">
<dt id="django.core.signing.TimestampSigner.unsign">
<code class="descname">unsign</code>(<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 <code class="docutils literal notranslate"><span class="pre">value</span></code> was signed less than <code class="docutils literal notranslate"><span class="pre">max_age</span></code> seconds ago,
otherwise raises <code class="docutils literal notranslate"><span class="pre">SignatureExpired</span></code>. The <code class="docutils literal notranslate"><span class="pre">max_age</span></code> parameter can
accept an integer or a <code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.timedelta</span></code> object.</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 <code class="docutils literal notranslate"><span class="pre">dumps</span></code> and <code class="docutils literal notranslate"><span class="pre">loads</span></code> 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"><code class="xref std std-setting docutils literal notranslate"><span class="pre">SECRET_KEY</span></code></a> is stolen an attacker will not be able
to execute arbitrary commands by exploiting the pickle format:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core</span> <span class="k">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="s2">"foo"</span><span class="p">:</span> <span class="s2">"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>
<p>Because of the nature of JSON (there is no native distinction between lists
and tuples) if you pass in a tuple, you will get a list from
<code class="docutils literal notranslate"><span class="pre">signing.loads(object)</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.core</span> <span class="k">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="s1">'a'</span><span class="p">,</span><span class="s1">'b'</span><span class="p">,</span><span class="s1">'c'</span><span class="p">))</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">['a', 'b', 'c']</span>
</pre></div>
</div>
<dl class="function">
<dt id="django.core.signing.dumps">
<code class="descname">dumps</code>(<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"><code class="xref py py-class docutils literal notranslate"><span class="pre">TimestampSigner</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="django.core.signing.loads">
<code class="descname">loads</code>(<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 <code class="docutils literal notranslate"><span class="pre">dumps()</span></code>, raises <code class="docutils literal notranslate"><span class="pre">BadSignature</span></code> if signature fails.
Checks <code class="docutils literal notranslate"><span class="pre">max_age</span></code> (in seconds) if given.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<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 <code class="docutils literal notranslate"><span class="pre">SECRET_KEY</span></code></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 <code class="docutils literal notranslate"><span class="pre">salt</span></code> 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>
<h4>Previous topic</h4>
<p class="topless"><a href="conditional-view-processing.html"
title="previous chapter">Conditional View Processing</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="email.html"
title="next chapter">Sending email</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/topics/signing.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<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>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 11, 2019</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>
