pine-gpg-filter-0.70 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 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.


Behaviour modifying 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.70 (http://linux-ip.net/sw/pine-gpg-filter/)
 --resultfile (-R)      Pine returns the filter's STDERR via the
                        _RESULTFILE_  See 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.
 --autoid (-a)          Select a specific local key identifier by parsing
                        the From: header line.  Requires the use of
                        Pine's _INCLUDEALLHDRS_ directive.  See Examples.

Special options
===============

 --build-symlinks       This will install all of the compatibility symlinks
                        for the pine-gpg-filter program.  You must have
                        write permissions on the directory in question in
                        order to use this option.

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.  (Not recommended.)

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

*-verify:  The *-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.  Thus, not supplying the
  --datafile _DATAFILE_ option when using the *-verify commands is
  an error.
  
*-encrypt, *-sign-encrypt:  Any use of the encryption command
  requires at least one 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_


Compatibility names
===================
In order to make the utility easier to use, there are several ways
to call it without requiring long options.  Here are the names and
the indicated behaviour:

       option             compat           autoid compat
   ================   ================   =================
   --clearsign        pgf-clearsign      pgfa-clearsign
   --encrypt          pgf-encrypt        pgfa-encrypt
   --sign --encrypt   pgf-sign-encrypt   pgfa-sign-encrypt
   --sign             pgf-sign           pgfa-sign
   --decrypt          pgf-decrypt        pgfa-decrypt (N.B.)
   --verify           pgf-verify         pgfa-verify (N.B.)

N.B., for symmetry, the pgfa-decrypt and pgfa-verify compatibility
symlinks are installed, although there is little sense to a pine
filter which selects an identity for receiving a message.  Why?
Because GPG simply attempts to decrypt (or verify) the message with
the key used for encryption.  In these invocations, the autoid
component is simply ignored.

See also Examples, below.


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.

5: /path/to/pgf-verify -R _RESULTFILE_ -D _DATAFILE_
5: /path/to/pgf-verify --resultfile _RESULTFILE_ --datafile _DATAFILE_

   The verify functionality requires a temporary file.  If you do
   not supply the "--datafile _DATAFILE_", pine-gpg-filter cannot
   validate the signature on the message, and must abort.

6: /path/to/pgfa-sign-encrypt _INCLUDEALLHDRS_ -R _RESULTFILE_ _RECIPIENTS_

   This is the calling method for using the automatic identity
   selection of this utility.

7: /path/to/pgfa-clearsign _INCLUDEALLHDRS_ -R _RESULTFILE_

   To select one of your identities automatically for any
   clearsigning, this invocation should suffice.


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.
  -a, --autoid                Determine <key_id> (role) from From: line.
      --build-symlinks        Install pgf-* and pgfa-* symlinks.

