===============
==  PinePgp  ==
===============

PinePgp 0.18.0


Description
-----------

PinePgp is set of display and sending filters which enables pine to send and
receive signed and/or encrypted e-mails.

Supported are both PGP <http://www.pgp.com/> (version 2.6.x, 5.x and 6.5.x)
and GnuPG <http://www.gnupg.org/> (version 1.0.0 and later).


Copying
-------

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

See the COPYING file or GNU General Public License page
<http://www.gnu.org/copyleft/gpl.html> for license information.

Copyright 1998,.. by Peter Soos <sp@osb.hu> and others. All rights reserved.


Requirements
------------

mktemp:	If installed, it is used to handle temp file used to store gpg/pgp
	output when checking/decrypting incomming message so proper footer
	can be created. If you do not want to install this utility, you can
	still use PinePGP, but use --without-mktemp when running configure.

	For more information about mktemp see <http://www.openbsd.org> .
	Sources can be downloaded from
	<ftp://ftp.openbsd.org/pub/OpenBSD/src/usr.bin/mktemp/> or from
	mirrors <http://www.openbsd.org/ftp.html>.
	RPM package of mktemp can be foud for example at
	<http://rufus.w3.org/linux/RPM/mktemp.html>.


Download
--------

You can find sources at:

	http://www.megaloman.com/~hany/_data/pinepgp/
	http://terminus.sk/~hany/_data/pinepgp/

Also you can download RPM packages from:

	http://www.megaloman.com/~hany/RPM/pinepgp.html
	http://www.megaloman.com/~hany/RPM/pinepgp26x.html
	http://www.megaloman.com/~hany/RPM/pinepgp5x.html
	http://www.megaloman.com/~hany/RPM/pinepgp65x.html
	http://www.megaloman.com/~hany/RPM/pinegpg.html


To verify files, use my public key from
<http://www.megaloman.com/~hany/gnupg-hany-public-key.txt>,
<http://terminus.sk/~hany/gnupg-hany-public-key.txt> or
from public keyservers (for example wwwkeys.eu.pgp.net):

pub  1024D/01F72129 2001-08-03 Peter Hanecak (Hany) <hany@megaloman.sk>
     Key fingerprint = 432F 1A38 8126 9B52 8AAE  8681 705B 82EF 01F7 2129
uid                            Peter Hanecak (Hany) <hany@terminus.sk>
uid                            Peter Hanecak (Hany) <hanecak@megaloman.sk>
sub  2048g/FAF03B1C 2001-08-03 [expires: 2003-08-03]


Releases 0.16.0 and earlier are signed with my older and now expired key:

pub  1024D/1664445A 1999-09-08 Peter Hanecak (Hany) <hany@terminus.sk>
     Key fingerprint = 84F1 078F B502 3C80 2B6E  23E6 F536 2F64 1664 445A
uid                            Peter Hanecak (Hany) <hanecak@megaloman.sk>
uid                            Peter Hanecak (Hany) <hany@megaloman.sk>
sub  2048g/1BC5CE1A 1999-09-08 [expires: 2001-09-07]


Installation
------------


	Administrator
	-------------


First, you need some UNIX system which have 'sed' and 'awk' alredy installed.
Also 'mktemp' utility is recomended (PinePGP version from 0.12.90 to 0.17.1
requires it, for version 0.17.2 and later it is optional but recomended).

After you have sucessfuly downloaded and unpacked source tarball, do the
following in source directory:

	$ ./configure
	$ make
	$ make install

Before building you can manualy enable support for particular encryption
utility and also specify path to utility with --with-<utility>[=<path>]. For
example you can enable GnuPG support (and let configure found path to binary)
and enable generic PGP 2.6.x support with /usr/bin/pgp using following:

	$ ./configure --with-gpg --with-pgp=/usr/bin/pgp

You can also disable support for particular encryption utility with
--without-<utility>. Example (disabling PGP support):

	$ ./configure --without-pgp

If you have mktemp installed but do not want PinePGP to use it, you can use
--without-mktemp configure parameter:

	$ ./configure --without-mktemp

If you want to disable partial fix for Naive Sign & Encrypt
(more information can be found at
http://world.std.com/~dtd/sign_encrypt/sign_encrypt7.html),
use --without-nsefix:

	$ ./configure --without-nsefix

For more information on ./configure arguments run:

	$ ./configure --help



	User
	----

After "Administrator" part is completed, users on your system can run either
'pinegpg-install', 'pinepgp5x-install', 'pinepgp65x-install' or
'pinepgp26x-install' to add particular filters into theire own pine
configuration file (~/.pinerc). Example (install GnuPG filters):

	$ pinegpg-install


To enable "encrypt to yourself" feature, specify your e-mail adress as
argument when running install script. Example (install GnuPG filters,
replace joe@earth.org with your own e-mail address):

	$ pinegpg-install joe@earth.org



Usage
-----

	Viewing signed and/or encrypted messages
	----------------------------------------

To view signed and/or encrypted message just selects it from index.

Signed and/or ecrypted parts are displayed following way:

--[PinePGP]--------------------------------------------------[begin]--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XX                                     XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XX   signed and/or encrypted message   XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XX                                     XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
--[PinePGP]-----------------------------------------------------------
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YY encryption backend and/or PinePGP messages YYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
--[PinePGP]----------------------------------------------------[end]--


Example:

--[PinePGP]--------------------------------------------------[begin]--
Hello,

this is signed message from me.

Hany
--[PinePGP]-----------------------------------------------------------
gpg: Signature made Fri 28 Sep 2001 03:00:00 PM CEST using DSA key ID 01F72129
gpg: Good signature from "Peter Hanecak (Hany) <hany@terminus.sk>"
--[PinePGP]----------------------------------------------------[end]--


	Sending signed and/or encrypted messages
	----------------------------------------

To send signed and/or encrypted message just compose it as ussual. Then
press <Ctrl+X> (send message) and select particular filter:

	+ 'unfiltered' for normal message
	+ 'gpg-sign' for signed (by you) message
	+ 'gpg-encrypt"' for encrypted message (you need public key
	  of recipient in your key ring)
	+ 'gpg-sign+encrypt' for signed (by you) and encrypted message
	  (you need public key of recipient in your key ring)



	"encrypt to yourself" feature
	-----------------------------

With this feature enabled, outgoing encrypted messages are encypted also
with you as recipient (using e-mail adress you supplied in configuration or
when running install script) so when you are viewing your outgoing encrypted
messages you are able to actualy decrypt them.


	Pine filters manual configuration
	---------------------------------

If you want to add filters manualy into pine configuration file, than you
have to add following lines (or change current filter definitions) into
it (example will add GnuPG filters):

	# This variable takes a list of programs that message text is piped into
	# after MIME decoding, prior to display.
	display-filters=_LEADING("-----BEGIN PGP MESSAGE-----")_ /usr/bin/gpg-check,\
		_LEADING("-----BEGIN PGP SIGNED MESSAGE-----")_ /usr/bin/gpg-check,

	# This defines a program that message text is piped into before MIME
	# encoding, prior to sending
	sending-filters=/usr/bin/gpg-sign,/usr/bin/gpg-encrypt _RECIPIENTS_,\
		/usr/bin/gpg-sign+encrypt _RECIPIENTS_,


If you want to use filters with "encrypt to yourself" feature, use following
(replace joe@earth.org with your own e-mail adress):

	# This variable takes a list of programs that message text is piped into
	# after MIME decoding, prior to display.
	display-filters=_LEADING("-----BEGIN PGP MESSAGE-----")_ /usr/bin/gpg-check,\
		_LEADING("-----BEGIN PGP SIGNED MESSAGE-----")_ /usr/bin/gpg-check,

	# This defines a program that message text is piped into before MIME
	# encoding, prior to sending
	sending-filters=/usr/bin/gpg-sign,/usr/bin/gpg-encrypt _RECIPIENTS_ joe@earth.org,\
		/usr/bin/gpg-sign+encrypt _RECIPIENTS_ joe@earth.org,


Your own pine configuration file is ussualy ~/.pinerc . System wide
configuration file should be in /etc/pine.conf but that depends on type of
your system.


	Pine's compose-send-offers-first-filter
	---------------------------------------

Setting this feature will cause the first filter in the sending-filters list
(in case of default PinePGP install it is 'sign' filter) to be offered
as the default instead of unfiltered, the usual default.


For aditional information on cryptography consult Pine, GnuPG and/or PGP
documentation.


	Pine filters temp directory
	---------------------------

PinePGP filters are using ~/.pinpgp directory for placing temporary files.
Install script automaticaly creates this directory for you if it does not
exists (with 0700 access permissions).


How to contribute
-----------------

If you would like to submit a patch, send it to me <hanecak@megaloman.sk>
or to any other author. Please be sure to include a textual explanation of
what your patch does.

The preferred format for changes is 'diff -u' output. You can generate it
like this:

	$ diff -urN pinepgp-orig pinepgp-work > mydiffs.patch



Other Resources
---------------

	About PinePGP
	-------------

+ Using GnuPG with Pine for Secure E-Mail:
  Good introduction to e-mail encryption using PinePGP with GnuPG.
  <http://www.linuxsecurity.com/feature_stories/feature_story-83.html>


	Other e-mail encryption tools
	-----------------------------

+ Pine Privacy Guard:
  Small perl script to interface Pine and GnuPG for the secure
  exchange of e-mail.
  <http://quantumlab.net/pine_privacy_guard/>


TODO
----

+ some other package formats to support more distributions
+ take a look at http://slashdot.org/comments.pl?sid=01/01/09/2117217&cid=144
  and http://sourceforge.net/projects/janitor/ and figure out whether we can
  include S/MIME x.509 support
+ Ed Vazquez, Jr. <evazquez@inflow.com>: For those of us with multiple
  signatures, some way to select a signature
  on sign/encrypt would be nice.

  Ideal would be the ability to define a default signature, but have the
  option to change on send.
+ Ryan W. Maple <ryan@guardiandigital.com>: add something like
  "From: XXX\nTo: XXX\n..." at the end of signed+encrypted and encrypted
  messages to address problems described in
  http://world.std.com/~dtd/sign_encrypt/sign_encrypt7.html


Authors
-------

Peter Soos <sp@osb.hu>
Peter Hanecak <hanecak@megaloman.sk>
Martin Edas Edlman <edlman@dzungle.ms.mff.cuni.cz>


Contributors
------------

Jon Wilson <jon@netsw.co.uk>
Scott C. Wood <woody@netsw.co.uk>
phuzzie <phuzzie@phuzzielogik.cx>
Magnus B{ckstr|m <b@etek.chalmers.se>
Tim Bishop <T.D.Bishop@ukc.ac.uk>
Rolando Abarca <rabarca@ing.uchile.cl>
Matt Brubeck <mbrubeck@hmc.edu>
Ryan W. Maple <ryan@guardiandigital.com>
Dale Bewley <dale@bewley.net>

Thank you.


Maintainer
----------

Current maintainer is Peter Hanecak <hanecak@megaloman.sk> .
