/usr/share/doc/pyro4-doc/html/security.html is in pyro4-doc 4.63-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 | <!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.63 documentation</title>
<link rel="stylesheet" href="_static/classic.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.63',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="/usr/share/javascript/jquery/jquery.js"></script>
<script type="text/javascript" src="/usr/share/javascript/underscore/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="next" title="Exceptions and remote tracebacks" href="errors.html" />
<link rel="prev" title="Name Server" href="nameserver.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<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="Exceptions and remote tracebacks"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="nameserver.html" title="Name Server"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Pyro 4.63 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="security">
<span id="index-0"></span><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-cloudpickle-and-dill-as-serialization-formats-optional">
<span id="index-1"></span><h2>Pickle, cloudpickle and dill as serialization formats (optional)<a class="headerlink" href="#pickle-cloudpickle-and-dill-as-serialization-formats-optional" title="Permalink to this headline">¶</a></h2>
<p>When configured to do so, Pyro is able to use the <code class="xref py py-mod docutils literal"><span class="pre">pickle</span></code>, <code class="xref py py-mod docutils literal"><span class="pre">cloudpickle</span></code>
or <code class="xref py py-mod docutils literal"><span class="pre">dill</span></code> modules to serialize objects and then sends them over the network.
It is well known that using these serializers for this purpose is a security risk.
The main problem is that allowing a program to deserialize this type of serialized data
can cause arbitrary code execution and this may wreck or compromise your system.
Because of this the default serializer is serpent, which doesn’t have this security problem.
Some other means to enhance security are discussed below.</p>
</div>
<div class="section" id="network-interface-binding">
<span id="index-2"></span><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 other machines.</p>
<p>It is possible to tell Pyro the interface address via an environment variable or global config item (<code class="docutils literal"><span class="pre">HOST</span></code>).
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">
<span id="index-3"></span><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="secure-communication-via-ssl-tls">
<span id="index-4"></span><h2>Secure communication via SSL/TLS<a class="headerlink" href="#secure-communication-via-ssl-tls" title="Permalink to this headline">¶</a></h2>
<p>Pyro itself doesn’t encrypt the data it sends over the network. This means if you use the default
configuration, you must never transfer sensitive data on untrusted networks
(especially user data, passwords, and such) because eavesdropping is possible.</p>
<p>You can run Pyro over a secure network (VPN, ssl/ssh tunnel) where the encryption
is taken care of externally. It is also possible however to enable SSL/TLS in Pyro itself,
so that all communication is secured via this industry standard that
provides encryption, authentication, and anti-tampering (message integrity).</p>
<p><strong>Using SSL/TLS</strong></p>
<p>Enable it by setting the <code class="docutils literal"><span class="pre">SSL</span></code> config item to True, and configure the other SSL config items
as required. You’ll need to specify the cert files to use, private keys, and passwords if any.
By default, the SSL mode only has a cert on the server (which is similar to visiting a https url
in your browser). This means your <em>clients</em> can be sure that they are connecting to the expected
server, but the <em>server</em> has no way to know what clients are connecting.
You can solve this by using a HMAC key (see <a class="reference internal" href="#hmackey"><span class="std std-ref">by using a HMAC signature via a shared private key</span></a>), but if you’re already using SSL,
a better way is to do custom certificate verification.
You can do this in your client (checks the server’s cert) but you can also tell your clients
to use certs as well and check these in your server. This makes it 2-way-SSL or mutual authentication.
For more details see here <a class="reference internal" href="#cert-verification"><span class="std std-ref">by using 2-way-SSL and certificate verficiation</span></a>. The SSL config items are in <a class="reference internal" href="config.html#config-items"><span class="std std-ref">Overview of Config Items</span></a>.</p>
<p>For example code on how to set up a 2-way-SSL Pyro client and server, with cert verification,
see the <code class="docutils literal"><span class="pre">ssl</span></code> example.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">You must use at least Python 2.7.11 / 3.4.4 or newer for proper SSL support.</p>
</div>
</div>
<div class="section" id="dotted-names-object-traversal">
<span id="index-5"></span><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 <code class="docutils literal"><span class="pre">proxy.aaa.bbb.ccc()</span></code>) is not possible in Pyro, 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> ).</p>
</div>
<div class="section" id="environment-variables-overriding-config-items">
<span id="index-6"></span><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"><span class="doc">Configuring Pyro</span></a> for the proper way to do this.</p>
</div>
<div class="section" id="preventing-arbitrary-connections">
<span id="index-7"></span><h2>Preventing arbitrary connections<a class="headerlink" href="#preventing-arbitrary-connections" title="Permalink to this headline">¶</a></h2>
<div class="section" id="by-using-a-hmac-signature-via-a-shared-private-key">
<span id="hmackey"></span><h3>by using a HMAC signature via a shared private key<a class="headerlink" href="#by-using-a-hmac-signature-via-a-shared-private-key" title="Permalink to this headline">¶</a></h3>
<p>You can use 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).
The hashing algorithm that is used in the HMAC is SHA-1.</p>
<div class="sidebar">
<p class="first sidebar-title">consider alternatives</p>
<p class="last">For industry standard encryption and connection verification, consider using SSL/TLS instead.</p>
</div>
<p>You need to create and configure a secure shared key yourself.
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. You can set the shared key via the <code class="docutils literal"><span class="pre">_pyroHmacKey</span></code> property on a proxy or a daemon:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">daemon</span><span class="o">.</span><span class="n">_pyroHmacKey</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">"secretkey"</span>
<span class="n">proxy</span><span class="o">.</span><span class="n">_pyroHmacKey</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">"secretkey"</span>
</pre></div>
</div>
<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 software and extract the key from it.
Pyro itself provides no facilities to help you with this, sorry.
The Diffie-Hellman Key Exchange algorithm is one example of a secure solution to this problem.
There’s the <code class="docutils literal"><span class="pre">diffie-hellman</span></code> example that shows the basics, but DO NOT use it directly
as being “the secure way to do this” – it’s only demo code.</p>
</div>
</div>
<div class="section" id="by-using-2-way-ssl-and-certificate-verficiation">
<span id="cert-verification"></span><span id="index-8"></span><h3>by using 2-way-SSL and certificate verficiation<a class="headerlink" href="#by-using-2-way-ssl-and-certificate-verficiation" title="Permalink to this headline">¶</a></h3>
<p>When using SSL, you should also do some custom certificate verification, such as checking the serial number
and commonName. This way your code is not only certain that the communication is encrypted, but also
that it is talking to the intended party and nobody else (middleman).
The server hostname and cert expiration dates <em>are</em> checked automatically, but
other attributes you have to verify yourself.</p>
<p>This is fairly easy to do: you can use <a class="reference internal" href="tipstricks.html#conn-handshake"><span class="std std-ref">Connection handshake</span></a> for this. You can then get the peer certificate
using <code class="xref py py-meth docutils literal"><span class="pre">Pyro4.socketutil.SocketConnection.getpeercert()</span></code>.</p>
<p>If you configure a client cert as well as a server cert, you can/should also do verification of
client certificates in your server. This is a good way to be absolutely certain that you only
allow clients that you know and trust, because you can check the required unique certificate attributes.</p>
<p>Having certs on both client and server is called 2-way-SSL or mutual authentication.</p>
<p>The <code class="docutils literal"><span class="pre">ssl</span></code> example shows how to do this.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<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-cloudpickle-and-dill-as-serialization-formats-optional">Pickle, cloudpickle and dill as serialization formats (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="#secure-communication-via-ssl-tls">Secure communication via SSL/TLS</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">Preventing arbitrary connections</a><ul>
<li><a class="reference internal" href="#by-using-a-hmac-signature-via-a-shared-private-key">by using a HMAC signature via a shared private key</a></li>
<li><a class="reference internal" href="#by-using-2-way-ssl-and-certificate-verficiation">by using 2-way-SSL and certificate verficiation</a></li>
</ul>
</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">Exceptions and remote tracebacks</a></p>
<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>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<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="Exceptions and remote tracebacks"
>next</a> |</li>
<li class="right" >
<a href="nameserver.html" title="Name Server"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Pyro 4.63 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright Irmen de Jong.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.5.
</div>
</body>
</html>
|