<!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>Bcfg2 Data Encryption — Bcfg2 1.3.0 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.3.0',
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>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="top" title="Bcfg2 1.3.0 documentation" href="../index.html" />
<link rel="up" title="The Bcfg2 Server" href="index.html" />
<link rel="next" title="Genshi XML Template Reference" href="genshi-xml.html" />
<link rel="prev" title="Server-side Caching" href="caching.html" />
<link rel="stylesheet" href="../_static/bcfg2.css" type=""/>
</head>
<body>
<div style="text-align: left; padding: 10px 10px 15px 15px">
<a href="../index.html"><img src="../_static/bcfg2_logo.png" border="0" alt="sampledoc"/></a>
</div>
<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="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="genshi-xml.html" title="Genshi XML Template Reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="caching.html" title="Server-side Caching"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">home</a> | </li>
<!--<li><a href="../search.html">search</a> | </li>-->
<li><a href="../help/index.html">help</a> | </li>
<li><a href="../contents.html">documentation </a> »</li>
<li><a href="../contents.html" >Bcfg2 documentation 1.3.0</a> »</li>
<li><a href="index.html" accesskey="U">The Bcfg2 Server</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="bcfg2-data-encryption">
<span id="server-encryption"></span><h1>Bcfg2 Data Encryption<a class="headerlink" href="#bcfg2-data-encryption" title="Permalink to this headline">¶</a></h1>
<p class="versionadded">
<span class="versionmodified">New in version 1.3.0.</span></p>
<p>Bcfg2 supports encrypting some data on the disk, which can help
protect sensitive data from other people who need access to the Bcfg2
repository but are perhaps not authorized to see all data. It
supports multiple passphrases, which can be used to enforce
separations between teams, environments, etc.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This feature is <em>not</em> intended to secure the files against a
malicious attacker who has gained access to your Bcfg2 server, as
the encryption passphrases are held in plaintext in
<tt class="docutils literal"><span class="pre">bcfg2.conf</span></tt>. This is only intended to make it easier to use a
single Bcfg2 repository with multiple admins who should not
necessarily have access to each other’s sensitive data.</p>
</div>
<p>Two types of data can be encrypted:</p>
<ul class="simple">
<li><a class="reference internal" href="plugins/generators/cfg.html#server-plugins-generators-cfg"><em>Cfg</em></a> files can be encrypted
as whole files. See <a class="reference internal" href="plugins/generators/cfg.html#server-plugins-generators-cfg-encryption"><em>Encrypted Files</em></a>
for more details.</li>
<li><a class="reference internal" href="plugins/connectors/properties.html#server-plugins-connectors-properties"><em>Properties</em></a> data can be encrypted on
a per-element basis. See
<a class="reference internal" href="plugins/connectors/properties.html#server-plugins-connectors-properties-encryption"><em>Encrypted Properties data</em></a> for more
details.</li>
</ul>
<p>In general, Properties encryption is preferred for a few reasons:</p>
<ul class="simple">
<li>It plays nicely with your VCS. If you change an encrypted Cfg file,
then all you can see in your VCS log is that the file changed, no
details about how it changed. With an encrypted Properties file,
you can see which element changed (although obviously not the
changed content).</li>
<li>It is faster when you have more than one passphrase. When
decrypting a Cfg file, Bcfg2 simply brute-forces it with all known
passphrases; when decrypting a Properties element, the passphrase is
given by name so only one passphrase must be tried.</li>
<li>A Cfg file can only be encrypted with a single passphrase;
Properties files can use different passphrases for different
elements. If you are using different passphrases to segregate data
amongst different teams, this lets teams collaborate more closely on
files and other data.</li>
</ul>
<div class="section" id="bcfg2-crypt">
<span id="id1"></span><h2>bcfg2-crypt<a class="headerlink" href="#bcfg2-crypt" title="Permalink to this headline">¶</a></h2>
<p>Encrypting and decrypting <a class="reference internal" href="plugins/generators/cfg.html#server-plugins-generators-cfg"><em>Cfg</em></a> and
<a class="reference internal" href="plugins/connectors/properties.html#server-plugins-connectors-properties"><em>Properties</em></a> files can be done with the
<tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt> tool, which mostly tries to do the right thing. I.e.,
it encrypts plaintext files, decrypts encrypted files, and
automatically discovers if a file is Cfg or Properties. Its usage is
thus generally very simple, e.g.:</p>
<div class="highlight-python"><pre>bcfg2-crypt foo.conf
bcfg2-crypt foo.xml</pre>
</div>
<p>Since the behavior of <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt> varies significantly depending
on whether you are dealing with a Cfg or Properties files, these are
documented separately below. It’s also well worthwhile to familiarize
yourself with the man page for <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt>.</p>
<div class="section" id="encrypting-cfg-files">
<h3>Encrypting Cfg Files<a class="headerlink" href="#encrypting-cfg-files" title="Permalink to this headline">¶</a></h3>
<p>To encrypt a Cfg file, you can simply run:</p>
<div class="highlight-python"><pre>bcfg2-crypt foo.conf</pre>
</div>
<p>This will write the encrypted data to <tt class="docutils literal"><span class="pre">foo.conf.crypt</span></tt>. Once you
are satisfied that the file has been encrypted as you wish, you can
remove the plaintext version, or you can use the <tt class="docutils literal"><span class="pre">--remove</span></tt> flag of
<tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt>.</p>
<p>To decrypt a file, simply run <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt> again:</p>
<div class="highlight-python"><pre>bcfg2-crypt foo.conf.crypt</pre>
</div>
<p>On Cfg files, <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt> is more-or-less equivalent to the
following commands (encryption and decryption, respectively):</p>
<div class="highlight-python"><pre>openssl enc -aes-256-cbc -k <passphrase> -in foo.conf \
-out foo.conf.crypt -a
openssl enc -d -aes-256-cbc -k <passphrase> -in foo.conf.crypt \
-out foo.conf -a</pre>
</div>
<p>Those commands can be used in lieu of <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt> if you hate
convenience.</p>
</div>
<div class="section" id="encrypting-properties-files">
<h3>Encrypting Properties Files<a class="headerlink" href="#encrypting-properties-files" title="Permalink to this headline">¶</a></h3>
<p>To encrypt or decrypt a properties file, simply run:</p>
<div class="highlight-python"><pre>bcfg2-crypt foo.xml</pre>
</div>
<p>If the top-level tag of a Properties file is not <tt class="docutils literal"><span class="pre"><Properties></span></tt>,
then you need to use the <tt class="docutils literal"><span class="pre">--properties</span></tt> flag to <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt>:</p>
<div class="highlight-python"><pre>bcfg2-crypt --properties foo.xml</pre>
</div>
<p>The first time you run <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt> on a Properties file, it will
encrypt all character data of all elements. Additionally, it will add
<tt class="docutils literal"><span class="pre">encrypted="<key</span> <span class="pre">name>"</span></tt> to each element that has encrypted character
data. It also adds <tt class="docutils literal"><span class="pre">encryption="true"</span></tt> to the top-level
<tt class="docutils literal"><span class="pre"><Properties></span></tt> tag as a flag to the server that it should try to
decrypt the data in that file. (If you are using Properties schemas,
you will need to make sure to add support for these attributes.) On
subsequent runs, only those elements flagged with <tt class="docutils literal"><span class="pre">encrypted="*"</span></tt>
are encrypted or decrypted.</p>
<p>To decrypt a Properties file, simply re-run <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt>:</p>
<div class="highlight-python"><pre>bcfg2-crypt foo.xml</pre>
</div>
<p>This decrypts the encrypted elements, but it does <em>not</em> remove the
<tt class="docutils literal"><span class="pre">encrypted</span></tt> attribute; this way, you can decrypt a Properties
file, modify the contents, and then simply re-run <tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt> to
encrypt it again. If you added elements that you also want to be
encrypted, you can either add the <tt class="docutils literal"><span class="pre">encrypted</span></tt> attribute to
them manually, or run:</p>
<div class="highlight-python"><pre>bcfg2-crypt --xpath '*' foo.xml</pre>
</div>
<p>You can also use the <tt class="docutils literal"><span class="pre">--xpath</span></tt> option to specify more restrictive
XPath expressions to only encrypt a subset of elements, or to encrypt
different elements with different passphrases. Alternatively, you can
manally set the <tt class="docutils literal"><span class="pre">encrypted</span></tt> attribute on various elements and
<tt class="docutils literal"><span class="pre">bcfg2-crypt</span></tt> will automatically do the right thing. You can also
run bcfg2-crypt in interactive mode to interactively select which
attributes should be encrypted:</p>
<div class="highlight-python"><pre>bcfg2-crypt -I foo.xml</pre>
</div>
<p>If you want to use different passphrases within a single Properties
file, you must manually set the <tt class="docutils literal"><span class="pre">encrypted</span></tt> attribute.</p>
</div>
</div>
<div class="section" id="configuring-encryption">
<span id="server-encryption-configuration"></span><h2>Configuring Encryption<a class="headerlink" href="#configuring-encryption" title="Permalink to this headline">¶</a></h2>
<div class="section" id="passphrases">
<h3>Passphrases<a class="headerlink" href="#passphrases" title="Permalink to this headline">¶</a></h3>
<p>To configure encryption, add a <tt class="docutils literal"><span class="pre">[encryption]</span></tt> section to
<tt class="docutils literal"><span class="pre">bcfg2.conf</span></tt> with any number of name-passphrase pairs.</p>
<p>For instance:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">encryption</span><span class="p">]</span>
<span class="n">foo_team</span><span class="o">=</span><span class="n">P4ssphr4se</span>
<span class="n">bar_team</span><span class="o">=</span><span class="n">Pa55phra5e</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The name of a passphrase <strong>cannot</strong> be <tt class="docutils literal"><span class="pre">algorithm</span></tt> or
<tt class="docutils literal"><span class="pre">decrypt</span></tt>, which are reserved for other configuration options.</p>
</div>
<p>This would define two separate encryption passphrases, presumably for
use by two separate teams. The passphrase names are completely
arbitrary.</p>
<p>Note that this does entail a chicken-and-egg problem. In order for
the Bcfg2 server to be able to decrypt encrypted files, the
passphrases must exist in <tt class="docutils literal"><span class="pre">bcfg2.conf</span></tt> in plaintext; but, if you’re
encrypting data, presumably you don’t want to include those plaintext
passphrases in your Bcfg2 repository, so you’ll want to encrypt
<tt class="docutils literal"><span class="pre">bcfg2.conf</span></tt>. The best way to solve this is:</p>
<ol class="arabic simple">
<li>On your Bcfg2 server, manually add the <tt class="docutils literal"><span class="pre">[encryption]</span></tt> section to
<tt class="docutils literal"><span class="pre">bcfg2.conf</span></tt> and restart the Bcfg2 server.</li>
<li>Update <tt class="docutils literal"><span class="pre">bcfg2.conf</span></tt> in your Bcfg2 repository with the
passphrases, and encrypt it.</li>
</ol>
<p>The first (manual) step breaks the mutual dependency.</p>
</div>
<div class="section" id="algorithm">
<h3>Algorithm<a class="headerlink" href="#algorithm" title="Permalink to this headline">¶</a></h3>
<p>By default, Bcfg2 uses the AES-256-CBC cipher algorithm. If you wish
to change this, you can set the <tt class="docutils literal"><span class="pre">algorithm</span></tt> option in the
<tt class="docutils literal"><span class="pre">[encryption]</span></tt> section of <tt class="docutils literal"><span class="pre">bcfg2.conf</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">encryption</span><span class="p">]</span>
<span class="n">algorithm</span> <span class="o">=</span> <span class="n">bf_cbc</span>
</pre></div>
</div>
<p>The value of <tt class="docutils literal"><span class="pre">algorithm</span></tt> must be a valid OpenSSL cipher algorithm
according the naming model of the Python <tt class="xref py py-mod docutils literal"><span class="pre">M2Crypto</span></tt> module. To
get a list of valid algorithms, you can run:</p>
<div class="highlight-python"><pre>openssl list-cipher-algorithms | grep -v ' => ' | \
tr 'A-Z-' 'a-z_' | sort -u</pre>
</div>
</div>
<div class="section" id="lax-vs-strict-decryption">
<h3>Lax vs. Strict decryption<a class="headerlink" href="#lax-vs-strict-decryption" title="Permalink to this headline">¶</a></h3>
<p>By default, Bcfg2 expects to be able to decrypt every encrypted
datum. Depending on how encryption is implemented at your site,
though, that may not be possible. (For instance, if you use
encryption to protect data for your production environment from your
staging Bcfg2 server, then you would not expect the staging server to
be able to decrypt everything.) In this case, you want to enable lax
decryption in the <tt class="docutils literal"><span class="pre">[encryption]</span></tt> section of <tt class="docutils literal"><span class="pre">bcfg2.conf</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">encryption</span><span class="p">]</span>
<span class="n">decrypt</span> <span class="o">=</span> <span class="n">lax</span>
</pre></div>
</div>
<p>This causes a failed decrypt to produce a warning only, not an error.</p>
<p>This can be overridden by individual XML files by setting
<tt class="docutils literal"><span class="pre">decrypt="strict"</span></tt> on the top-level tag (or, vice-versa; if strict
is the default an XML file can specify <tt class="docutils literal"><span class="pre">decrypt="lax"</span></tt>.</p>
</div>
</div>
<div class="section" id="encryption-api">
<h2>Encryption API<a class="headerlink" href="#encryption-api" title="Permalink to this headline">¶</a></h2>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Bcfg2 Data Encryption</a><ul>
<li><a class="reference internal" href="#bcfg2-crypt">bcfg2-crypt</a><ul>
<li><a class="reference internal" href="#encrypting-cfg-files">Encrypting Cfg Files</a></li>
<li><a class="reference internal" href="#encrypting-properties-files">Encrypting Properties Files</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-encryption">Configuring Encryption</a><ul>
<li><a class="reference internal" href="#passphrases">Passphrases</a></li>
<li><a class="reference internal" href="#algorithm">Algorithm</a></li>
<li><a class="reference internal" href="#lax-vs-strict-decryption">Lax vs. Strict decryption</a></li>
</ul>
</li>
<li><a class="reference internal" href="#encryption-api">Encryption API</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="caching.html"
title="previous chapter">Server-side Caching</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="genshi-xml.html"
title="next chapter">Genshi XML Template Reference</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/server/encryption.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>
<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="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="genshi-xml.html" title="Genshi XML Template Reference"
>next</a> |</li>
<li class="right" >
<a href="caching.html" title="Server-side Caching"
>previous</a> |</li>
<li><a href="../index.html">home</a> | </li>
<!--<li><a href="../search.html">search</a> | </li>-->
<li><a href="../help/index.html">help</a> | </li>
<li><a href="../contents.html">documentation </a> »</li>
<li><a href="../contents.html" >Bcfg2 documentation 1.3.0</a> »</li>
<li><a href="index.html" >The Bcfg2 Server</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2013, Narayan Desai.
Last updated on Mar 20, 2013.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
b50d8ee6d7871fcc13c0677a9364ed59
>
files
>
435
