diff options
Diffstat (limited to 'doc/man/bcfg2-crypt.txt')
-rw-r--r-- | doc/man/bcfg2-crypt.txt | 121 |
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)` |