
                              PREMAIL README FILE
                                       

README file for premail v. 0.33
21 Apr 1994 -- Raph Levien <raph@cs.berkeley.edu>

   Premail is a mail client for Unix workstations, supporting PGP
encryption and anonymous remailers. It can be used either stand-alone
or as a layer under your favorite user mail client. You will need perl
in order to use premail.

   Premail has been designed to be as simple and transparent as
possible. Features include:

* Chaining of messages for cypherpunk remailers.

* Automatic selection of reliable remailers.

* PGP encryption and signing.

* Online and offline operation.

* Aliases.

   Premail is designed to masquerade as sendmail. It accepts mail in
the same way, and takes the the same options, and providing additional
header fields for its privacy features. Thus, if you can get your mail
client to pass the mail to premail rather than sendmail, then you gain
the use of the privacy features without changing the way you send
mail.

   In the interest of simplicity, premail only handles outgoing mail.
It does not handle incoming mail, or PGP decryption.


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

   This section explains how to set up premail for basic operation,
without PGP encryption. Use of PGP encryption is highly encouraged,
and is covered in a later section, as are configuration and advanced
features. This section assumes that your machine is connected to the
net when you run premail. It is capable of offline operation as well,
as discussed in a later section.

1. Get the source. Given that you are reading this file, you may have
already done this; if so, go to step 3. The latest version of premail
is available at:

   ftp://ftp.csua.berkeley.edu/pub/cypherpunks/premail/premail-0.33a.tar.gz

2. Unpack it. To do this, run:

   gzip -dc premail-0.33a.tar.gz | tar xvf -

3. See if you can run it. First, do "cd premail", then "./premail"
(without the "" marks in both cases). If it prints a usage summary,
you are in luck. If you get "command not found," then the problem is
most likely that your system's copy of perl does not live in /usr/bin.
Type "which perl" to find out where it actually is, then edit the
first line of the file "premail" to match that, and try again.

4. Copy premail into a directory in your path (this step is optional).
For example, if ~/bin is in your path, then do:

   cp premail ~/bin

   After this step, you probably want to run "rehash" so your shell
knows were to find premail.

5. Set up the premail configuration file by typing:

   cp .premailrc ~

6. Test whether premail really works, by typing:

   premail your@own.email.addr
   Chain: 1
   Subject: Test

   Does this really work?
   .

   If everything goes well, you should get a response from an
anonymous remailer in a few minutes. Then, premail is set up and ready
to use. You probably want to set up PGP as well, but you don't have
to. This and other configuration options are covered below. The
configuration options are controlled by the ~/.premailrc file, so you
might want to browse through it and tweak things to your taste.


Setting up premail for PGP
--------------------------

   When properly set up, premail will automatically encrypt outgoing
mail using PGP. This applies both to traffic routed through the
remailers, and to email encrypted for the final recipient, who would
use PGP to decrypt it. On the other hand, you can skip this section if
you don't want that.

   First, you need to make sure that you have PGP set up on your
machine. When you do, just type:

   premail -getkeys

   This will finger my remailer pgp key list at
pgpkeys@kiwi.cs.berkeley.edu . If this site is down, or if you are not
connected to the net, you should get the list from somewhere else. You
can specify either an email address to finger or a file. For example,
if you save the keys into remailkeys.asc, then you can run:

   premail -getkeys remailerkeys

   The messages from PGP will tell you that it's adding about a dozen
new keys to the keyring. You'll probably want to premail -getkeys
fairly frequently, say once a week, because (at least at the time of
this writing) new remailers are constantly being installed. If you
attempt to send to one, but you don't have the key, the mail will
bounce.

   You also need to tell premail that you've got PGP running, and have
added the remailer keys to your keyring. To do so, add the following
line to the ~/.premailrc file:

   $config{"encrypt"} = "yes";

   Also, if you've got PGP in a non-standard place, so that typing
"pgp" will not call it up, then you need to add this line to the
~/.premailrc file:

   $config{"pgp"} = "/wherever/you/put/pgp";

   Then, you want to test sending a message to yourself. It will
probably help to try PGP on its own first. PGP will ask you for a
bunch of random keys the first time you use it. It is essential to go
through this _before_ running premail. First, generate a keypair for
yourself:

   pgp -kg

Then, encrypt a random file:

   pgp -e a-random-file your-user-id

When this is done, send mail to yourself:

   premail your@own.email.addr
   Subject: test of PGP premail
   Chain: 1

   Testing...
   .

You can also try sending PGP encrypted mail to yourself:

   premail your@own.email.addr
   Subject: test of PGP encryption
   Key:

   Good luck reading this message :-)
   .


Integration with user mail clients
----------------------------------

   Without premail, outgoing mail works as follows. After you compose
your mail, your mail client hands it off to a program called sendmail,
which forwards it to the Net. Sendmail (written by Eric Allman at UC
Berkeley) knows a lot about email addresses, networking, and so on,
but very little about privacy and security. That's the job of premail.

   It is possible to use premail in two modes: under your client, or
by itself. Either way will give the same features, it's just that
integrating it with your client will be more convenient to use (if a
bit harder to set up). To use premail, type:

   premail recipient@email.addr

and enter your mail as you normally would, ending with either
Control-D or a line with just a . on it. Or, you can prepare an email
message with your favorite editor, and send it with

   premail -t < your.file


Integrating premail with Emacs
------------------------------

   To add premail support to emacs, just add this line to your .emacs
file:

(setq sendmail-program "/your/path/to/premail")


Integrating premail with MH
---------------------------

   In whatever directory you keep the premail executable, create a
symbolic like as follows:

   ln -s premail prepost

   Under the name "prepost", premail will masquerade as MH's post
program rather than sendmail. You can get MH to call premail instead
of post by adding this line to your .mh_profile:

postproc: /your/path/to/prepost

   One thing to keep in mind is that premail's processing is done
before that of post. Thus, if you have MH aliases, they will get
expanded after the call to premail. If you use only premail aliases,
only MH aliases, or neither, this won't be a problem.

   Alternatively, if you have appropriate privileges, you can add this
line to /usr/lib/mh/mtstailor:

sendmail: /your/path/to/premail

   You may also have to configure MH to call sendmail locally rather
than connecting to an SMTP server. Don't do both the mtstailor and
mh_profile methods -- that would run premail twice.


Installing premail with UCBmail
-------------------------------

   UCBmail is a simple mailer front-end (also known as Mail and
mailx). If, when you type "mail user@site.dom", the mailer asks you
for a "Subject: " line, you are undoubtedly using UCBmail. If so, you
are in luck -- it integrates very easily with premail. Just add this
line to your ~/.mailrc file:

set sendmail=/your/path/to/premail

   Using premail with UCBmail is not very different from using premail
by itself, but you do get some extra features, such as being able to
edit the mail, and including files.


Installing premail with other mailers
-------------------------------------

   Unfortunately, most mailers are built so that the path to sendmail
is not user-configurable. If you have appropriate permissions, you can
recompile the programs, but that's pretty painful. Still, if you're
game, Sameer Parekh (sameer@c2.org) has patches to Pine and Elm.
   When premail gets fairly stable, I'm going to try to get the people
who maintain the mailers to make it easier to integrate them with
premail. A little lobbying from the user community couldn't hurt!
Until then, you'll just have to use premail in stand-alone mode.


Installing premail as the default sendmail
------------------------------------------

   If you are root on your machine, you can install premail in
/usr/lib/sendmail, so that it will work for _all_ mail clients. This
is a fairly bold move, so it would be wise to test this carefully
before doing so. To do so, move the existing sendmail into, say,
/usr/lib/real_sendmail . Then, add the line

   $config{"sendmail"} = "/usr/lib/real_sendmail";

to premail, inside the body of the code, where other config options
are set, so that it does not depend on user .premailrc files. Finally,
copy premail to /usr/lib/sendmail. If you choose to do this, let me
know how well it works out.


Using the privacy features
--------------------------

   Premail has two important privacy features: chaining through
remailers, and PGP encrypting the messages.

   To chain through the remailers, simply add a header line such as

   Chain: 3

to your mail. The number 3 says how many remailers you want it to
chain through. Three is a good compromise between privacy on the one
hand and speed and reliablilty on the other. The remailers will
automatically be selected for their reliablity and speed, using the
remailer list I maintain (finger remailer-list@kiwi.cs.berkeley.edu to
see it).

   If you want to specify a particular sequence of remailers, you can
do that. For example, if you are very fond of the idea of your mail
crossing national boundaries, you might want to send it through
Canada, Austria, and Holland, in that order:

   Chain: extropia;wien;usura

   When using the Chain field, your identity will be completely
obscured. If the recipient tries to reply to your mail, it will get
nowhere. You can specify a reply address using the Anon-From field:

   Anon-From: an123456@vox.xs4all.nl

   The Anon-From field only shows up in mail which goes through the
remailers. In ordinary mail, it will be ignored. So, you can put it in
all of your mail without worrying about compromising your identity. In
fact, you can make premail automatically use it in all anonymous mail
by adding this line to your ~/.premailrc file:

   $config{"anon-from"} = "an123456@vox.xs4all.nl";

   Similarly, if most of the mail you send will be through the
remailers, then you can set premail to do that as the default. Add
this line (or whatever path you want, if not 3) to ~/.premailrc:

   $config{"defaultpath"} = "3";

   Then, whenever you want to send non-anonymous mail, add this header
field:

   Chain: ;


   The other important privacy feature is the ability to PGP encrypt
outgoing mail. This works whether or not you use the remailers. The
recipient's key must be in your public key ring before you can encrypt
mail to them. Then, all you have to do is add this mail header field:

   Key: user_id

   The mail will be encrypted with this user_id. It will be formatted
using the MIME content type of application/x-pgp. If the recipient has
a MIME-capable mail reader, they can set it up to automatically call
PGP when receiving encrypted mail. Otherwise, you don't need to worry
about it. If the message is itself MIME encoded, then premail will do
the right thing with it, according to the draft RFC on PGP/MIME
integration. This is great for sending encrypted pictures, sounds, and
so on.

   You can also have premail automatically sign your mail, as well.
This feature is a potential security problem, so use it with caution.
Add these lines to your ~/.premailrc:

   $config{"signuser"} = "your_user_id";
   $config{"signpass"} = "your pass phrase";

   Again, a warning: in doing so, you have just stored your pass
phrase in a disk file, which is considered a security no-no. On the
other hand, if you are using this for medium-security applications, or
if you have good control over access to your machine, then it should
be OK; certainly a _lot_ better than not using PGP at all. The
~/.premailrc file should always have -rw------- (600) permissions. Use
with caution.


How to use the cypherpunks remailers as you would anon.penet.fi
---------------------------------------------------------------

[NOTE: at the time of this writing (6 Nov 1994), anon@vox.xs4all.nl
was not giving out new aliases. This situation is supposed to be
temporary. I believe you can still send mail to ping@desert.xs4all.nl
and get an alias from that mailer.]

   Even though the cypherpunks remailers do essentially the same
things as anon.penet.fi (though faster and with better privacy), they
work quite a bit differently, and can be somewhat intimidating.
Premail can help.

   First, you will need to get an anonymous alias. At this time, the
only cypherpunk remailer which will do this for you is "avox", or
anon@vox.xs4all.nl. To get the alias, do:

   premail your@own.email.addr
   Subject: alias
   Chain: avox

   Hopefully, this will assign me an alias.
   .

   You can also receive an alias by mailing a blank message to
ping@vox.xs4all.nl . Either way, in a few hours, you will get email
back with an alias of the form an123456@vox.xs4all.nl .

   Then, when you send anonymous email, give your alias as the reply
address. Here is an example:

   premail recipient@email.addr
   Anon-From: an123456@vox.xs4all.nl
   Chain: 3

   Hello, if you reply to this, mail will get to me.
   .

   Unfortunately, unlike penet, avox does _not_ make the person
replying anonymous. The best way for them to be anonymous is to use
the cypherpunks mailers as well (hopefully by using premail!).


How to post to Usenet
---------------------

   Premail now supports direct anonymous posting to Usenet. Simply
mail your post to the newsgroup name, as follows:

   premail alt.privacy.anon-server
   Chain: 1
   Subject: premail is great

   Just letting everyone know they should be using it.
   .

   Another way is to use a mail-to-Usenet gateway. For example, to
post to alt.skydiving, just send mail to alt.skydiving@demon.co.uk . A
full list is available by fingering remailer.help.all@chaos.bsu.edu,
or from http://www.cs.berkeley.edu/~raph/ghio-remailer-list.html .


Extra goodies
-------------

   Premail supports a few more features, for advanced users. These
include: offline mail preparation, logging, a password for penet, and
a debugging mode. You can also specify the degree of randomization in
choosing chains of remailers. The configuration options specifying
these are described in the ~/.premailrc file, which is what you would
need to edit. Have fun!


Advanced feature: aliases
-------------------------

   Skip this if you're feeling intimidated. Aliases are an optional
feature to make private mail more convenient, but are not strictly
necessary.
   With premail, there are three main reasons for using aliases.

   1. Permanently attaching PGP keys to certain email addresses.

   2. Creating mailing lists.

   3. Saving typing on long email addresses.

   Adding aliases is fairly straightforward. Add a line

alias: expansion

to your .premailrc file. The expansion is a comma-separated list of
recipients. Each recipient can have premail options attached to it,
such as ^key or ^chain=3 , etc. When using more than one option at a
time, just stick them together, separating the options with carets (^)
and not commas. For examle, to send encrypted and anonymous mail to
spy@nsa.gov, use spy@nsa.gov^key^chain=3 .


Aliases: Attaching PGP keys to email addresses
----------------------------------------------

   This is the main thing I use aliases for, and the real reason I
wrote them. The best thing about using aliases is that it is much
harder to just forget to encrypt. Here are a few relevant lines from
my .premailrc file:

raph: ^key
raph@cs.berkeley.edu: ^key
raph@kiwi.cs.berkeley.edu: ^key=raph@cs.berkeley.edu

   The idea here is that, for each of the email addresses that I might
use, there is an entry. The ^key expansion says to just use the email
address as the PGP key. On the third line, since the email address
doesn't match the PGP key, the key is specified directly.

   One danger is that, if you use an email address which is not on the
list, then the encryption won't happen.


Aliases: Setting up a mailing list
----------------------------------

   Aliases are a quick and dirty way to set up a mailing list. Here's
a typical .premailrc entry:

conspirators: tom@a.com, dick@b.edu^key, harry@c.org

   Then, mail sent to conspirators will go to all three addresses.
Further, mail to dick will be encrypted, using his email address as
the PGP key.
   One good (or bad) thing about using premail aliases as a mailing
list is that each message is sent separately. There is no way for the
recipients to find out who else is on the mailing list, or even that
the message was sent to a mailing list instead of individually.


Aliases: Saving typing
----------------------

   Suppose you frequently post anonymously to
alt.swedish.chef.bork.bork.bork . You would invoke premail as follows:

premail alt.swedish.chef.bork.bork.bork@demon.co.uk
Chain: 3
Subject: bread recipe

and another cup of flour, and another cup of flour, and another cup of
flour, and another cup of flour...
.

   Well, that's a fair amount of typing, which can be saved by adding
this line to your .premailrc

ascbbb: alt.swedish.chef.bork.bork.bork@demon.co.uk^chain=3

   Then, you can post by typing

premail ascbbb
Subject: bread recipe

and yet another cup of flour...
.
