From 1291e5b09efb956d42e7ab83d485d41542f438f4 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Wed, 6 Jun 2012 09:31:14 -0400 Subject: added properties element encryption added bcfg2-crypt utility for encrypting Properties and Cfg files --- doc/server/plugins/connectors/properties.txt | 72 ++++++++++++++++++++++++++++ doc/server/plugins/generators/cfg.txt | 33 +++++++++---- 2 files changed, 96 insertions(+), 9 deletions(-) (limited to 'doc') 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 ````. + Usage ===== @@ -83,6 +86,75 @@ directly in one of several ways: top-level element. (I.e., everything directly under the ```` 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 ````, +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=""`` to the top-level +```` 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 -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 -in foo.conf -out foo.conf.crypt -a openssl enc -d -aes-256-cbc -k -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. -- cgit v1.2.3-1-g7c22