1 files changed, 121 insertions, 0 deletions
diff --git a/doc/man/bcfg2-crypt.txt b/doc/man/bcfg2-crypt.txt
new file mode 100644
index 000000000..37e60482e
--- /dev/null
+++ b/doc/man/bcfg2-crypt.txt
@@ -0,0 +1,121 @@
+.. 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
+    Specify which operation you'd like to perform.
+    :program:`bcfg2-crypt` can usually determine which is necessary
+    based on the contents of each file.
+
+--cfg
+    Tell :program:`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 :program:`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
+-----
+
+: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)`