## README for ez-pine-gpg
## http://Business-PHP.com/opensource/ez-pine-gpg/

* INSTALL
* CONFIG
* ADVANCED
* KNOWN ISSUES
* MISC
* HISTORY

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* INSTALL

the install script in this directory is used this way:

./install /install/path/

If this is a system-wide install '/usr/local/bin/' might be a good choice.
If this is an install just for you '~/bin/' is probably good.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* CONFIG

pine-config:

display-filters =	_BEGINNING("-----BEGIN PGP")_ /full/path/to/ez-pine-gpg-incoming
sending-filters =	/full/path/to/ez-pine-gpg-sign-and-encrypt _INCLUDEALLHDRS_ _RECIPIENTS_
			/full/path/to/ez-pine-gpg-encrypt _RECIPIENTS_
			/full/path/to/bin/ez-pine-gpg-sign _INCLUDEALLHDRS_

most users won't need to read anything else.
	1) install the scripts
	2) configure pine
	3) enjoy

for the curious and the power-users, keep reading.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* ADVANCED

as of v0.4g there is an "ez-pine-gpg-symmetric" sending filter that allows
messages to be encrypted with a symmetric key (shared passphrase). this
filter is installed with the rest of the filters but it's configuration
is not mentioned by the install script. it's the kind of thing that only
tends to be useful to people who read README files, so that's where i've
hidden it's configuration:
	sending-filters =       /full/path/to/ez-pine-gpg-symmetric
place it within the sending filters where it makes sense for you.

these scripts will do their best to figure out what public
keys should be used when encrypting to the recipients. this
is based on the email address being used.

these scripts will also do their best to figure out what
private key to use when signing. if there is a header
"X-OpenPGP-KeyID" or "X-OpenPGP-Key-ID" we'll use that
key for signing:
 X-OpenPGP-KeyID: 0x12345678 (1024D)
 X-OpenPGP-Key-ID: (1024D) 0x12345678
** the key type is optional, and may be before or after
** the key id
** the important thing is that the key id is separated by
** spaces from anything else on the line and begins with "0x"
** no other "word" on that line may begin with "0x"

as of v0.4g the "OpenPGP" header is supported, as defined in
"The OpenPGP mail and news header" <http://josefsson.org/openpgp-header/>.
if the draft gains acceptance, the "X-OpenPGP-KeyID" and "X-OpenPGP-Key-ID"
header support will be deprecated. to make use of this header the qtools
package <http://www.superscript.com/qtools/intro.html> is required.

when signing without a key-ID specified in the headers, or
encrypting, these filters will determine what key to use
based on the email address. as an example, let's say my
address (and key UID) is <foo@bar> and i'm subscribed to
the "xyz" mailing list with an address <foo-xyz@bar>.
these scripts will let me know if they can't find a private
(signing) key for <foo-xyz@bar> and ask if i'd like to use
the key of <foo@bar> instead.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!! headers are NOT encrypted!! if you specify a key id in the email header !!
!! it will be clearly visible to anyone sniffing your mail!!               !!
!! this is a concern for anyone attempting to avoid traffic analysis!!     !!
!! if you aren't concerned by leaving your email address in the header     !!
!! then this shouldn't matter.                                             !!
!! if you're concerned about traffic analysis you probably shouldn't be    !!
!! using pine                                                              !!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* KNOWN ISSUES

* BCC recipients of encrypted messages will still have their key info
in the OpenPGP encrypted message. if you send a message "To" Bob
and "BCC" Alice, Bob can detect that the message was encrypted to
Alice.

* pine only works well with inline pgp messages. pgp/mime and
attached signatures are not handled by pine.

* if your gpg.conf file specifies "verbose" more than once, gpg
may spit out diagnostic information into the body of the message.
this has been called a "classic feature" which may (or may not) be
fixed in or after gpg 1.4.x

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* MISC

i think that's all the docs i've got for now.
everything else ~should~ be self-explanatory...

if a few people ask the same question, it will be clarified
in the next version of the documentation.

for extra credit, send in more verbose and better organized
documentation!

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* HISTORY

v0.3d	* first public release
v0.3e	* fixed the install script - it failed on OS-X
v0.3f	* small improvements to the user interface
v0.3g	* if text exists above and/or below the PGP headers that text will
	  be displayed. previous versions suppressed all text outside of
	  the PGP headers. this is done in a way that should avoid confusion
	  of which text is part of PGP and which text is not.
	* added a history to the README
v0.4a	* some messages were not displayed properly in v0.3g.
	* changed the way that ez-pine-gpg-incoming displays signed messages.
	* some cosmetic changes to ez-pine-gpg-incoming.
v0.4b	* correct the way that dash-escaped text is displayed.
v0.4c	* if an incoming message is signed and encrypted, but the signature
	  fails, you still want to see the decrypted message. right?
v0.4d	* cleaner display of information. more information displayed before
	  being asked for a decryption passphrase: among other things, this
	  gives information about symmetrically encrypted messages; or if
	  the message is asymmetrically encrypted, it will display who else
	  (or what keys) the message is encrypted to.
v0.4e	* better display of information if an encryption key is not found or
	  not usable.
v0.4f	* compensates for an un-acknowledged display bug in pine.
	* UI updates to help protect users from themselves.
v0.4g	* add a blank line between message body and signature.
	* allow signing to recognize key-id from OpenPGP header, as described
	  in "The OpenPGP mail and news header" <http://josefsson.org/openpgp-header/>
	* add "ez-pine-gpg-symmetric" for encrypting to symmetric keys
	* better recognition of whether an incoming message is textmode or armored
v0.4h	* tighten up the screen refresh
	* tighten up the blank line between the end of a message and inline signature

-- EOF
