pine-gpg-filter-0.3 README

Description
===========
pine-gpg-filter is almost a clone of pinepg*.  It, however,
adds the capability for specifying which user ID (or IDs) to use for
the encryption or signing.  It does absolutely no passphrase
caching.  If you need (want) passphrase caching, look into
gpg-agent, available in the "gnupg2" package, e.g., gnupg-1.9.21 as
of 2006-07-04.

This utility is intended to allow the pine user to be able to take
advantage of multiple separate roles and keys for each of those
roles within pine.  Other pine and GnuPG integration (i.e.,
pgp4pine, pinepg) utilities do not allow for selection of user ID
for a particular encryption or signing request.

Required Option(s)
==================
At least one of these first four options is required.  The sign and
encrypt options may be combined, but no other combination is
possible.  If multiple options are specified in incompatible
combinations, the last one "wins".

 --encrypt (-e)         Have GPG encrypt the message.  When using
                        this option, you must specify recipient
                        addresses, as well.
 --sign (-s)            Have GPG sign the message.
 --decrypt (-d)         Have GPG decrypt the message.
 --verify (-v)          Have GPG verify the message.

These options

 --to-self (-t)         This option asks GPG to employ the encrypt-to-self
                        option, where self is defined as the local
                        user <key_id> specified with the -L option.
                        (This option is simply ignored if not needed.)

 --one-line (-o)        Only print out one line of the status generated
                        by GnuPG on the STDERR (_RESULTFILE_).
 --multi-line (-m)      Produce all of the usual GnuPG status output.
 --no-comment (-n)      Suppress the default comment string.
 --comment (-c)         Override the default comment string. Default is
                        pgf-0.3 (http://linux-ip.net/sw/pine-gpg-filter/)
 --resultfile (-R)      Pine returns the filter's STDERR via the
                        _RESULTFILE_ (cf. Examples).
 --datafile (-D)        Pine provides a session-unique filename called
                        We use it as a FIFO.  _DATAFILE_ (cf. Examples).
 --local-user (-l)      Select a specific local key identifier.  With this
                        option, you may specify a non-default key on
                        your GPG keyring.  The <key_id> may be an
                        email address or the actual key ID itself.


Examples
========
In this iteration of the tool, you are required to specify in your pine
sending-filters which key you wish to use.
  
  example 0; encrypt the message (sending-filters)
  ================================================
  /path/to/pgf -tL <key_id> -ER _RESULTFILE_ _RECIPIENTS_

  example 1; sign the message (sending-filters)
  ================================================
  /path/to/pgf -tL <key_id> -SR _RESULTFILE_


  * pinepg:  http://quantumlab.net/pine_privacy_guard/


Usage
=====
Usage: pine-gpg-filter [ options ] <arg> [ <arg> ... ]

Options (defaults marked, or in parentheses):
  -h, --help                 Print out this handy help screen.
  -L, --long-usage           Provide help and some more hints.
  -q, --quiet                Reset verbosity to none.
  -v, --verbose              Increase verbosity, can be used multiple times.
  -V, --version              Print version information.
  -e, --encrypt              Ask GPG to encrypt the input.
  -s, --sign                 Ask GPG to sign the input.
  -d, --decrypt              Ask GPG to decrypt the input.
  -y, --verify               Ask GPG to verify the input.
  -o, --one-line             Compress multiline status output from GPG.
  -m, --multi-line           Allow all of the status output from GPG.
  -t, --to-self              Also encrypt-to-self (ignored if not needed).
  -n, --no-comment           Suppress any comment string.
  -c, --comment <string>     Override the default comment string.
  -R, --resultfile <file>    Pine reports command output via _RESULTFILE_.
  -l, --local-user <key_id>  Specify a local username.

