pine-gpg-filter-0.62 README

Description
===========
pine-gpg-filter (pgf) is almost a clone of pinepg [0].  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".

 --clearsign (-c)       Have GPG clearsign the message.  This is what
                        most people mean when they talk about "signed"
                        email messages.
 --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 (use with encrypt).
 --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.62 (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.


Prerequisites
=============
You must have a working GnuPG installation.  If you are using these
scripts for integration with your pine MUA and you have only a
single GPG identity (one secret key), you may wish to consider the
GnuPG option (check ~/.gnupg/options or ~/.gnupg/gpg.conf in newer
versions) known as "encrypt-to".  The encrypt-to option allows you
to specify a key identifier which will be added to the recipient
list for any encryption.

Although not strictly a prerequisite, you may find that the
passphrase caching offered by gpg-agent (included in SuSE's gpg2
package) will save some keystrokes when used with this filter, which
performs none of its own caching.


Notes on sending-filters and display-filters
============================================

all scripts:  All of the scripts can make use of the _RESULTFILE_
  token as either a sending-filter or a display-filter.  The
  _RESULTFILE_ is used to store output like "gpg: Good signature..."
  while the filter itself is running.

  I recommend invoking each of the utilities with the "--resultfile
  _RESULTFILE_" option (see Examples, below).  Pine will pause and
  display the STDERR output from GPG, which has ended up in the
  _RESULTFILE_.  This option is, perhaps, less important when used
  on the sending-filters.

  If you are absolutely sure you want to bypass the confirmations
  of successful decryption or verification, you may omit the "-R
  _RESULTFILE_" (in which case, the output will go to the terminal
  "behind" pine's curses interface) or you may specify "-R
  /dev/null" to obliterate the output.

  I would encourage the use of "--resultfile _RESULTFILE_", because
  the user will then receive feedback from the GPG regarding the
  signature (or encryption).

pgf-verify:  The pgf-verify command requires the use of a temporary
  file (it uses a FIFO) in order to both output the text of the
  message and validate the signature.
  
pgf-encrypt, pgf-sign-encrypt:  Any use of the encryption command
  requires a recipient.  If there is no recipient, then the command
  will fail.  Pine will provide the recipient list, including Cc and
  Bcc (careful!), to the filters as command line arguments.  By
  using the _RECIPIENTS_ token in the sending-filter, you are asking
  pine to provide these addresses.


Simplest usage
==============

With the exception of the incorrect path, the below examples are the
minimum configuration set for using the pine-gpg-filter tools.  (Note, that
these pinerc entries are line broken for readability.)

display-filters=_LEADING("-----BEGIN PGP MESSAGE-----")_ \
                    /path/to/pgf-decrypt -R _RESULTFILE_,
_LEADING("-----BEGIN PGP SIGNED MESSAGE-----")_  \
                    /path/to/pgf-verify -D _DATAFILE_ -R _RESULTFILE_

sending-filters=/path/to/pgf-clearsign -R _RESULTFILE_
/path/to/pgf-sign-encrypt -R _RESULTFILE_ _RECIPIENTS_


Examples
========
Here are several examples of how to configure your pine filters:

  
0: /path/to/pgf-sign-encrypt --resultfile _RESULTFILE_ _RECIPIENTS_
0: /path/to/pgf-sign-encrypt -r _RESULTFILE_ _RECIPIENTS_

   The above will select the primary GPG key ID to use for signing
   and encrypting the message.  These two are exactly the same, one
   uses the long command line options, and the other uses the short
   command line options.

1: /path/to/pgf-sign-encrypt -tl 0x2486302b -R _RESULTFILE_ _RECIPIENTS_
1: /path/to/pgf-sign-encrypt --to-self --local-user 0x2486302b \
     --resultfile _RESULTFILE_ _RECIPIENTS_

   In these examples, we are specifying the key identifier
   (0x0x2486302b) we wish to use when encrypting.  The --to-self
   (-t) option instructs GPG to encrypt the message not only to the
   _RECIPIENTS_, but also to the key 0x2486302b.

   Because there may be multiple _RECIPIENTS_, this should be the
   last parameter on the command line.

2: /path/to/pgf-clearsign -l frank@cheese-shop.net -R _RESULTFILE_
2: /path/to/pgf-clearsign --local-user frank@cheese-shop.net \
     --resultfile _RESULTFILE_

   In this case, we are asking GPG to use the key for address
   frank@cheese-shop.net.

3: /path/to/pgf-clearsign -C "Organization Name" -R _RESULTFILE_

   We do not specify a key ID here, so the default GPG user will be
   selected.  The --comment (-C) option allows you to alter the
   string sent in the body of the GPG signature (in this case, or
   the header of the encrypted message in the case of encryption).

4: /path/to/pgf-sign-encrypt -nR _RESULTFILE_ _RECIPIENTS_

   Maybe you don't like the advertisement for pine-gpg-filter in the
   clearsign text of your messages.  Suppress the comment string
   by using the --no-comment (-n) option.


Future
======
There is a not-yet-implemented feature called "--autoid".  By taking
advantage of pine's _INCLUDEALLHDRS_ directive, we should be able to
grab the address between the wedges '<>' on the From: line and use
that email address as the GPG ID.


Similar applications
====================

 [0] http://quantumlab.net/pine_privacy_guard/     pinepg
 [1] http://hany.sk/~hany/software/pinepgp/        pinepgp
 [2] http://user.cs.tu-berlin.de/~gator/pgp4pine/  PGP4Pine (PAPP) 
 [3] http://dougbarton.net/FreeBSD/Downloads/      Pine PGP Filters 
 [4] http://pgpenvelope.sourceforge.net/           pgpenvelope


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

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.
  -c, --clearsign             Ask GPG to clearsign the input.
  -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.
  -D, --datafile    <file>    Use pine-provided _DATAFILE_ as temporary FIFO.
  -R, --resultfile  <file>    Pine reports command output via _RESULTFILE_.
  -l, --local-user  <key_id>  Specify a local username.

