#!/usr/pkg/bin/perl -w
#
#  pgpenvelope
#    - basic call to pgpenvelope
#
#  Copyright (C) 2000 Frank J. Tobin <ftobin@uiuc.edu>
#
#  This file is part of pgpenvelope
#
#  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, visit the following URL:
#  http://www.gnu.org/copyleft/gpl.html
#
#  $Id: pgpenvelope,v 1.13 2001/05/07 23:39:29 ftobin Exp $
#

use strict;
use English;

use PGPEnvelope::Common;
use PGPEnvelope::Config;

my $config = PGPEnvelope::Config->new();
$config->getopt( \@ARGV );

my $homedir = $config->get( 'homedir' );
PGPEnvelope::Common->check_and_create_dir( $homedir );

my $version = PGPEnvelope::Common->version;

my $copyright_line = "pgpenvelope $version, Copyright (C) 2001 Frank Tobin";

if ( $config->get( 'version' ) )
{
    print $copyright_line, "\n";
    exit 0;
}

print <<EOF;
$copyright_line
pgpenvelope comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under certain conditions as described in the GNU General Public License.

pgpenvelope at this time does not use this executable. Please consult
the manpage for pgpenvelope for details on how to set it up for Pine.
EOF

exit 0;

__END__


####################################################################

=head1 NAME

pgpenvelope - Filter for Pine to handle GnuPG operations

=head1 DESCRIPTION

The purpose of B<pgpenvelope> is to allow easy use of GnuPG to 
encrypt/sign/decrypt/verify messages using
Pine's sending/displaying filters.

=head1 USAGE

Simply make the appropriate filter entries in one's Pine configuration,
and run Pine as normal.  When sending mail, choose the
B<pgpenvelope_encrypt> filter.  Additionally, one can
use it as a procmail filter, as described below.


=head2 Pine configuration

These settings should be made in the Pine configuration menu.
To access this, from the main menu, select Setup, then Config.

    display-filters =
      _BEGINNING("-----BEGIN PGP ")_ (path_to)/pgpenvelope_decrypt


    sending-filters =
      (path_to)/pgpenvelope_encrypt _RECIPIENTS_

Please note that each filter is one full line,
and there are spaces between any words which are at the
end of one line and the beginning of the next.
Make sure you include the space at the end of "-----BEGIN PGP ", or else
you might get into infinite loops with Pine.
Also make sure you substitute (path_to) with the
absolute path to the B<pgpenvelope> executable.
Make sure you remove the parentheses, and have a space
between B<pgpenvelope_encrypt> and B<_RECIPIENTS_>.

For instance, one could the following for a sending-filter:

C</usr/local/bin/pgpenvelope_encrypt _RECIPIENTS_>


=head2 Procmail configuration

Put the following lines near or at the top of your F<$HOME/.procmailrc>.


    :0 BDc
    * ^-----BEGIN PGP
    pgpenvelope-backup
     
    :0 bfw
    | (path_to)/pgpenvelope_decrypt --filter


Again, make sure you substitute (path_to) with the
absolute path to the B<pgpenvelope> executable.
These lines will store a backup
of signed messages into the mailbox signed-backup, in
addition to verifying a signed message.
Having these lines lets B<pgpenvelope>
verify signed messages once so you don't
have to everytime you open a signed email.
This filter does not affect encrypted messages.

Your message will be recovered in its original state by B<procmail>
if B<pgpenvelope> or GnuPG fails, but the backup is still handy
for purposes such as forwarding mail to others and allowing them to
verify the message's signature.

=head1 FILES

=over 4

=item F<$HOME/.pgpenvelope/prefs>

=item F<$HOME/.pgpenvelope/prefs.default>

F<prefs> contains your preferences; this is the file read by B<pgpenvelope>.
F<prefs>.default contains documented defaults, and is currently
re-created if a differing version of the defaults file is found from
the running version of pgpenvelope.

=back


=head1 TIPS

Use the B<procmail> bit.  It's quite nice and handy.

If you wish to have B<pgpenvelope_encrypt>
as your default sending filter,
select

    [X] compose-send-offers-first-filter

in one's pine configuration
and have B<pgpenvelope_encrypt> be the first
filter listed in your filter list.

This is not directly related to pgpenvelope, but
if you define a keyserver in F<$HOME/.gnupg/options>
GnuPG will automatically download unidentified keys
when verifying signatures.


=head1 SECURITY NOTES

Both B<pgpenvelope_encrypt> and B<pgpenvelope_encrypt>
use temporary files to be able to pass off large messages to GnuPG
without buffering problems.
The temporary files are created from the call
IO::File->new_tmpfile() (see L<IO::File/new_tmpfile> for details>.
Any temporary files created are zeroed out after use.
Zeroing out files should not be taken as assurance that the
file is not recoverable.

Your passphrase is entered directly into GnuPG, so
there is no need to worry about B<pgpenvelope>
remembering it.

=head1 BUGS

=head2 Pine 4.32

Pine 4.32 has a bug in it where quotes don't work inside
Pine's display-filter setting.  This means that filter
recommended above will not work.  Instead, one should
use:

  _BEGINNING(-----BEGIN)_ (path_to)/pgpenvelope_decrypt

This bug was fixed in Pine 4.33, so upgrading Pine is
another option.

=head1 AUTHOR

Frank J. Tobin <ftobin@uiuc.edu>

=over 4

=item OpenPGP fingerprint:

4F86 3BBB A816 6F0A 340F  6003 56FF D10A 260C 4FA3

=back


=head1 COPYRIGHT

Copyright (C) 2000 Frank J. Tobin <ftobin@uiuc.edu>

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, visit the following URL:
http://www.gnu.org/copyleft/gpl.html

=cut
