# $Id: INSTALL,v 1.10 2007/12/05 01:08:39 doug Exp $

In order for the scripts to work, before you start you will need the following:
/bin/sh, mktemp, [e]grep, less, sed, tr, cat, csplit, and the latest version of
GnuPG. If you are a FreeBSD user, you will find GnuPG in the ports collection,
ports/security/gnupg[1], and the rest of the binaries installed by default.

The configure script will look for your gpg2 binary in PREFIX/bin, /usr/bin,
and /bin, in that order, then repeat the search for gpg 1.x if version 2 is
not found.

Note: These scripts have been tested with the development versions of Alpine
as well as Pine 4.64. Everywhere that Pine is referenced you can substitute
Alpine safely.

Installation is quite simple:

./configure [--help|--prefix=/path]	# /usr/local is the default
make install

The Makefile will install the scripts to PREFIX/libexec. To make use of them
you will have to modify your Pine config. First make a backup of your config,
then start Pine and type M for "Menu" (if you're not already there), S for
"Setup," and C for "Config." Assuming that /usr/local is your PREFIX, to verify
and/or decrypt files, put the following in your display-filters option, exactly
as shown:

_LEADING("-----BEGIN PGP SIGNED ")_ /usr/local/libexec/ppf_verify _TMPFILE_
_LEADING("-----BEGIN PGP MESSAGE")_ /usr/local/libexec/ppf_decrypt _TMPFILE_

I highly recommend using _LEADING() instead of _BEGINNING() since it is a
lot faster for Pine to scan just one line for filters than every line of the
message.

If you want to verify or decrypt pgp messages that occur other places in the
text of an e-mail, just pipe the message to 'gpg --verify' (for example).

To sign and/or encrypt messages that you send, put the following in your
sending-filters option:

/usr/local/libexec/ppf_sign _INCLUDEALLHDRS_
/usr/local/libexec/ppf_encrypt _INCLUDEALLHDRS_ _RECIPIENTS_

To sign or encrypt a file, when you choose ^X to send, you should see the
following options:

Send message (unfiltered)?
 ? Help         Y [Yes]         ^P Prev Filter  ^R Background
^C Cancel       N No            ^N Next Filter

To sign or encrypt, use the ^N or ^P options to rotate to the desired filter,
then type y (for Yes), or just hit Enter. If you regularly sign or encrypt
your mail, you might want to choose the "compose-send-offers-first-filter"
option from the Composer Preferences menu.

*** WARNING ***
Because of the way Pine handles attachments, it is not possible to encrypt
or sign them using a filter. If you need privacy or verification for your
attachments, they must be signed and/or encrypted before you attach them.

Other options you may find useful are:
enable-8bit-esmtp-negotiation
character-set=iso-8859-1

Be sure to read the help for those options, and test them out in your
environment before sending anything critical. Of course, iso-8859-1 is
not going to be an appropriate choice for everyone, you'll have to weigh
your alternatives.

If you use a different character set, you should make sure that the setting
in Pine and the setting in your terminal emulator match. You might also
want to consider using the display-charset option in your gpg.conf file.

You might also consider adding an X-OpenPGP-Key-ID header either in the
general Customized Headers field, or in a role configuration. While the
X-OpenPGP* headers are not fully standardized, they are fairly common
and a lot of mail clients know how to use them. Mine looks like this:
X-OpenPGP-Key-ID: 0xD5B2F0FB

If this header is present it will be preferred for the signing key in
the ppf_encrypt and ppf_sign filters.

You might want to consider adding an "encrypt-to" line in your
~/.gnupg/gpg.conf file with your primary encryption key ID.
This will insure that you can always read messages that you encrypt.

Finally, in order to use the ppf_mime "filters" to verify messages whose pgp
signatures are attached to the message with MIME type application/pgp, you
will need to choose the enable-unix-pipe-cmd option, since there is no way to
do this task with a real filter at this time.

To verify the signature of a MIME encoded e-mail, choose the | (Pipe) option,
then ^W for Raw Text, then type in the filter name:

Pipe RAW message 1 to : ppf_mime
^G Help                       ^W Shown Text   ^R With Delimiter
^C Cancel      Ret Accept     ^Y Free Output

While this procedure is a little cumbersome the first time through, the good
news is that Pine will offer these choices as the defaults for subsequent
invocations of the | command during that same session. Once you've viewed
the processed message output, just type E (Exit Viewer) and you're back to the
message view you were in previously.

To use the ppf_mime_decrypt script, you use the same procedure, except that
you need to also toggle the ^Y option which normally reads "Free Output"
as above to read "Capture Output." This is necessary to deal with what
appears to be a bug in Pine that prevents entering the password at the
GnuPG prompt. The output of the command is piped to less for viewing. To
switch back to using ppf_mime for verification, you will have to toggle
the ^Y option back to its default position.

This procedure is a bit cumbersome, but to my knowledge this is the only set
of filters that actually works with MIME signatures or encrypted files.
