  premail documentation
  Raph Levien rraapphh@@ccss..bbeerrkkeelleeyy..eedduu

  This is a draft of the documentation for premail 0.44.

  11..  IInnttrroodduuccttiioonn ttoo pprreemmaaiill

  This is the documentation for version 0.44 of premail, an e-mail
  privacy package by Raph Levien <hhttttpp::////kkiiwwii..ccss..bbeerrkkeelleeyy..eedduu//~~rraapphh//>.

  The main function of premail is adding support for encrypted e-mail to
  your mailer, using plain PGP, PGP/MIME, MOSS, or S/MIME.

  In addition, premail provides a seamless, transparent interface to the
  anonymous remailers, including full support for Mixmaster remailers
  and the nymservers. Nymservers provide cryptographically protected,
  fully anonymous accounts for both sending and receiving e-mail.

  While premail can be used as a stand-alone application, it works best
  when integrated with your mailer. Currently, premail is integrated
  completely seamlessly and transparently only with Netscape 3.0's
  built-in mailer. It works fairly well with Pine 3.94 or later, as well
  (plain PGP is supported, but decryption of MIME-based e-mail
  encryption protocols is still missing). Transparent integration of
  outgoing mail only is supported for any mailer in which the mail
  sending program can be configured, including Berkeley mail, most emacs
  mailers, and MH.  For these mailers, you can decode messages with a
  single command.

  To integrate with your mailer, premail places itself between the
  mailer and the actual mail transport. For outgoing mail, premail
  masquerades as sendmail. You configure your mailer to call premail
  instead of sendmail. Then, premail performs the encryption or signing,
  and invokes sendmail to actually send the message.

  For mailers that call a command to receive incoming mail (including
  Netscape 3.0), the situation is similar. Netscape, for example, can be
  configured to call movemail to get incoming mail. To integrate
  premail, you'd configure Netscape to call premail instead, which would
  in turn call movemail to actually get the mail, then would decode it.

  You need the following software in order to effectively use premail:

  +o  Unix. Unfortunarely, premail does not work on Mac or Windows.

  +o  Perl <hhttttpp::////wwwwww..ppeerrll..ccoomm//ppeerrll//iinnddeexx..hhttmmll> 5.000 or later.

  +o  PGP <hhttttpp::////wweebb..mmiitt..eedduu//nneettwwoorrkk//ppggpp--ffoorrmm..hhttmmll> (version 2.6.2
     recommended).

  +o  RIPEM <ffttpp::////rriippeemm..mmssuu..eedduu//ppuubb//ccrryypptt//rriippeemm//> 3.0b2 or later
     (optional, for S/MIME support)

  +o  TIS/MOSS <hhttttpp::////wwwwww..ttiiss..ccoomm//ddooccss//PPrroodduuccttss//ttiissmmoossss..hhttmmll> 7.1
     (optional, for MOSS support)

  +o  Mixmaster <hhttttpp::////wwwwww..oobbssccuurraa..ccoomm//~~llookkii//> (optional, for higher
     security anonymous mail)

  +o  Lynx <hhttttpp::////wwwwww..uukkaannss..eedduu//aabboouutt__llyynnxx//aabboouutt__llyynnxx..hhttmmll> (only if
     you're behind a firewall)

  22..  IInnssttaallllaattiioonn

  First, you need to get premail. The source code is available from an
  export-control <hhttttpp::////kkiiwwii..ccss..bbeerrkkeelleeyy..eedduu//pprreemmaaiill--ffoorrmm..hhttmmll> Web
  server. You may also be able to find a copy on the Hacktic
  <ffttpp::////ffttpp..hhaacckkttiicc..nnll//ppuubb//rreeppllaayy//ppuubb//rreemmaaiilleerr//> FTP site in the
  Netherlands. In either case, you want to get the file
  pprreemmaaiill--00..4444..ttaarr..ggzz.

  After you've gotten the file, unpack it. This command should do it:

       gzip -dc premail-0.44.tar.gz | tar xvf -

  The unpacking process will create a subdirectory called pprreemmaaiill--00..4444,
  containing the following files:

  +o  RREEAADDMMEE A short description of the contents

  +o  pprreemmaaiill The premail program itself

  +o  pprreeffeerreenncceess A skeletal preferences file

  Test to see if you can run premail. These commands should print a
  usage summary:

       cd premail-0.44

  If you get an error message reading ``command not found,'' then you
  will have to edit the first line of pprreemmaaiill to refer to the actual
  pathname of the perl5 interpreter. One good way to find out the
  pathname is to do ``wwhhiicchh ppeerrll55'' or ``wwhhiicchh ppeerrll''.

  On the other hand, if you get a string of syntax errors, then the
  problem is that you are running perl4, while premail needs perl5. Try
  to see if you can find perl5 on your machine. Otherwise, you may need
  to install perl5 yourself.

  If you will be using premail from the command line frequently, then
  you may want to copy (or symlink) the premail program into a location
  in your $$PPAATTHH. For example, if you have permission to add files into
  //uussrr//llooccaall//bbiinn, then you may consider running this command:

       cp -p premail /usr/local/bin

  At this point, you are ready to test whether premail actually works.
  We are assuming that you already have PGP installed and have generated
  your own public key. Type this command, substituting in your own e-
  mail address:

       To: your@own.email.addr ((encrypt-pgp))
       Subject: Test

       Does this really work?

  If all goes well, you should be back at the command line within a
  couple of seconds. If it seems to hang without any disk or net
  activity, try typing randomly for a minute, under the assumption that
  PGP needs random keystrokes. This shouldn't happen if PGP is already
  set up correctly (including having generated your own public key), but
  on the chance that it isn't, hanging while waiting for random
  keystrokes is one of the more common failure modes.

  This is also the point at which you may get a PGP error. Two common
  problems are that premail can't find the PGP program, in which case
  you will want to add a line to your preferences file (see section
  ``Preferences'' below), or that it can't find the public key
  corresponding to your e-mail address.

  If the test was successful you now have a PGP-encrypted message in
  your mailbox, then you should now have a PGP-encrypted message in your
  mailbox.

  33..  PPrreeffeerreenncceess

  While premail's default configuration is designed to be sufficient for
  the the most common cases, you may want to change some of the
  configuration options. This is done by adding lines to the preferences
  file.

  The default location for the preferences file is
  ~~//..pprreemmaaiill//pprreeffeerreenncceess, where ~~ represents your home directory. The
  premail distribution comes with a skeleton preferences file, but it
  does not automatically copy it into the ~~//..pprreemmaaiill directory. You
  might choose to do that yourself, or you might create one from
  scratch.

  The format of the preferences file is a sequence of lines such as the
  following:

       $config{'option'} = 'value';

  All other lines (including those beginning with ##) are considered to
  be comments and are ignored. Here's a typical preferences file
  (actually, the one on my home machine):

  $config{'logfile'} = '/home/raph/premail/log';
  $config{'debug'} = 'chvl';
  $config{'movemail'} = '/home/raph/bin/movehome';
  $config{'ripem'} = '/home/raph/install/ripem/main/ripem';
  $config{'pgp'} = '/usr/local/bin/pgp';

  As you can see, a major use for the preferences file is to specify
  full pathnames for the helper programs. In addition, I've set it up to
  produce a full log, which I find useful, because I'm constantly
  tracking down bugs :-)

  Here's a table of all the configuration options, their defaults, and a
  very brief description. More complete descriptions are found in the
  preferences file included in the premail distribution.

     ppggpp ((ddeeffaauulltt ppggpp)
        The location of the PGP executable.

     sseennddmmaaiill ((ddeeffaauulltt //uussrr//lliibb//sseennddmmaaiill)
        The location of the sendmail executable.

     mmiixxmmaasstteerr ((ddeeffaauulltt mmiixxmmaasstteerr)
        The location of the Mixmaster executable (useful for more secure
        anonymous mail).

     mmoovveemmaaiill ((ddeeffaauulltt mmoovveemmaaiill)
        The location of the movemail executable (useful for integrating
        Netscape 3.0).

     rriippeemm ((ddeeffaauulltt rriippeemm)
        The location of the ripem executable (needed for S/MIME
        messages).

     mmoossssbbiinn
        The directory containing the TIS/MOSS executables (needed for
        MOSS messages).

     ppoosstt ((ddeeffaauulltt ppoosstt)
        The location of the MH post executable (needed for MH
        integration).

     ggeettuurrll ((ddeeffaauulltt  )
        A command for getting files from the Web. Use ``llyynnxx --ssoouurrccee''
        if behind a firewall.

     ddeeaadd--lleetttteerr ((ddeeffaauulltt ~~//ddeeaadd..lleetttteerr)
        The file where premail stores undeliverable mail.

     llooggffiillee
        The location where premail stores its log, if the ll debug flag
        is set.
     ssttoorreeffiillee
        If set, the location where premail stores outgoing mail, instead
        of calling sendmail.

     ttmmppddiirr ((ddeeffaauulltt //ttmmpp)
        Where premail stores its temporary files.

     cchhaarrsseett ((ddeeffaauulltt iissoo--88885599--11)
        The default charset for outgoing 8-bit messages.

     eennccrryypptt ((ddeeffaauulltt yyeess)
        Set to blank to disable PGP encryption to remailers.

     aacckk
        If set, nymservers will send acknowledgements for all outgoing
        mail.

     eexxttrraabbllaannkk
        If set, premail adds an extra blank on remailer messages. Useful
        if behind a broken mail proxy.

     ddeebbuugg
        Debugging flags (see section ``debugging'').

     ssiiggnnuusseerr
        The user id of the default PGP secret key used to sign messages.

     ddeeffaauulltt--rreeppllyy--ttoo
        Adds a RReeppllyy--TToo:: header field with this address when sending
        anonymous e-mail.

     aaddddrreesssseess ((ddeeffaauulltt ~~//..pprreemmaaiill//aaddddrreesssseess)
        The file containing your addresses.

     rrlliisstt ((ddeeffaauulltt ~~//..pprreemmaaiill//rrlliisstt)
        The file where premail stores the remailer list.

     ppuubbrriinngg ((ddeeffaauulltt ~~//..pprreemmaaiill//ppuubbrriinngg..ppggpp)
        The file where premail stores the public keyring for the
        remailers.

     pprreemmaaiill--sseeccrreettss--ppggpp ((ddeeffaauulltt ~~//..pprreemmaaiill//sseeccrreettss..ppggpp)
        The file where premail stores the encrypted secrets file.

     pprreemmaaiill--sseeccrreettss ((ddeeffaauulltt //ttmmpp//pprreemmaaiill--sseeccrreettss..$$<<)
        The location of your secrets file

     rrlliisstt--uurrll ((ddeeffaauulltt hhttttpp::////kkiiwwii..ccss..bbeerrkkeelleeyy..eedduu//rrlliisstt)
        The URL for the remailer list.

     ppuubbrriinngg--uurrll ((ddeeffaauulltt hhttttpp::////kkiiwwii..ccss..bbeerrkkeelleeyy..eedduu//ppuubbrriinngg..ppggpp)
        The URL for the remailer public keyring.

     ttyyppee22--lliisstt--uurrll ((ddeeffaauulltt hhttttpp::////wwwwww..jjppuunniixx..ccoomm//ttyyppee22..hhttmmll)
        The URL for the Mixmaster type2 list.

     ppuubbrriinngg--mmiixx--uurrll ((ddeeffaauulltt hhttttpp::////wwwwww..jjppuunniixx..ccoomm//ppuubbrriinngg..hhttmmll)
        The URL for the Mixmaster pubring.

  44..  SSeeccrreettss

  To create signatures, decrypt messages, or use nyms, you need to set
  up a ``premail secrets'' file. If you will only be using premail to
  encrypt outgoing mail, you can skip this section.

  The default filename is //ttmmpp//..pprreemmaaiill--sseeccrreettss..$$<< , where $$<< is equal
  to your numeric user id. To change the filename, use a preferences
  line such as this one:

       $config{'premail-secrets'} = '/mnt/cryptdisk/premail-secrets';

  If you don't know your numeric user id, you can find it by running
  ``eecchhoo $$uuiidd'' (from csh or tcsh), ``eecchhoo $$UUIIDD'' (from sh or bash), or:

       perl -e 'print "$<;\n"'

  The premail secrets file has this format:

       $pgppass{'user'} = 'PGP passphrase for user';
       $pgppass{'alternate'} = 'PGP passphrase for alternate';
       $penetpass = 'Passphrase for anon.penet.fi';

  However, make sure your premail secrets file has restrictive
  permissions, so other people on your system can't read your
  passphrases! This command is well recommended (substituting your
  actual user id, of course):

       chmod 600 /tmp/.premail-secrets.7437

  44..11..  LLooggggiinngg iinn aanndd llooggggiinngg oouutt

  Generally, premail stores its secrets file in the //ttmmpp directory. In
  some cases, this is good enough security. In other cases, it might be
  better to store the file encrypted most of the time, and only decrypt
  it when necessary. To use this capability of premail, first set a
  passphrase with:

       premail -setpass

  You will be prompted for a passphrase. You can use the same passphrase
  as for your PGP key, or a different one, depending on how many
  passphrases you want to remember. This command leaves you logged in
  with the new passphrase set.

  Note: the secrets file must already exist before setting the password
  on it. If not, there will be an error message.

  To log out:

       premail -logout

  You might consider adding this command to your .logout file, so that
  it occurs automatically every time you log out of your account.

  To log in again:

       premail -login

  If you are running on a system with X, then premail will automatically
  pop up a window to log in whenever the secrets are needed. If you are
  not running X, and the secrets are needed, you will get an error. In
  this case, you can log in manually and try the command again.

  55..  NNeettssccaappee

  This section describes how to integrate premail into Netscape 3.0's
  built-in mailer. Skip this section if you won't be using Netscape
  mail.

  1. Create symbolic links to premail called ``prezilla'' and
  ``premailmove''. To do this, make sure you are in the same directory
  as premail itself, and type:

  ln -s premail prezilla
  ln -s premail premailmove

  2. Find a working movemail. If you have emacs installed, then you most
  likely have one in /usr/lib/emacs/etc/movemail or a similar location.
  If you don't already have one, then the source (or possibly binary)
  for one is included in the Netscape Navigator distribution and you can
  build it (no need if a binary is included). Then, make sure premail
  can find it by adding a line such as this one to your preferences
  file:

       $config{'movemail'} = '/usr/lib/emacs/etc/movemail';

  This usage assumes that you get your mail from a mail spool, as
  opposed to POP or some such. You may be able to get it to work for POP
  as well, but you need to figure out how to invoke movemail to move the
  mail from your mailbox to a file (specified as the second argument to
  the movemail script).

  3. Add this line to your .cshrc, assuming your shell is csh or tcsh:

       setenv NS_MSG_DELIVERY_HOOK /your/path/to/prezilla

  Also run this command from the shell so it takes effect immediately.
  The syntax is slightly different if your shell is sh or bash _(_n_o_t_e_: _i_s
  _t_h_i_s _r_i_g_h_t_?_):

       NS_MSG_DELIVERY_HOOK=/your/path/to/prezilla
       export NS_MSG_DELIVERY_HOOK

  4. Start Netscape (exit first if it's already running). Go to the
  Options|Mail and News Preferences dialog, select the Servers tab.
  Click on ``External Movemail'' and set the value to
  //yyoouurr//ppaatthh//ttoo//pprreemmaaiillmmoovvee.

  Try sending yourself mail, and clicking on ``Get Mail'' from the
  Netscape Mail window. The mail should show up in the Inbox, correctly
  decoded.

  To view the X-Premail-Auth: header field to see the result of
  signature checking, select Options|Show All Headers from the Netscape
  Mail window.

  Note: as of Netscape v3.0b5, there is still a bug in the handling of
  the BBcccc:: header field, which causes it to be ignored. Do not use this
  field. Hopefully, this will be fixed in a future version of Netscape.

  Note: some 3.0 beta versions modify the PPAATTHH environment variable. If
  premail seems to work correctly from the command line, but not from
  Netscape, try setting absolute pathnames for the programs used by
  premail.

  66..  PPiinnee

  As of Pine 3.94, premail integrates both outgoing mail and the
  decryption of plain PGP incoming mail. Unfortunately, decryption of
  MIME-based mail is not yet supported.

  Two Pine configuration options need to be set to integrate premail
  (i.e. from the main Pine screen, SS for setup, then CC for configure).
  First, sseennddmmaaiill--ppaatthh should be set to a value similar to this
  (substituting the actual path to premail):

       /your/path/to/premail -oem -t -oi

  Second, ddiissppllaayy__ffiilltteerrss should be set to a value similar to this:

       _BEGINNING("-----BEGIN PGP")_ /your/path/to/premail -decode -body

  If you have trouble finding these options in the setup screen, then
  you can edit the .pinerc file directly.

  One caveat when using Pine: it usually tries to be ``smart'' and
  remove comments from e-mail addresses, which includes the double-paren
  commands such as ((((eennccrryypptt--ppggpp)))). There are a few ways to deal with
  this problem:

  +o  Use ""(( ))"" instead of (((( )))). _N_o_t_e_: _I _t_h_i_n_k _t_h_i_s _w_o_r_k_s_, _b_u_t _I _h_a_v_e_n_'_t
     _t_e_s_t_e_d _i_t_.

  +o  Use the alternative caret syntax. These two lines mean the same
     thing:

       To: raph@cs.berkeley.edu ((encrypt-key, sign))
       To: raph@cs.berkeley.edu^encrypt-key^sign

  +o  Avoid setting the encryption options on the command line
     altogether, and set them in the addresses file instead (see section
     ``Address book'' below).

  77..  OOtthheerr mmaaiilleerrss

  This section describes how to integrate premail with MH, emacs, and
  UCBMail. With these mailers, premail will only handle outgoing mail
  automatically. To decode incoming mail, you still need to invoke
  pprreemmaaiill --ddeeccooddee by hand.

  77..11..  IInntteeggrraattiinngg pprreemmaaiill wwiitthh EEmmaaccss

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

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

  77..22..  IInntteeggrraattiinngg pprreemmaaiill wwiitthh MMHH

  In whatever directory you keep the premail executable, create a
  symbolic link 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.
  77..33..  IInnssttaalllliinngg pprreemmaaiill wwiitthh UUCCBBmmaaiill

  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 handy features, such as including files
  and using an editor on the mail.

  88..  CCoommmmaanndd lliinnee

  Hopefully, you have integrated premail into your mail client, and you
  won't have to invoke it from the command line. However, there may
  still be times when it is convenient to use premail from the command
  line.

  The most basic use of premail is as a replacement for sendmail.  For
  example, you can send mail directly from the command line, as follows
  (here, the >> represents the Unix prompt):

       > premail -t
       To: raph@cs.berkeley.edu ((sign))
       Subject: premail bug report

       Here's a bug in premail: ...
       >

  The --tt option specifies that the recipients are extracted from the
  header fields (TToo::, CCcc::, BBcccc::, and the RReesseenntt-- variants of each). As
  in sendmail, you can specify the recipients on the command line
  instead of using the --tt option.

  In addition, you can set configuration options from the command line,
  using the ++ooppttiioonn==vvaalluuee syntax. This is especially useful with the
  debug option (see section ``Debugging''). For example, to show you
  what happens when formatting mail for remailers, but not actually send
  the message:

  > premail +debug=ry -t
  To: raph@cs.berkeley.edu ((chain=1))
  Subject: test of remailer

  test
  Chose chain exon
  /usr/lib/sendmail -oi remailer\@remailer\.nl\.com << -eof-
  To: remailer@remailer.nl.com

  ::
  Encrypted: PGP

  -----BEGIN PGP MESSAGE----- remailer@remailer.nl.com
  ::
  Request-Remailing-To: raph@cs.berkeley.edu

  ##
  Subject: test of remailer

  test
  -----END PGP MESSAGE-----
  -eof-

  There is one configuration option that can only be set from the
  command line in this fashion, which is the location of the preferences
  file itself. The configuration option is pprreeffeerreenncceess, and the default
  value is ~~//..pprreemmaaiill//pprreeffeerreenncceess.

  99..  EEnnccrryyppttiioonn

  Once you've got premail set up, actually using encryption is easy.
  You simply add commands in double parentheses to the e-mail addresses.
  The eennccrryypptt--ppggpp command (which can be abbreviated to kkeeyy) adds
  encryption to the outgoing mail, and the ssiiggnn command signs it.

  For example, to send me encrypted mail, you'd send it to
  rraapphh@@ccss..bbeerrkkeelleeyy..eedduu ((((eennccrryypptt--ppggpp)))). You need to have a key with this
  user id on your PGP public keyring, otherwise you'll get an error
  message. If the user id on the key doesn't match the e-mail address,
  you can specify it directly. For example, to send mail directly to my
  workstation, but using the same public key as above, use
  rraapphh@@kkiiwwii..ccss..bbeerrkkeelleeyy..eedduu ((((kkeeyy==rraapphh@@ccss..bbeerrkkeelleeyy..eedduu)))).

  Signing works much the same way. I can sign mail by adding
  ((((ssiiggnn==rraapphh@@ccss..bbeerrkkeelleeyy..eedduu)))) to the outgoing address.  Actually,
  because I set the ssiiggnnuusseerr configuration option in my preferences
  file, all I have to add is ((((ssiiggnn)))).

  Doing both encryption and signing is just as easy. For example, to
  send me signed, encrypted mail, use this line:

       To: raph@cs.berkeley.edu ((encrypt-pgp, sign))

  Each recipient is treated separately - the double-paren commands after
  an e-mail address apply to that recipient only. However, you can add a
  SSiiggnn:: header field to indicate that your message is signed for all
  recipients. Example:

       To: vp@company, secretary@company, employees@company,
           friend@outside ((encrypt-pgp))
       Subject: Important announcement
       Sign:

  In this example, all recipients will get a signed message, and the
  message to friend@outside will be encrypted as well.

  1100..  DDeeccooddiinngg

  The basic way to decode encrypted messages is to use pprreemmaaiill --ddeeccooddee
  as a command line. You can either give a filename as an argument, or
  premail will accept the encrypted message on its standard input. In
  either case, the decoded message will be printed on the standard
  output.

  The message can be a standard e-mail message (RFC 822 format), or it
  can be an entire mailbox. In the latter case, premail will decode each
  of the messages individually. If you don't have premail directly
  integrated into your mailer, then here's a handy way to view your
  mail:

       premail -decode $MAIL | more

  If the message is actually encrypted, then premail will need to access
  the secrets file. If you are logged out of premail, then premail will
  try to open an xterm window for you to type the passphrase for the
  secrets file. If that doesn't succeed, premail will print an error
  message. At that point, you might choose to log in (i.e. pprreemmaaiill
  --llooggiinn) and then try the decoding again.

  If, as in many mailers, you have easy access to the body of the
  message but not the header, then you can use pprreemmaaiill --ddeeccooddee --bbooddyy on
  the body. This works well for plain PGP encrypted messages, but
  unfortunately does not work for MIME-based message formats, because
  important information is contained in the header.

  The results of the decoding (including signature verification) are
  given in an XX--PPrreemmaaiill--AAuutthh:: header field. This header field is
  protected against forgery; if the original message contains it, it is
  changed to XX--AAtttteemmpptteedd--AAuutthh--FFoorrggeerryy.

  1111..  AAnnoonnyymmiittyy

  The original reason for writing premail was to provide good support
  for anonymous remailers <hhttttpp::////wwwwww..ccss..bbeerrkkeelleeyy..eedduu//~~rraapphh//rreemmaaiilleerr--
  lliisstt..hhttmmll>. If you're not interested in sending anonymous mail, you
  can skip this section.

  Sending anonymous mail is very similar to sending encrypted mail.
  Simply add the ((((cchhaaiinn)))) command to the recipient's e-mail address.
  Alternatively, you can add a CChhaaiinn:: header field, and the mail will be
  send anonymously to all recipients.

  Even though the chain command is simple, a lot is going on under the
  surface. The default chain is 33, which asks that three ``good''
  remailers be chosen randomly. To make sure that it makes its choice
  based on fresh, up-to-date information, premail downloads the remailer
  list and a set of PGP public keys for the remailers from the Web (the
  actual URLs are configuration options). After choosing the remailers,
  the message is multiply encrypted with the PGP public keys, and
  finally sent to the first remailer in the chain.

  The automatic chain selection process is very good. My tests indicate
  that reliability is consistently above 99%. Further, the chain
  selection process avoids some potential problems. For example, some
  remailers are known not to work well in chains, probably because of
  incorrectly configured ``block lists.'' Also, some remailers are
  ``linked,'' in the sense of being hosted on the same machine, or being
  administered by the same person. Choosing a sequence of linked
  remailers wouldn't offer much security, so premail doesn't.

  You can also choose the chain length. A shorter chain will be faster
  and more reliable, but less secure, and conversely for longer chains.
  For example, ((((cchhaaiinn==55)))) selects a chain of five remailers.

  If this isn't enough control, you can specify the exact chain of
  remailers by hand. For example, ((((cchhaaiinn==rreeppllaayy;;jjaamm;;eexxoonn)))) bounces the
  message around a few times outside the US.

  Mixmaster chains are specified inside an additional set of
  parentheses. At the moment, there is no way to automatically select a
  chain of Mixmaster remailers, so you have to do it by hand. For
  example: ((((cchhaaiinn==((rreeppllaayy;;eeccaaffee--mmiixx;;llccss)))))). You can even mix Mixmaster
  and type-1 remailers; for example, ((((cchhaaiinn==((aannoonn));;11;;((rreeppllaayy)))))) will
  sandwich one well-chosen remailer between the two Mixmaster remailers.

  Extra header fields can be placed in the outgoing message by prefixing
  the header with ``AAnnoonn--''. A particularly common usage is an AAnnoonn--
  RReeppllyy--TToo:: field, which specifies a reply-to address in the mail
  delivered to the recipient. The RReeppllyy--TToo:: header field is used often
  enough that premail includes a ddeeffaauulltt--rreeppllyy--ttoo configuration option,
  which automatically adds it to all anonymous messages.

  The following header fields are passed through to the anonymized
  message, even without the AAnnoonn-- prefix:

       Mime-Version:
       Content-Type:
       Content-Transfer-Encoding:
       Newsgroups:
       X-Anon-To:
       In-Reply-To:
       References:

  1122..  UUssiinngg nnyymmss

  This section describes how to create and use _n_y_m_s, which are accounts
  for sending and receiving anonymous mail. The most popular and well
  known nymserver is alpha.c2.org. The FAQ <hhttttpp::////aallpphhaa..cc22..oorrgg//>
  explains how to set up and use nyms by hand, but it's much easier to
  do (and more secure!) with premail.

  To create a new nym, type

       premail -makenym

  and follow the prompts. This command is also good for updating an
  existing nym, which is important if one of the nym's remailers goes
  down.

  You can also create or update a nym from the command line, as follows:

       premail -makenym you@alpha.c2.org your@real.email.address

  When premail creates a nym, it chooses random passphrases (one for
  each remailer in the chain). The passphrases and other details of the
  nym are stored in the premail secrets file. Thus, the nym is fairly
  secure (much more so than, say, anon.penet.fi).

  The decode mechanism handles responses to nyms, again looking up the
  passphrases in the premail secrets file.

  You can also send mail from your nym, in one of two ways. Assume for
  the sake of example that your nym is you@alpha.c2.org.  Then, you
  would use a chain of 22;;aallpphhaa==yyoouu. Alternatively, you can use a chain
  of 22;;aallpphhaa and include this header field:

       Anon-From: you@alpha.c2.org (You Know Who)

  If you want the nymserver to send you a confirmation every time you
  send mail from your nym, add a $$ccoonnffiigg{{''aacckk''}} ==

  To delete a nym:

       premail -makenym you@alpha.c2.org delete

  Please delete nyms if you are not actually using them; this helps free
  up disk space and prevents the nymservers from being overloaded.

  1133..  PPoossttiinngg ttoo UUsseenneett

  Even though some remailers can post directly to Usenet, premail does
  not support that. Thus, if you want to post to Usenet, you should use
  a mail-to-news gateway.

  To find a working mail-to-news gateway, check Don Kitchen's list
  <hhttttpp::////ssttuuddeennttss..ccss..bbyyuu..eedduu//~~ddoonn//mmaaiill22nneewwss..hhttmmll>. There are two basic
  kinds: sites that scan the header fields, and sites that include the
  newsgroup in the address.

  Using the address-parsing kind, to post to alt.anonymous, you'd just
  send mail to alt.anonymous@myriad.alias.net (assuming, of course, that
  myriad.alias.net is still functioning).

  Using the header-scanning kind, send mail to
  mail2news@myriad.alias.net, and include this header field:

       Newsgroups: alt.anonymous

  The header scanning kind has one advantage: you can cross-post to
  multiple newsgroups using one mail message.

  One frequently asked question is: how can I follow up on a thread
  while posting anonymously? This is easy. Find the MMeessssaaggee--IIdd:: header
  field in the post you're responding to, and change it into a
  RReeffeerreenncceess:: field in your outgoing mail.

  Here's an example that ties it all together. Let's say you wanted to
  reply to this post:

       From: Edward Brian Kaufman <ebk8@columbia.edu>;
       Newsgroups: alt.privacy.anon-server, alt.anonymous
       Subject: A few questions about anon posts
       Message-ID: <Pine.SUN.3.94L.960630113156@aloha.cc.columbia.edu>;

       Hi,

       I'd like to know what the best/easiest way to do anon posts is and
       how to do them.  Thank you,

       Ed

  To post the reply anonymously, send this mail:

  To: mail2news@myriad.alias.net ((chain))
  Cc: Edward Brian Kaufman <ebk8@columbia.edu> ((chain))
  Newsgroups: alt.privacy.anon-server, alt.anonymous
  Subject: Re: A few questions about anon posts
  References: <Pine.SUN.3.94L.960630113156@aloha.cc.columbia.edu>

  If you have a Unix machine, using premail is the best way. To find
  out how, read the manual.

  1144..  AAddddrreessss bbooookk

  Adding the extra encryption commands is not difficult, but it can be
  tedious and potentially error prone. Thus, premail provides an address
  book for specifying commands to be used with specific e-mail
  addresses.

  For example, let's say that one of your correspondents tells you that
  she prefers mail to be PGP encrypted. Then, instead of typing
  ((((eennccrryypptt--ppggpp)))) every time you send her mail, you could add this line
  to your addresses file:

       her@email.address: ((encrypt-pgp))

  The addresses file is usually at ~~//..pprreemmaaiill//aaddddrreesssseess, but the
  location is a configurable option.

  Another example is the hackerpunks mailing list, in which all of the
  subscribers have alpha.c2.org nyms. Since haqr@alpha.c2.org has this
  line in his addresses file, he is able to post to the list with just
  ``TToo:: hhppuunnkkss'':

       hpunks: hackerpunks@alpha.c2.org ((chain=2;alpha=haqr))

  An address book entry can also expand to a list of addresses. For
  example:

       alice: alice@crypto.com ((encrypt-pgp))
       bob: bwhite@got.net ((key=bobw@netcom.com))
       eric: eric@ecsl.org ((encrypt-pgp))

       friends: alice, bob, eric

  Sending mail to ffrriieennddss would then do what you'd expect: send
  encrypted mail to each of alice, bob, and eric's full e-mail
  addresses.

  1155..  SS//MMIIMMEE

  Version 0.44 of premail contains limited support for S/MIME messages.
  Basic message formatting works, but there are problems with creating
  usable certificates, and there is still no support for an encryption
  algorithm interoperable with RC2. However, a few hearty souls may wish
  to experiment with the S/MIME functionality that is present. This
  section explains how to do it.

  First, you must install RIPEM 3.0b2 (or later). This is available from
  the ripem export-controlled FTP site
  <ffttpp::////rriippeemm..mmssuu..eedduu//ppuubb//ccrryypptt//rriippeemm//>. You'll need to get an account
  on the server in order to download any of the export-controlled code -
  the GETTING_ACCESS file on the site explains how.

  Once you have RIPEM installed (and the rriippeemm configuration option
  pointing to the executable), create a public key with this command:

       premail -ripemkey

  You will then be prompted for your e-mail address. Alternatively, you
  can give your e-mail address as a command line argument to pprreemmaaiill
  --rriippeemmkkeeyy.

  After your key is created, you can send signed messages by adding the
  ((((ssssiiggnn)))) command. If you send a signed message to another premail
  user, they will have your public key, and can send you mail, by using
  ((((eennccrryypptt==yyoouurr@@uusseerr..iidd)))).

  The default encryption is Triple-DES. If the recipient can't handle
  it, then ((((eennccrryypptt--ddeess)))) will fall back to plain DES, which most users
  will be able to decrypt - probably including ``export'' versions of
  S/MIME. Of course, the disadvantage of using plain DES is that any
  competent spy organization will also be able to decrypt the messages
  ;-).

  Unfortunately, RIPEM 3.0b2 has some significant differences from other
  S/MIME implementations in the way it handles public key certificates.
  These prevent you from getting a VeriSign certificate you can use. It
  is, however, possible to accept VeriSign class 1 beta certificates by
  running the following:

       > rcerts -u your@user.id
       Enter password to private key:
       E - Enable standard issuers...
         Enter choice:
       e
       v
         Enter the number of months the certificate will be valid, or blank to cancel:
       12
         Enter choice:
       q

  1166..  DDeebbuuggggiinngg

  If you run into trouble with premail, it might be of value to turn on
  some of the debugging options. This can be done on the command line,
  or in the .premailrc file. In the former case, add a ++ddeebbuugg==cchhvvyy
  argument to the command line. In the latter case, try:

       $config{'debug'} = 'chvy';

  Here are the meanings of the debug options:

  +o  cc: Print command line invocation.

  +o  hh: Print headers of input message.

  +o  ll: Debug output goes to log instead of stdout.

  +o  pp: Print finished message, do PGP.

  +o  rr: Print chain chosen (useful in debugging chain selection).

  +o  yy: Print finished message, don't do PGP.

  +o  vv: Print all kinds of verbose info.

  Note that ++ddeebbuugg==pp puts the encrypted message on stdout.  This may be
  useful for constructing reply blocks, among other things.

  If there are problems with premail, then one of the best ways to track
  them down is through the log. Try setting the ddeebbuugg configuration
  option to cchhvvll, setting the llooggffiillee configuration option (for example,
  to ~~//..pprreemmaaiill//lloogg), and then examining the log. Also, if you're
  bringing bugs to my attention, it helps a lot if you can send me
  relevant excerpts from the log.

  1177..  TTeecchhnniiccaall nnootteess

  This section covers a number of techincal notes related to the
  operation of premail. This information should not be necessary for
  ordinary use.

  1177..11..  MMuullttiippllee rreecciippiieennttss

  One of the tricky problems with mail encryption packages such as
  premail is how to deal with multiple recipients. Based on experience
  with previous versions, this version of premail tries very hard to
  ``get it right.'' However, as a consequence, the exact behavior can
  sometimes be difficult to understand.

  The hard part is when some of the recipients have encryption specified
  and others don't. What premail does is to split the recipients up into
  groups. If two recipients can receive the same actual message, they
  are in the same group, otherwise not. For example, recipients getting
  an encrypted and an unencrypted message cannot be in the same group.
  However, multiple recipients appearing in TToo:: and CCcc:: fields that use
  the same encryption method will be in the same group. A single
  message, encrypted to multiple recipients, will be sent, which is
  considerably more efficient than encrypting separately for each
  recipient.

  One subtle point is the handling of BBcccc:: recipients. The semantics of
  BBcccc:: specify that the mail be sent to each of the BBcccc:: recipients, but
  that none of the other recipients be able to find out their identity.
  However, encrypting to multiple recipients would defeat this, because
  it is possible to indentify all of the recipients of the encrypted
  message. Thus, each encrypted BBcccc:: recipient gets its own group.

  Each recipient of an anonymous message also gets its own group, for
  similar reasons.

  An attempt is made to make the headers in the message received by the
  recipient be the same as if no encryption were used.  Specifically,
  the complete TToo:: and CCcc:: header fields will be present, but the BBcccc::
  field will be missing. One exception to this rule is anonymous
  messages, in which case the recipient can't see any information about
  the other recipients.

  1177..22..  EErrrroorr hhaannddlliinngg

  The goal is to handle errors in the same way as sendmail. Thus, the
  exact handling depends on the setting of the --ooee command line option.
  The default (as in sendmail) is --ooeepp, meaning that the error message
  is printed to standard out, and the mail message is appended to the
  dead letter file (the location of which is a configuration option).

  Another choice is --ooeemm, in which case the error message and the mail
  message are packaged together and mailed back to the user. This is
  appropriate when the mailer has no way to deal with error messages
  returned from premail.

  One additional choice, not provided by sendmail, is --ooeedd, which prints
  the error message on standard out, but drops the mail message. This is
  a good choice if the mailer can interpret a non-zero return status
  code as indication of an error. This is the mode used by Netscape (and
  is automatically selected when premail is invoked as prezilla).

  1177..33..  SSeeccuurriittyy iissssuueess

  In designing premail, usefulness and convenience were considered more
  important than top security. Nonetheless, it can provide good
  security, especially if you are aware of the security issues.

  One overriding assumption was that your machine is secure, and that
  the serious threats were those of eavesdroppers on the network and e-
  mail forgers. In general, premail handles passive attacks quite well,
  while containing a number of vulnerabilities to active attacks.

  Here are some potential security pitfalls with premail:

  +o  Stores secrets information on disk file.

  +o  Stores (potentially sensitive) temporary files on disk.

  +o  Does not check authenticity of remailer list, remailer public key
     ring, or Mixmaster information gotten from the Web.

  +o  Accessing the Web signals when anonymous mail is about to be sent,
     perhaps aiding traffic analysis.

  +o  Does not evaluate the trustworthiness of public keys used for
     encryption and signature checking.

  1177..44..  UUsseelleessss ffeeaattuurreess

  Over the years, premail has accumulated a number of features of
  dubious value. One of them is support for MOSS, a nice encryption
  protocol that nevertheless failed to catch on. If you feel the urge to
  use it, documentation is available in the release notes for version
  0.43 <hhttttpp::////wwwwww..cc22..nneett//~~rraapphh//pprreemmaaiill//pprreemmaaiill..nnootteess..00..4433>.

  One potentially cool feature is a server for decoding e-mail. This
  _w_o_u_l_d be a useful feature if there were any mailers which used it. The
  protcol for the server was designed to be fast (much, much faster than
  invoking pprreemmaaiill --ddeeccooddee separately for each message), as well as
  ``crypto-neutral,'' meaning that it doesn't contain any features
  designed just for crypto, and that it could be used for other tasks,
  for example converting image formats or character sets.  Thus, a
  client designed to use this protocol would like be fully exportable
  from the US. If you're interested in integrating support for this
  protocol into a popular e-mail client, please get in touch with me.

  1188..  RReellaatteedd ddooccuummeennttss

  +o  The README file for premail version 0.33a.

  +o  Release notes for version 0.43 of premail.

