# $Id: README,v 1.11 2010/07/29 20:02:19 dougb Exp $

===== Notes
If you are looking for installation and usage instructions, please see
the INSTALL file.

These scripts have been tested with Alpine 2.00. Previous versions were
developed with Pine 4.64, and almost certainly remain compatible with it.

GnuPG 2.x works if you are running Alpine locally, and have a pinentry dialog.
It works with pinentry-curses for ppf_decrypt, but not ppf_sign or ppf_encrypt.

===== What is this?

This is the "Pine PGP Filters" package for Unix, created by Douglas Barton.

The latest version of this package; MD5, SHA1, and SHA256 fingerprints,
and a pgp signature should be available at:

http://dougbarton.us/PGP/ppf/

===== Why another filter package?

Does the world need yet another filter package to integrate pgp with Alpine?
Maybe not, but I felt the need to create one anyway. Here are my reasons:

1. With due respect to the authors of other packages, they don't meet my needs.

2. The FreeBSD Project already had a set of simple, Bourne Shell based filters.
   However, they had suffered from bitrot over time, and didn't support GnuPG.

3. Therefore, I wanted something that I could replace the old FreeBSD scripts
   with, and since I was revamping them anyway, I decided to start from
   scratch with new scripts that address all the things I wanted as well.

===== Design goals

1. I wanted to create a set of "stand alone" filters that do not require a
   language that is not in the FreeBSD base and were simple enough that users
   could easily change the display format or other options without complicated
   configure scripts or config files.

2. Simple, simple, simple. (Also fast, fast, fast. :)  I like to keep things
   simple, and generally that means that they are fast as well. Part of making
   this as simple as possible involved splitting out the verify and decrypt
   functions into separate scripts. This made both scripts simpler. The main
   difference is that you need to supply a password for decryption, which
   makes that script slightly more complicated. Separating the two functions
   allowed me to make the verify script (which is called most often) simpler.

3. The GNU Project's GPG package is by far the most popular Unix command line
   implementation nowadays, so it is the only one supported.

4. Compatibility with the latest GnuPG versions 1 and 2. These scripts were
   developed and thoroughly tested with GnuPG version 2.0.16, and Alpine 2.00.

5. Capable of handling a wide variety of input without failing.

6. Secure. I've tried to make these scripts as secure as possible, to the best
   of my ability.

7. Did I mention fast?

===== Features

In addition to the standard functions of encrypt/decrypt and sign/verify for
inline PGP messages there are also pseudo-filters to verify and decrypt
messages that were sent using MIME encoding. See INSTALL for how to use them.
It is not possible for a sending filter to create these kinds of MIME messages
since Alpine does not give the user the ability to twiddle attachments.

These MIME "filters" work with messages generated by Apple Mail, Claws Mail,
Evolution, exmh, FreeNX, GPGMail, Gnus, KMail, Mew, Mulberry, Mutt, Outlook,
pear, The Bat!, Thunderbird/Enigmail, and I'm sure a few others that are
compliant with the standards.

As of version 1.2, the ppf_sign and ppf_encrypt scripts now search the headers
of your message looking for the From: header, or an [X-]OpenPGP[-Key-ID]
header if it exists. The latter overrides the former. The information from
these headers is used as input to the --local-user switch for GnuPG.
Mine looks like this:
OpenPGP: id=1A1ABC84

===== Contact

Feel free to contact me at the address below. I will do my best to respond
in a timely manner, but please don't be offended if I don't. :) I'm interested
in suggestions for how to improve these filters. I'm also interested in making
them as useful as possible on other platforms. If you have requests or
suggestions in this area be warned that I will probably need your help to test
possible solutions.

pub   2048R/1A1ABC84 2010-03-23
      Key fingerprint = E352 0E14 9D05 3533 C33A  67DB 5CC6 86F1 1A1A BC84
uid                  Douglas Barton dougb@dougbarton.us
sub   3072R/498795B4 2010-03-23


Enjoy!