#
# GPG4PINE README
#

GPG4PINE by Marcin Marszalek <azzie@staszic.waw.pl> v4.2
========================================================

DESCRIPTION
-----------
Interactive filter that automatically encrypts/decrypts mail under PINE using
PGP. User is not separated from things that GNUPG or PGP does. The program
knows GNUPG 1.0 and PGP versions 2.6.3, 5.0 and 6.5.1. It is highly
configurable and can even optionally remember your passphrase.

FEATURES
--------
* Encrypting and/or signing (ascii armoured) messages before they are sent
* Autodetecting encrypted and signed messages and decrypting before they are
  shown
* User can choose what he/she wants to do with each messege that is to be sent,
  using a quite flexible system (answering to exact questions with possibility
  to set default and "always" answers)
* User is not separated from PGP output
* Support for GNUPG 1.0
* Support for PGP 2.6.3, PGP 5.0, PGP 6.5.1
* Internationalization (en, pl, de, es, it)
* Optional intelligent default ansewer selection
* Optional autodetection of signing key (you can use roles!)
* Support for multiple signing keys
* Password can be stored in memory for one session
* Decrypted messages can be stored on disk for later use for user-specified
  time (including one session time)
* Keyring is spooled for faster operation
* Key-ID aliases
* Encrypted data is separated from not encrypted stuff
* Temporary files are wiped
* Support for signature-rotating programs

INSTALLATION
------------
To install GPG4PINE by Marcin Marszalek <azzie@staszic.waw.pl>

0. Install GNUPG or PGP and verify this package. See also BUGS if you would
   like to apply some patches to PGP :>

1. Untar the inner package (you probably already have done it)

2. (OBSOLETE?) If you need/want compile the getpass program, but it seems that
   it is not necessary since stty should work well (doesn't it?):

gcc getpass.c -o getpass

3a. Copy the file 'gpg4pine' and optionally also 'getpass' to directories you
    want to (if you chose something else than '/usr/local/bin' don't forget
    to change things below) and do the same for manuals in 'docs/'
-OR-
3b. Check the 'Makefile' and type:
   
make install

CONFIGURATION
-------------
1. Edit the 'gpg4pinerc' (probably GPG4PINE_MYADDRESS and some GPG4PINE_BIN_*)

2a. Create the directory '.gpg4pine/' in home directories of users you want and
   set its mode to 700 (drwx------) (recommended), then copy files 'gpg4pinerc'
   and 'aliases' to '~/.gpg4pine' directories, create directories 'tmp/' and
   'spool/' inside and finally copy the whole 'language/' directory if you want
   full internationalization :)
-OR-
2b. If you have source package you can check the 'Makefile' and type:

make user-install

3. If you want, set the default settings putting them to
   /usr/local/etc/gpg4pine.defaults or override any of the user settings in
   /usr/local/etc/gpg4pine.override

4. Configure PINE by
a) adding to 'display-filters' something like:

_LEADING("-----BEGIN PGP")_ /usr/local/bin/gpg4pine -d -i _TMPFILE_ -p _DATAFILE_

b) adding to 'sending-filters' something like:

/usr/local/bin/gpg4pine -e -i _TMPFILE_ -p _DATAFILE_ -r _RECIPIENTS_ _INCLUDEALLHDRS_

c) checking 'compose-send-offers-first-filter' if you want to always send
   using GPG4PINE

5. If you need/want, edit the file '~/.gpg4pine/aliases' (check the example to
   know what is going on)

6. Just play with it

7. Send comments to azzie@staszic.waw.pl (recommended) :)

OPTIONS
-------
Check manual pages located in "docs/"

NOTES
-----
Security points:

* In BIN variables you should type the full path
* Attachments are NOT ENCRYPTED (and this is PINE's developers' fault, not
  mine)

Internationalization points:

* Translated messages are located in 'languages/' directory. If it does not
  contain your native language, translate 'messages.en' and send me the
  result to include it in distribution :) Please, watch out for all those
  '$1's, '$2's and '"'s

Additional points:

* You can remove the p4pXXXX.tmp files from TMP directory if you are not
  using GPG4PINE at the moment or you can set GPG4PINE_RM_STALETMP to do
  it for you
* If PINE says that GPG4PINE returns an error code and you don't know what
  is happening, try running the program manually with given set of options
  (check in PINE's configuration)

Interrupting:

* When you press ^C when gpg4pine processes the encoded mail, you get the
  unprocessed form of it
* When you press ^C when gpg4pine is at any stage of encrypting the message,
  sending of message is cancelled

BUGS
----
If you set GPG4PINE_CHECKPASS option to Y and you use PGP 6.5.1 it may not
work. It is because of strange behaviour of this version of PGP, that may be
caused by its beta stage ;) You may apply a patch "pgp-6.5.1i.batch.patch"
located in 'pgp-patches' directory to try to make it work as expected.

If you want to sign readable with the 5.0 version of PGP and you use 8-bit
characters, you may want to apply the "pgp-5.0i.8bitclean.patch" patch.
Unfortunately I do not remember who gave me the idea how to write this great
patch :(

You can encounter problems working with various versions of PGP, since I no
longer support PGP as primary encoder (what does not mean that I don't support
PGP ;). Please, report such bugs to me immediately, so that I can fix any bugs
and send you a fixed version at once. See also TROUBLESHOOTING.

Spanish translator says, that his translation my contain some
misunderstandings, so if you know both English and Spanish, check the
messages.es and send me some comments, please :)

When sending in a bugreport, please always provide me with the information
about what gpg4pine version, pine version, pgp/gnupg version and bash version
you use, and tell me if you want to receive a prerelease of gpg4pine's next
version that has a bug that you've pointed out fixed (aprox. 15KB).

TROUBLESHOOTING
---------------
Just wondering, do you provide its source code?

 gpg4pine is a bash script, so you can look inside, make some fixes, and send
 me patches ;-)

It says:
--
-n Encrypt?
-n [y/N]
--
What is this -n for? Is it OK?

 No, please check what kind of echo in your system supports -n option, then
 change P4P_ECHO definition at the begining of the gpg4pine script.

It says:
--
I cannot choose a key for user XXX (X elements)
Please define it again [cancel this recipient]
--
No matter what I've typed and I'm sure that it should find a key after
what I've typed, because without any doubt it points to one and exactly one
key. And I have no problem with -n option of echo.

 If you use PGP 6.5.x you should remove 'compatible=on' option from your
 pgp.cfg file if it is placed there.

 Look at the developement/ directory, maybe you can help me to fix it on the
 spot. When sending in a bugreport, additionally to all the most important info
 (see BUGS) send me the output of your standard keylisting command.
 
It says:
--
/usr/local/bin/gpg4pine: [: integer expression expected before -gt
*** End of news
--
What is that?

 It seems that your date command does not support %s formatting field. Change
 P4P_TIME1 and P4P_TIME2 definitions to two commands that as a result return
 the number of seconds since 1970-01-01 00:00:00 UTC (there is an example with
 perl)

This is strange. I am left with several stale gpg4pine processes running. This
is even after I have completed all gpg4pine functions, and even after I have
exited pine.

 Those processes are the passphrase server. They should disappear in 10 seconds
 after you exited pine.
 
TODO
----
* Builtin attachments that would be encrypted but may be incompatible with
  other pgp filters and plugins? Tell what you think :)
* Colors?
* You tell me

THANKS
------
Check the file AUTHORS

LEGAL STUFF
-----------
GPG4PINE was written by Marcin Marszalek <azzie@staszic.waw.pl>. See AUTHORS to
know who helped much. GPG4PINE is a part of "Azzie's tools project" and is
distributed under the terms of AZZIE'S OWN TYPE OF PUBLIC LICENSE. Description
of those terms you should find in this package.

LATEST VERSION
--------------
Always available at
http://azzie.robotics.net

Marcin Marszalek - the author
azzie@staszic.waw.pl

#
# GPG4PINE by Marcin Marszalek <azzie@staszic.waw.pl>
# 27/08/00  version 4.2
#
