/ 
Mail-IspMailGate-1.1013
River stage zero No dependents
/ Mail::IspMailGate::Filter::PGP

NAME

Mail::IspMailGate::Filter::PGP - Encrypt and decrypt mails with PGP

SYNOPSIS

# Create a filter object
my($scanner) = Mail::IspMailGate::Filter::VirScan->new({
    'uid' => 'Jochen Wiedmann <joe@ispsoft.de>'
});

# Call it for filtering the MIME entity $entity and pass it a
# Mail::IspMailGate::Parser object $parser
my($result) = $scanner->doFilter({
    'entity' => $entity,
    'parser' => $parser
    });
if ($result) { die "Error: $result"; }

VERSION AND VOLATILITY

$Revision 1.0 $
$Date 1998/04/05 18:46:12 $

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 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.

INSTALLATION AND CUSTOMIZATION

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.

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 pubring.pgp, secring.pgp and randseed.bin to the .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:

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.

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>
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!

Configuring the PGP module

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

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

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

$PGP_UID = 'FooBar Inc. <info@foobar.com>';
$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:

$PGP_UIDS = {
    'FooBar Inc. <info@foobar.com>' => 'foobar'
};
$cfg->{'pgp'}->{'encrypt_command'}

A command template for encrypting messages. Example:

$cfg->{'pgp'}->{'encrypt_command'} =
    '/usr/bin/pgp -fea $uid +verbose=0';

Note the use of single quotes to prevent expansion of the variable $uid. This variable will be expanded my the MIME::Decoder module.

$cfg->{'pgp'}->{'decrypt_command'}

Likewise for decryption. Example:

$cfg->{'pgp'}->{'decrypt_command'} =
    '/usr/bin/pgp -f +verbose=0';

You might miss a variable $pass or something sililar here, as decryption requires a pass phrase. Pgp has no command line option for setting the pass phrase (Security reasons, might be visible in ps output), but it accepts an environment variable PGPPASS. This variable gets set automatically.

Creating filter rules

Recall the situation from above. We have the FooBar headquarters and the department in Stuttgart. The headquarter might use the following rule for encrypting mails to the department:

  { 'recipients' => '\\@stuttgart.foobar.com^',
    'filters' => [ Mail::IspMailGate::Filter::PGP->new({
	'uid' => 'FooBar Inc., Department Stuttgart'
	    . ' <info@stuttgart.foobar.com>',
        'direction' => 'pos'
	}) ]
  },
  { 'recipients' => '\\@stuttgart.foobar.com^',
    'filters' => [ Mail::IspMailGate::Filter::PGP->new({
        'direction' => 'neg'
	}) ]
  }

Likewise the following might be used at the department of Stuttgart:

  { 'recipients' => '\\@hq.foobar.com^',
    'filters' => [ Mail::IspMailGate::Filter::PGP->new({
	'uid' => 'FooBar Inc. <info@foobar.com>',
        'direction' => 'pos'
	}) ]
  },
  { 'recipients' => '\\@hq.foobar.com^',
    'filters' => [ Mail::IspMailGate::Filter::PGP->new({
        'direction' => 'neg'
	}) ]
  }

If you use multiple filters (for example the PGP filter might well be used together with a compressing filter), note the following:

When encrypting a mail, the PGP filter *must* always be the last filter, because what the filter does is mainly choosing a certain type for the content-transfer-encoding. On the other hand, the PGP filter must be the first one, when decrypting a mail. Thus the headquarters setup for both compressing and decrypting mails from the headquarter to the department in Stuttgart and vice versa might look like this:

  { 'recipients' => '\\@stuttgart.foobar.com^',
    'filters' => [
        Mail::IspMailGate::Filter::Packer->new({
	    'packer' => 'gzip',
	    'direction' => 'pos'
            }),
        Mail::IspMailGate::Filter::PGP->new({
	    'uid' => 'FooBar Inc., Department Stuttgart'
	         . ' <info@stuttgart.foobar.com>',
            'direction' => 'pos'
	    })
        ]
  },
  { 'recipients' => '\\@stuttgart.foobar.com^',
    'filters' => [
        Mail::IspMailGate::Filter::PGP->new({
	    'uid' => 'FooBar Inc., Department Stuttgart'
	         . ' <info@stuttgart.foobar.com>',
            'direction' => 'neg'
	    })
        Mail::IspMailGate::Filter::Packer->new({
	    'packer' => 'gzip',
	    'direction' => 'neg'
            })
        ]
  }

SEE ALSO

ispMailGate, Mail::IspMailGate::Filter