view release on metacpan or  search on metacpan

lib/Mail/IspMailGate/Filter/PGP.pm  view on Meta::CPAN

=head1 DESCRIPTION

This class implements an encrypting and decrypting filter based on PGP.
It is derived from the abstract base class Mail::IspMailGate::Filter.
For details of an abstract filter see L<Mail::IspMailGate::Filter>.

The PGP module is based on the MIME::Decoder::PGP module which is
using an external PGP binary. The filter module is designed for
installation on two servers: When sending mail from one server to
the other mails get automatically encrypted on the sending server
and decrypted on the receiving server. Of course both servers need
the IspMailGate package and PGP installed. Installation typically
includes creating an own secret and public key ring which is
specifically dedicated to IspMailGate.

=head1 INSTALLATION AND CUSTOMIZATION

=head2 Patching the MIME-tools

Unfortunately the current version of the MIME-tools (4.116, as of this
writing) has a minor bug that make the MIME::Decoder::PGP module unusable.
This bug was reported to Eryq, the MIME-tools author and will be fixed
in the next release. The patch is quite easy:

  *** /usr/lib/perl5/site_perl/MIME/ParserBase.pm Thu Feb 12 04:11:27 1998
  --- lib/MIME/ParserBase.pm      Thu Apr  9 12:22:44 1998
  ***************
  *** 518,523 ****
  --- 518,524 ----
              $ent->effective_type('application/octet-stream');
              $decoder = new MIME::Decoder 'binary';
          }
  +       $decoder->head($head);
  
          # Obtain a filehandle for reading the encoded information:
          #    We have two different approaches, based on whether or not we

In other words, just use your favourite text editor to edit the file
lib/MIME/ParserBase.pm of the MIME-tools distribution and add the
line marked with a plus sign as line 521. Then reinstall the MIME
modules.

=head2 Creating a key ring

Before starting to use the PGP module, you have to create a public and
private keyring of the ispmailgate user. If you already have an appropriate
keyring, this is done by copying the files C<pubring.pgp>, C<secring.pgp>
and C<randseed.bin> to the C<.pgp> subdirectory of the ispmailgate users
home directory. Note that your personal keyring is not appropriate.
An anonymous user representing your information (an "info" user, for example)
might be more appropriate.

Do not forget to set the file permissions the right way. For example you
might do the following:

    su
    mkdir ~ispmailgate/.pgp
    cp ~info/.pgp/pubring.pgp ~ispmailgate/.pgp
    cp ~info/.pgp/secring.pgp ~ispmailgate/.pgp
    cp ~info/.pgp/randseed.bin ~ispmailgate/.pgp
    chown -R ispmailgate ~ispmailgate/.pgp
    chgrp -R ispmailgate ~ispmailgate/.pgp
    chmod 755 ~ispmailgate/.pgp
    chmod 600 ~ispmailgate/.pgp/*

If you don't have an appropriate keyring, you can instead create a new
one. This is done with the following command:

    su - ispmailgate -c "pgp -kg"

PGP will ask you some questions, for example:

=over 4

=item RSA key size

I recommend using a value of 1024 bit; IspMailGate is not an interactive
application and it doesn't hurt, if encryption and decryption take a little
bit longer.

=item user ID

Choose an appropriate user ID for representing your organization, for
example

    FooBar Inc. <info@foobar.com>

Do not choose the same user ID's and or keyrings on both ends. For
example another user ID might be

    FooBar Inc., Department Stuttgart <info@stuttgart.foobar.com>

=item pass phrase

Enter a random word (you'll be asked to repeat it), note that what you
enter is usually not visible on the terminal. Remember this pass phrase
for later use!

=back

=head2 Configuring the PGP module

Next step is editing the Mail::IspMailGate::Config module. In particular
you have to enter values for the following variables:

=over 4

=item $cfg->{'pgp'}->{'uid'}

This is the default user ID for encrypting emails. (You might override
it with the C<uid> attribute of the Mail::IspMailGate::Filter::PGP
objects, see below.) Example:

    $PGP_UID = 'FooBar Inc. <info@foobar.com>';

=item $cfg->{'pgp'}->{'uids'}

This is a hash ref of user ID's that you want to encrypt automatically.
The hash keys are the user ID's, the hash values are the respective
pass phrases. Example: