<!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>Security — Pyro 4.21 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: '4.21',
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="Pyro 4.21 documentation" href="index.html" />
<link rel="next" title="Errors and remote tracebacks" href="errors.html" />
<link rel="prev" title="Name Server" href="nameserver.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="errors.html" title="Errors and remote tracebacks"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="nameserver.html" title="Name Server"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Pyro 4.21 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="security">
<span id="id1"></span><h1>Security<a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h1>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Do not publish any Pyro objects to remote machines unless you’ve read and understood everything
that is discussed in this chapter. This is also true when publishing Pyro objects with different
credentials to other processes on the same machine.
Why? In short: using Pyro has several security risks. Pyro has a few countermeasures to deal with them.
Understanding the risks, the countermeasures, and their limits, is very important to avoid
creating systems that are very easy to compromise by malicious entities.</p>
</div>
<div class="section" id="pickle-as-serialization-format-optional">
<h2>Pickle as serialization format (optional)<a class="headerlink" href="#pickle-as-serialization-format-optional" title="Permalink to this headline">¶</a></h2>
<p>When configured to do so, Pyro is able to use the <tt class="xref py py-mod docutils literal"><span class="pre">pickle</span></tt> module to serialize objects and then sends those pickles over the network.
It is well known that using pickle for this purpose is a security risk.
The main problem is that allowing a program to unpickle arbitrary data can cause arbitrary code execution
and this may wreck or compromise your system.</p>
<p>Although this may sound like a showstopper for using Pyro for anything serious, Pyro provides a few facilities
to deal with this security risk. The most important one is that by default, a different serializer is used that
doesn’t have pickle’s security problem. Other means to enhance security are discussed below.</p>
</div>
<div class="section" id="network-interface-binding">
<h2>Network interface binding<a class="headerlink" href="#network-interface-binding" title="Permalink to this headline">¶</a></h2>
<p>By default Pyro binds every server on localhost, to avoid exposing things on a public network or over the internet by mistake.
If you want to expose your Pyro objects to anything other than localhost, you have to explicitly tell Pyro the
network interface address it should use. This means it is a conscious effort to expose Pyro objects to remote machines.</p>
<p>It is possible to tell Pyro the interface address by means of an environment variable or global config item (<tt class="docutils literal"><span class="pre">HOST</span></tt>).
In some situations, or if you’re paranoid, it is advisable to override this setting in your server program
by setting the config item from within your own code instead of depending on an externally configured setting.</p>
</div>
<div class="section" id="running-pyro-servers-with-different-credentials-user-id">
<h2>Running Pyro servers with different credentials/user id<a class="headerlink" href="#running-pyro-servers-with-different-credentials-user-id" title="Permalink to this headline">¶</a></h2>
<p>The following is not a Pyro specific problem, but is important nonetheless:
If you want to run your Pyro server as a different user id or with different credentials as regular users,
<em>be very careful</em> what kind of Pyro objects you expose like this!</p>
<p>Treat this situation as if you’re exposing your server on the internet (even when it’s only running on localhost).
Keep in mind that it is still possible that a random user on the same machine connects to the local server.
You may need additional security measures to prevent random users from calling your Pyro objects.</p>
</div>
<div class="section" id="protocol-encryption">
<h2>Protocol encryption<a class="headerlink" href="#protocol-encryption" title="Permalink to this headline">¶</a></h2>
<p>Pyro doesn’t encrypt the data it sends over the network. This means you must not transfer
sensitive data on untrusted networks (especially user data, passwords, and such) because it is
possible to eavesdrop. Either encrypt the data yourself before passing it to Pyro, or run Pyro
over a secure network (VPN, ssl/ssh tunnel).</p>
</div>
<div class="section" id="dotted-names-object-traversal">
<h2>Dotted names (object traversal)<a class="headerlink" href="#dotted-names-object-traversal" title="Permalink to this headline">¶</a></h2>
<p>Using dotted names on Pyro proxies (such as <tt class="docutils literal"><span class="pre">proxy.aaa.bbb.ccc()</span></tt>)
is disallowed by default because it is a security vulnerability
(for similar reasons as described here <a class="reference external" href="http://www.python.org/news/security/PSF-2005-001/">http://www.python.org/news/security/PSF-2005-001/</a> ).
You can enable it with the <tt class="docutils literal"><span class="pre">DOTTEDNAMES</span></tt> config item, but be aware of the implications.</p>
<p>The <tt class="file docutils literal"><span class="pre">attributes</span></tt> example shows one of the exploits you can perform if it is enabled.</p>
</div>
<div class="section" id="environment-variables-overriding-config-items">
<h2>Environment variables overriding config items<a class="headerlink" href="#environment-variables-overriding-config-items" title="Permalink to this headline">¶</a></h2>
<p>Almost all config items can be overwritten by an environment variable.
If you can’t trust the environment in which your script is running, it may be a good idea
to reset the config items to their default builtin values, without using any environment variables.
See <a class="reference internal" href="config.html"><em>Configuring Pyro</em></a> for the proper way to do this.</p>
</div>
<div class="section" id="preventing-arbitrary-connections-hmac-signature">
<h2>Preventing arbitrary connections: HMAC signature<a class="headerlink" href="#preventing-arbitrary-connections-hmac-signature" title="Permalink to this headline">¶</a></h2>
<p>Pyro suggests using a <a class="reference external" href="http://docs.python.org/library/hmac.html">HMAC signature</a> on every network transfer
to prevent malicious requests. The idea is to only have legit clients connect to your Pyro server.
Using the HMAC signature ensures that only clients with the correct secret key can create valid requests,
and that it is impossible to modify valid requests (even though the network data is not encrypted).</p>
<p>You need to create and configure a secure shared key in the <tt class="docutils literal"><span class="pre">HMAC_KEY</span></tt> config item.
The key is a byte string and must be cryptographically secure (there are various methods to create such a key).
Your server needs to set this key and every client that wants to connect to it also needs to
set it.</p>
<p>Pyro will cause a Python-level warning message if you run it without a HMAC key, but it will run just fine.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is hard to keep a shared secret key actually secret!
People might read the source code of your clients and extract the key from it.
Pyro itself provides no facilities to help you with this, sorry.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/pyro.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Security</a><ul>
<li><a class="reference internal" href="#pickle-as-serialization-format-optional">Pickle as serialization format (optional)</a></li>
<li><a class="reference internal" href="#network-interface-binding">Network interface binding</a></li>
<li><a class="reference internal" href="#running-pyro-servers-with-different-credentials-user-id">Running Pyro servers with different credentials/user id</a></li>
<li><a class="reference internal" href="#protocol-encryption">Protocol encryption</a></li>
<li><a class="reference internal" href="#dotted-names-object-traversal">Dotted names (object traversal)</a></li>
<li><a class="reference internal" href="#environment-variables-overriding-config-items">Environment variables overriding config items</a></li>
<li><a class="reference internal" href="#preventing-arbitrary-connections-hmac-signature">Preventing arbitrary connections: HMAC signature</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="nameserver.html"
title="previous chapter">Name Server</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="errors.html"
title="next chapter">Errors and remote tracebacks</a></p>
<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>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="errors.html" title="Errors and remote tracebacks"
>next</a> |</li>
<li class="right" >
<a href="nameserver.html" title="Name Server"
>previous</a> |</li>
<li><a href="index.html">Pyro 4.21 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright Irmen de Jong.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
