<!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="Content-Type" content="text/html; charset=utf-8" />
<title>Cryptographic signing — Django 1.8.19 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.8.19',
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="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="top" title="Django 1.8.19 documentation" href="../contents.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 role="document">
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.8.19 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"><code class="xref std std-djadmin docutils literal"><span class="pre">startproject</span></code></a>, the
<code class="docutils literal"><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"><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"><span class="pre">django.core.signing</span></code> module.
To sign a value, first instantiate a <code class="docutils literal"><span class="pre">Signer</span></code> instance:</p>
<div class="highlight-default"><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"><span class="pre">unsign</span></code> method:</p>
<div class="highlight-default"><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"><span class="pre">django.core.signing.BadSignature</span></code> exception will be raised:</p>
<div class="highlight-default"><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"><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"><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"><span class="pre">Signer</span></code> constructor:</p>
<div class="highlight-default"><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"><span class="pre">key</span></code> to generate signatures and <code class="docutils literal"><span class="pre">sep</span></code> to
separate values. <code class="docutils literal"><span class="pre">sep</span></code> 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 <code class="docutils literal"><span class="pre">salt</span></code> argument to the <code class="docutils literal"><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"><span class="pre">SECRET_KEY</span></code></a>:</p>
<div class="highlight-default"><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"><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"><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"><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"><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"><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"><span class="pre">value</span></code> was signed less than <code class="docutils literal"><span class="pre">max_age</span></code> seconds ago,
otherwise raises <code class="docutils literal"><span class="pre">SignatureExpired</span></code>. The <code class="docutils literal"><span class="pre">max_age</span></code> parameter can
accept an integer or a <code class="xref py py-class docutils literal"><span class="pre">datetime.timedelta</span></code> object.</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.8:</span> <p>Previously, the <code class="docutils literal"><span class="pre">max_age</span></code> parameter only accepted an integer.</p>
</div>
</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"><span class="pre">dumps</span></code> and <code class="docutils literal"><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"><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"><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"><span class="pre">signing.loads(object)</span></code>:</p>
<div class="highlight-default"><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"><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"><span class="pre">dumps()</span></code>, raises <code class="docutils literal"><span class="pre">BadSignature</span></code> if signature fails.
Checks <code class="docutils literal"><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 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.8.19 documentation</a>
<ul><li><a href="index.html">Using Django</a>
<ul><li>Cryptographic signing</li></ul>
</li></ul>
</li>
</ul>
<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>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Mar 10, 2018</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>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
65530c6176058f9b54858c3b4f6385e6
>
files
>
977
