added properties element encryption

added bcfg2-crypt utility for encrypting Properties and Cfg files

2 files changed, 96 insertions, 9 deletions

diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt
index 7695e902c..19814a54f 100644
--- a/doc/server/plugins/connectors/properties.txt
+++ b/doc/server/plugins/connectors/properties.txt
@@ -33,6 +33,9 @@ be checked when running ``bcfg2-lint``.  For instance, given::
 
 ``dns-config.xml`` will be validated against ``dns-config.xsd``.
 
+Although Properties files are technically freeform XML, the top-level
+XML tag should be ``<Properties>``.
+
 Usage
 =====
 
@@ -83,6 +86,75 @@ directly in one of several ways:
   top-level element.  (I.e., everything directly under the
   ``<Properties>`` tag.)
 
+.. _server-plugins-connectors-properties-encrypted:
+
+Encrypted Properties data
+=========================
+
+.. versionadded:: 1.3.0
+
+You can encrypt selected data in Properties files to protect that data
+from other people who need access to the repository.  See
+:ref:`server-plugins-generators-cfg-configuring-encryption` for
+details on configuring encryption passphrases.  The data is decrypted
+transparently on-the-fly by the server; you never need to decrypt the
+data in your templates.
+
+.. note::
+
+    This feature is *not* 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
+    ``bcfg2.conf``.  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.
+
+Properties files are encrypted on a per-element basis; that is, rather
+than encrypting the whole file, only the character content of
+individual elements is encrypted.  This makes it easier to track
+changes to the file in a VCS, and also lets unprivileged users work
+with the other data in the file.  Only character content of an element
+can be encrypted; attribute content and XML elements themselves cannot
+be encrypted.
+
+To encrypt a file, use ``bcfg2-crypt``, e.g.::
+
+    bcfg2-crypt foo.xml
+
+If the top-level tag of a Properties file is not ``<Properties>``,
+then you need to use the ``--properties`` flag to ``bcfg2-crypt``::
+
+    bcfg2-crypt --properties foo.xml
+
+The first time you run ``bcfg2-crypt`` on a Properties file, it will
+encrypt all character data of all elements.  Additionally, it will add
+``encrypted="true"`` to each element that has encrypted character
+data.  It also adds ``encryption="<key name>"`` to the top-level
+``<Properties>`` 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 ``encrypted="true"``
+are encrypted or decrypted.
+
+To decrypt a Properties file, simply re-run ``bcfg2-crypt``::
+
+    bcfg2-crypt foo.xml
+
+This decrypts the encrypted elements, but it does *not* remove the
+``encrypted="true"`` attribute; this way, you can decrypt a Properties
+file, modify the contents, and then simply re-run ``bcfg2-crypt`` to
+encrypt it again.  If you added elements that you also want to be
+encrypted, you can either add the ``encrypted="true"`` attribute to
+them manually, or run::
+
+    bcfg2-crypt --xpath '*' foo.xml
+
+You can also use the ``--xpath`` option to specify more restrictive
+XPath expressions to only encrypt a subset of elements.
+
+All encrypted elements in a single Properties file must be encrypted
+with the same passphrase.
+
 Accessing Properties contents from TGenshi
 ==========================================
 
diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt
index d97cf62e9..6c848fddb 100644
--- a/doc/server/plugins/generators/cfg.txt
+++ b/doc/server/plugins/generators/cfg.txt
@@ -145,7 +145,10 @@ Encrypted Files
 .. versionadded:: 1.3.0
 
 Bcfg2 allows you to encrypt files stored in ``Cfg/`` to protect the
-data in them from other people who need access to the repository.
+data in them from other people who need access to the repository.  See
+also :ref:`server-plugins-connectors-properties-encrypted` for
+information on encrypting elements in Properties files, which is often
+more friendly for tracking changes in a VCS.
 
 .. note::
 
@@ -172,21 +175,33 @@ either order, e.g.::
     Cfg/etc/foo.conf/foo.conf.G10_foo.genshi.crypt
     Cfg/etc/foo.conf/foo.conf.H_bar.example.com.crypt.cheetah
 
-To encrypt a file, you can run::
+To encrypt a file, you can use ``bcfg2-crypt``, e.g.::
 
-    openssl enc -aes-256-cbc -k <passphrase> -in foo.conf -out foo.conf.crypt -a
+    bcfg2-crypt foo.conf
 
 Once you are satisfied that the file has been encrypted as you wish,
-you can remove the plaintext version.
+you can remove the plaintext version, or you can use the ``--remove``
+flag of ``bcfg2-crypt``.
+
+To decrypt a file, simply run ``bcfg2-crypt`` again::
+
+    bcfg2-crypt foo.conf
 
-To decrypt a file, you can run::
+See the ``bcfg2-crypt`` man page for more information.
 
+``bcfg2-crypt`` simply performs an AES256 encryption, and is
+more-or-less equivalent to the following commands (encryption and
+decryption, respectively::
+
+    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
 
+.. _server-plugins-generators-cfg-configuring-encryption:
+
 Configuring Encryption
 ----------------------
 
-To configure encryption, add a ``[cfg:encryption]`` section to
+To configure encryption, add a ``[encryption]`` section to
 ``bcfg2.conf`` with any number of name-passphrase pairs.  When
 decrypting a file, _all_ passphrases will be tried; the passphrase
 name is currently purely cosmetic, but at some point in the future the
@@ -195,7 +210,7 @@ added.
 
 For instance::
 
-    [cfg:encryption]
+    [encryption]
     foo_team=P4ssphr4se
     bar_team=Pa55phra5e
 
@@ -210,8 +225,8 @@ encrypting data, presumably you don't want to include those plaintext
 passphrases in your Bcfg2 repository, so you'll want to encrypt
 ``bcfg2.conf``.  The best way to solve this is:
 
-#. On your Bcfg2 server, manually add the ``[cfg:encryption]`` section
-   to ``bcfg2.conf`` and restart the Bcfg2 server.
+#. On your Bcfg2 server, manually add the ``[encryption]`` section to
+   ``bcfg2.conf`` and restart the Bcfg2 server.
 #. Update ``bcfg2.conf`` in your Bcfg2 repository with the
    passphrases, and encrypt it.