# $Id: README,v 1.8 2007/11/16 21:19:35 doug Exp $

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

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.

===== What's this?

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

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

http://dougbarton.us/PGP/scripts/ppf/		and/or
ftp://ftp.freebsd.org/pub/FreeBSD/ports/local-distfiles/dougb/

===== Why another filter package?

Does the world need yet another filter package to integrate pgp with Pine?
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 don't require Perl,
   and were simple enough that users could easily change the display format,
   or other options without complicated configure scripts or config files.
   Note: I have nothing against Perl, I use it quite a lot. However, we've
   decided to ship FreeBSD 5 and later with no interpreted languages in the
   base, so I needed something that didn't require extra packages to work.
   Also, I think that Perl overhead is overkill for something like this,
   and these filters are faster than any of the Perl alternatives I tested.

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 1.4.7, and Pine 4.64.
   Note: GnuPG 2.x works if you are running Pine locally. I have not yet
   tried running it on a remote desktop, but it should work.

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, I've
also added a pseudo-filter to verify messages that were sent using MIME
encoding to attach the signature. See INSTALL for how to use it. It's not
possible for a sending filter to create these kinds of MIME messages, since
Pine does not give the user the ability to twiddle attachments.

There is now also a (functional, but still a bit rough) script to decrypt
MIME attachments.

These MIME "filters" work with messages generated by Evolution, KMail,
Thunderbird, Mutt, pear, FreeNX, Claws, exmh, Mew, and I'm sure a few
others that are compliant to the standards.

They do not work with messages generated by Apple Mail, since they do not
follow RFC 3156. Specifically they combine the message and the signature
in one body.

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.

===== Contact

Feel free to contact me at the addresses 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, but if you have requests or
suggestions in this area be warned that I will probably need your help to test
possible solutions. :)

My pgp key should be available on the public key servers. The preferred
e-mail address is the first one listed:

pub   1024D/D5B2F0FB 2003-01-16
      Key fingerprint = 9DD1 E44C 8660 ADA6 580F  83B6 C886 A42B D5B2 F0FB
uid                  Doug Barton <DougB@DougBarton.us>
uid                  Doug Barton <DougB@DougBarton.net>
uid                  Doug Barton <DougB@FreeBSD.org>
sub   4096g/2DBB3F89 2003-01-16


Enjoy!
