bcfg2-crypt(8) -- Bcfg2 encryption and decryption utility
=========================================================

## SYNOPSIS

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

## DESCRIPTION

`bcfg2-crypt` performs encryption and decryption of Cfg and Properties
files.  It's often sufficient to run `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`:
    Specify which operation you'd like to perform.  `bcfg2-crypt` can
    usually determine which is necessary based on the contents of each
    file.

  * `--cfg`:
    Tell `bcfg2-crypt` that 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`:
    Tell `bcfg2-crypt` to 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`:
    Display help and exit.

## MODES

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

  * Cfg:
    When `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 `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
    `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 `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:

  * First, the passphrase given on the command line using `-p` is
    used.

  * Next, if exactly one passphrase is specified in `bcfg2.conf`, it
    will be used.

  * Next, if operating in Properties mode, `bcfg2-crypt` will attempt
    to read the name of the passphrase from the encrypted elements.

  * Next, 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

bcfg2-server(8)