.. -*- mode: rst -*-
.. vim: ft=rst

bcfg2-crypt
===========

.. program:: bcfg2-crypt

Synopsis
--------

**bcfg2-crypt** [-C *configfile*] [--decrypt|--encrypt]
[--cfg|--properties] [--stdout] [--remove] [--xpath *xpath*]
[-p *passphrase-or-name*] [-v] [-I] *filename* [*filename*...]

Description
-----------

:program:`bcfg2-crypt` performs encryption and decryption of Cfg and
Properties files. It's often sufficient to run :program:`bcfg2-crypt`
with only the name of the file you wish to encrypt or decrypt; it can
usually figure out what to do.

Options
-------

-C configfile         Specify alternate bcfg2.conf location.
--decrypt, --encrypt  Select encryption or decryption mode for the
                      given file(s). This is usually unnecessary, as
                      :program:`bcfg2-crypt` can often determine which
                      is necessary based on the contents of each file.
--cfg                 An XML file should be encrypted in its entirety
                      rather than element-by-element. This is only
                      necessary if the file is an XML file whose name
                      ends with *.xml* and whose top-level tag is
                      *<Properties>*. See [MODES] below for details.
--properties          Process a file as an XML Properties file, and
                      encrypt the text of each element
                      separately. This is necessary if, for example,
                      you've used a different top-level tag than
                      *Properties* in your Properties files. See
                      [MODES] below for details.
--stdout              Print the resulting file to stdout instead of
                      writing it to a file.
--remove              Remove the plaintext file after it has been
                      encrypted.  Only meaningful for Cfg files.
--xpath xpath         Encrypt the character content of all elements
                      that match the specified XPath expression.  The
                      default is *\*[@encrypted]* or *\**; see [MODES]
                      below for more details. Only meaningful for
                      Properties files.
-p passphrase         Specify the name of a passphrase specified in
                      the *[encryption]* section of *bcfg2.conf*. See
                      [SELECTING PASSPHRASE] below for more details.
-v                    Be verbose.
-I                    When encrypting a Properties file, interactively
                      select the elements whose data should be
                      encrypted.
-h                    Print usage information.

Modes
-----

:program:`bcfg2-crypt` can encrypt Cfg files or Properties files; they
are handled very differently.

Cfg
    When :program:`bcfg2-crypt` is used on a Cfg file, the entire file
    is encrypted. This is the default behavior on files that are not
    XML, or that are XML but whose top-level tag is not *<Properties>*.
    This can be enforced by use of the *--cfg* option.

Properties
    When :program:`bcfg2-crypt` is used on a Properties file, it
    encrypts the character content of elements matching the XPath
    expression given by *--xpath*. By default the expression is
    *\*[@encrypted]*, which matches all elements with an *encrypted*
    attribute. If you are encrypting a file and that expression doesn't
    match any elements, then the default is *\**, which matches
    everything. When :program:`bcfg2-crypt` encrypts the character
    content of an element, it also adds the *encrypted* attribute, set
    to the name of the passphrase used to encrypt that element. When it
    decrypts an element it does not remove *encrypted*, though; this
    lets you easily and efficiently run :program:`bcfg2-crypt` against a
    single Properties file to encrypt and decrypt it without needing to
    specify a long list of options. See the online Bcfg2 docs on
    Properties files for more information on how this works.

Selecting passphrase
--------------------

The passphrase used to encrypt or decrypt a file is discovered in the
following order.

#. The passphrase given on the command line using *-p* is used.
#. If exactly one passphrase is specified in *bcfg2.conf*, it will be
   used.
#. If operating in Properties mode, *bcfg2.conf* will attempt to read
   the name of the passphrase from the encrypted elements.
#. If decrypting, all passphrases will be tried sequentially.
#. If no passphrase has been determined at this point, an error is
   produced and the file being encrypted or decrypted is skipped.

See Also
--------

:manpage:`bcfg2-server(8)`