$Id: README,v 1.50 2003/06/12 04:08:09 nickm Exp $
======================================================================
This is Mixminion version 0.0.4.

 WARNING!  Mixminion 0.0.4 breaks backward compatibility with version 0.0.3.
 Versions older than 0.0.3 are no longer supported; you should upgrade now.

CONTENTS:
        I.    Overview
        II.   What's new in this version
        III.  How to upgrade
        IV.   How to install
        V.    How to send messages
        VI.   How to run a server
        VII.  How to report bugs and suggestions
        VIII. Future interoperability
        IX.   How to contribute

I. OVERVIEW
===========

Mixminion is the standard implementation of the Type III anonymous remailer
protocol, which lets you send very anonymous email.  This best-of-breed
remailer uses conservative design approaches to provide security against most
known attacks.  We chose a simple, extensible design so that we can provide a
robust core system and then experiment with new research features such as
dummy policies, directory servers, and reputation systems.

You can find the latest information at http://mixminion.net/, or on the
mailing list, archived at http://archives.seul.org/mixminion/dev/.  Please
consider subscribing, especially if you're going to run a node.

This is a testing alpha release.  You will probably only want to use it if
you are technically inclined, curious, and interested in helping the
Mixminion development effort.

WARNING!  Do NOT use this release if you require strong anonymity.  It has
known deficiencies, including some that make it possible for an adversary
to trace your message through the system.

II. WHAT'S NEW IN THIS VERSION?
===============================

NEW IN FINAL 0.0.4 release:
  BUGFIXES:
  - Fixed a bug that would sometimes give a useless error message when
    trying to build a message with a too-long path.

NEW IN VERSION 0.0.4rc4:
  BUGFIXES:
  - Improved error message on nonexistent directory.
  - Fixed a bug (found by Mike Gurski) that could kill a server if a message
    was received for an old key in between deleting the old key's replay cache,
    and deleting the old key itself.
  - Fixed a bug in setting up server directories.

NEW IN VERSION 0.0.4rc3:
   BUGFIXES:
   - Memory leaks:
       - Made server code release memory more aggressively.
       - Fixed a race condition where messages could be queued on a server
         connection that was already shutting down.
       - Fixed memory leaks on certificate checking.
   - Server bugs:
       - Fixed a server crash on key-rotation that would occur when to trying
         to open the same hash log db file twice.
       - Fixed bug that would crash server if PublicKeyLifetime changed.
       - Made server differentiate between ENOENT and EACCES when starting.
       - Fixed a bug that would cause key generation to happen at the wrong
         times.
   - Other bugs:
       - Fixed a bug related to using client keyrings without passwords.
       - Made ASCII armor more reliable in the face of extraneous space,
         headerless armor, and so on.
       - Excluded superceeded servers from directories more thoroughly.

   OTHER CHANGES:
   - Cosmetic:
       - Commented most uncommented code.
       - Refactored path selection again.
       - Refactored code to use more reliable file accessing functions.
       - Added more unit tests
   - Performance enhancements:
       - Changed recommended OpenSSL version to 0.9.7b.
   - Implementation quality
       - Improved a few log messages.
       - Made included etc/mixminiond.conf more reasonable by using a less
         aggressive retry schedule, commenting out unused Allow lines, and
         decreasing PublicKeyLifetime.
       - Made os.expanduser work on more configuration values.
   - Enabled threading on more C functions.

NEW IN VERSION 0.0.4rc2:
   BUGFIXES:
   - The server shouldn't crash so much when it gets bad TLS errors or
     timed-out connections.  Sometimes, it will give better errors when it
     does.

NEW IN VERSION 0.0.4rc1:
   First steps toward directory automation:
      - Servers generate new keys and server descriptors when the old ones
        are close to expiring.  (~2 weeks)
      - Servers also regenerate server descriptors when their configuration
        changes.
      - When a set of keys expires, a server rotates to the next set
        automatically (with some overlap).
      - Servers can upload their descriptors to a directory server
        automatically.
      - There's a trivial directory backend that accepts signed updates
        automatically, and queues new servers.
      - Directories now include a list of which servers are believed to be
        working correctly.  Right now, this list is still manually
        configured.
      - There's a cron job that regenerates the directory every so often.

   Packet format overhaul:
      - Server RSA keys are now 2048 bits long.
      - The header representation is more compact now, so we don't pay in
        space for the increased key length.

   MMTP improvements:
      - The certificate regime has changed so that key rotation is now
        possible: instead of authenticating servers based on their TLS
        keys, we authenticate based on their identity keys, which never
        change.
      - Packets sent from a server to itself no longer hit the network.
      - When relaying messages, a server never opens more than 1 connection
        at a time to the same server.
      - MMTP clients now recognize a 'REJECTED' reply that a server can use
        to refuse messages when under high load.

   Other server improvements:
      - Servers can (optionally) track the number of packets received,
        relayed successfully, dropped, and so on.
      - Servers can recognize and advertise whether they are configured
        'securely.'
      - The deliver/retry logic has been largely rewritten.  It should
        freak out and die less frequently now.  In any case, it also prints
        better debugging messages, and thrashes the disk less.

   Minor changes:
      - We now use real OpenPGP-style ASCII-armor.  Accept no substitutes!

   Numerous UI Improvements:
      - There are saner error messages for many common cases.
      - Support for multiple SURB keys to prevent identity-blending attack.
      - There's a new (temporary) 'mixminion ping' command that you can use
        to tell whether a server is accepting connections.  It's potentially
        dangerous (if you go pinging all the servers in your path), and has
        a banner saying so.
      - The path selection syntax has changed to be more flexible.  (You can
        now specify a single random hop, or N random hops.)

<See HISTORY file for changes in earlier versions.>

STILL NOT IN THIS VERSION:
   - We could use some man pages.
   - IP-based restrictions don't work.
   - No support for distributed directories.
   - Other stuff too numerous to mention; see TODO.

III. HOW TO UPGRADE FROM MIXMINION 0.0.3
========================================

First, follow the installation instructions from section IV to install the
new version of the software.

If you're running a server, you will need to upgrade your server's files.
Follow these steps:

    1. Your configuration file may be out of date.  The following options
       are new (but not required):
          "Publish"
          "LogStats"
          "StatsInterval"
          "StatsFile"

       The following options have been renamed:
          "PublicKeySloppiness" -> "PublicKeyOverlap".

       The following options, formerly optional, are now mandatory:
          "Nickname"

       Because key rotation is now implemented, you may want to decrease the
       value you've chosen for PublicKeyLifetime.  Formerly, "3 months" was
       typical.  Now, something on the order of one to three weeks is
       probably in order.

       See etc/mixminiond.conf for an example.

    2. Run 'mixminion server-upgrade' to delete keys and packets in obsolete
       formats.  (If you forget this step, the server will remind you when
       you try to start it.)

    3. Start your server as usual ('mixminion server-start') and try sending
       some messages through it.  (You can find the filename(s) of the
       currently live server descriptors stored in $HOMEDIR/current-desc.)

       Example:
          % mixminion server-start
            [wait for server to start]

          % cat $HOMEDIR/current-desc
          $HOMEDIR/keys/key_0022/ServerDesc

          % cp `cat $HOMEDIR/current-desc` myserver
          % mixminion send -t <your email> -P './myserver,?,?'
            [Type your message, followed by Ctrl-D.]
          
            [Wait a while, and see if your message gets sent.]

    4. When you're confident your server is working correctly, and you want
       to advertise your server to the rest of the world, edit your
       mixminiond.conf, and set the "Publish" option to 'yes'.

    5. Restart your server.  It will now advertise itself to the (still,
       alas!) central directory.  The first time you do this, I have to
       update the directory manually (to prevent pseudospoofing).  Once your
       server is listed, future updates will be get into the directory
       automatically.

IV. HOW TO INSTALL MIXMINION
============================

The quick version.
------------------
  <download and unpack http://www.mixminion.net/dist/Mixminion-0.0.4.tar.gz>

  % cd Mixminion-0.0.4
  % make download-openssl
  % make build-openssl
  % make
  % make test
 EITHER:
    % su
    Password:
    # make install
 OR:
    % make install PREFIX=~

The verbose version.
--------------------

  1) You must have Python version 2.0 or later installed on your system.  The
     binary may be called "python", "python2", "python2.X", or something else.
     If you don't have Python >=v2.0, go install it.  You can find source and
     binary distributions at http://www.python.org/.

  2) If you have OpenSSL version 0.9.7beta3 or later, go to step 5.
     Otherwise, continue.

  3) Run "make download-openssl".

  4) Run "make build-openssl".  If this step fails, OpenSSL didn't build
     correctly on your system.  Go read contrib/openssl/INSTALL, and make
     OpenSSL build.

  5) Run "make".  If you don't get any error messages, go to step 6.

     If you have OpenSSL 0.9.7 installed, but the build script doesn't find
     it, you can force it to look in a particular location (say, "/home/ssl")
     with:
            make OPENSSL_PREFIX=/home/ssl
     This will make the scripts look for headers in $OPENSSL_PREFIX/include
     and libraries in $OPENSSL_PREFIX/lib.

     If the scripts *still* can't find OpenSSL 0.9.7, you can override the
     compile and link options directly, like this:
            make OPENSSL_CFLAGS='-I/home/ssl/include' \
                 OPENSSL_LDFLAGS='-L/home/ssl/libraries -lssl097 -lcrypto097'

     If your C compiler knows where to find OpenSSL on its own, but the
     build script doesn't trust it, you can disable searching like this:
            make SKIP_OPENSSL_SEARCH=y

     If you get any other errors, please report them to <nickm@freehaven.net>.

  6) Run "make test" to run Mixminion's unit tests.  If you get any errors,
     please report them to <nickm@freehaven.net>.

  7) Run "make install" to install Mixminion.  You may need to be root to
     execute this command.  By default, Mixminion will install itself relative
     to your python distribution.  If you want to install somewhere else (e.g.
     /home/miniond/), run "make install PREFIX=/home/miniond".

     A script called "mixminion" will be created in the 'bin' directory
     relative to your prefix, or in the same directory as the python
     executable if no prefix is provided.  To make sure that everything was
     installed correctly, you can run "mixminion unittests".

V. HOW TO SEND MESSAGES VIA MIXMINION
=====================================

Just run one of the following command lines:

        mixminion send -t <email address> -i <filename to send>
    OR  mixminion send -t <email address>            (to read from stdin)
    OR  mixminion send -t <email address> -i -       (also reads from stdin)

Mixminion will then take the following steps:

     A) Download and validate the latest server directory.
        (But only if you haven't done so since midnight GMT.)
     B) Select a path that ends at a server with SMTP support.
        (Currently, this defaults to 4 hops.)
     C) Read your message.
     D) Construct a Type III Mix packet containing your message.
        (For more information, see the links at http://www.mixminion.net/)
     E) Send the message to the first server in your path.

To see a list of currently known servers, type:

      mixminion list-servers

To force a reload of the server directory, type:

      mixminion send -t <address> [-i <file>] -D yes

To send a message _without_ reloading the directory, type:

      mixminion send -t <address> [-i <file>] -D no

To reload the directory without sending a message, type:

        mixminion send -D yes
     OR mixminion update-servers

To see whether a server is running, type:
 
      mixminion ping <servername>

      (WARNING: This command is potentially dangerous, for a number of subtle
      and not-so-subtle reasons.  It will go away before mixminion 1.0.)

To force a path of a given length, type:

      mixminion send -t <address> [-i <file>] -H <number of hops>

      You can change the default by editing ~/.mixminionrc

To specify a path manually, type:

      mixminion send -t <address> [-i <file>] -P <path>

      The argument <path> must be a comma separated list of either:
          (a) Server nicknames as given by 'list-servers'
          (b) Paths to files containing server descriptors [more info below]

      For example, to send a message through the servers Foo, Bar, Baz, and
      Quux, you would type "-P Foo,Bar,Baz,Quux."

      To specify a randomly chosen server, you can include a question mark,
      like this:
             -P 'Foo,?,Bar,?'     [Foo, a random server, Bar, and another
                                   random server]

      You can specify a sequence of N random servers like this:
             -P 'Foo,*3,Bar'      [Foo, three random servers, then Bar.]

      If you have specified a path length (explicitly or in ~/.mixminionrc)
      you can use a '*' to indicate as many random servers as are needed to
      make your path long enough:

             -P 'Foo,*'           [Path that starts with Foo]
             -P '*,Foo'           [Path that ends with Foo]
             -P 'Foo,Bar,*,Quux'  [Path that starts with Foo and Bar,
                                   and ends with Quux]

      {ADVANCED} By default, the swap point will be halfway through
      the path (rounding up). To specify a swap point explicitly, use
      a colon in your path, as in:
             -P 'Foo,Bar:Baz,Quux'    [Swap headers at server Bar]
             --swap-at=<n>            [Swap headers at the n'th server]
      If you don't know what a swap point is, don't worry. :)

If you want to use the same path by default for all of your messages,
edit the  ~/.mixminonrc and change the ForwardPath line:

      # By default, use the same servers for entry and exit each time,
      # with three randomly chosen servers in the middle.
      ForwardPath: FavoriteEntry,?,?,?,FavoriteExit

To send a dummy message, specify "drop" instead of an email address, as in:

      mixminion send -t drop
      mixminion send -t drop -P '*,Foo'
      mixminion send -t drop -H 8

To queue a message for later transmission, run "mixminion queue" instead of
"mixminion send":

      mixminion queue -t <address> -i <file> -P <path>

      To see all the packets waiting in the queue:
      
      mixminion inspect-queue

      To attempt to deliver all messages waiting in the queue:

      mixminion flush

      To attempt to deliver no more than 16 messages:

      mixminion flush -n 16

      (QUEUE NOTE: By default, when "mixminion send" fails to deliver a
      message, it leaves that message in the queue to be reattempted later.
      To suppress this behavior, use the "--no-queue" option:
            mixminion send --no-queue -t <address> -i <file> -P <path>
      Also, as a final sidenote, "mixminion send --queue" is a synonym for
      "mixminion queue".)

To decode a message you have received, type:

      mixminion decode -i <input-file> -o <output-file>.

      Or, to send output to stdout:

      mixminion decode -i <input-file>

      (When you receive a message with non-printing characters via email, it
      will be encoded in base64 before delivery.  When you receive a reply,
      its contents will be encrypted.  The "mixminion decode" command
      extracts the original text from either kind of message as best it can.)

To generate a reply block, type:

      mixminion generate-surb -t <your-address>

      To send the reply block to a file, instead of to stdout:

      mixminion generate-surb -t <your-address> -o <filename>

      If you specify a "SURBAddress" field in ~/.mixminionrc, you may
      omit the target address:

      mixminion generate-surb

      Also, you can control path selection in the same way as with
      sending messages:

      mixminion generate-surb -H 3        (a 3-hop path)
      mixminion generate-surb -P '*,Foo'  (end with server foo)
      mixminion generate-surb -P 'Bar,*'  (start with server bar)

      You can use the '-n' option to generate many reply blocks at once:
      
      mixminion generate-surb -n 100      (generate 100 reply blocks)

      To save space, you can specify binary (as opposed to text) encoding
      for your reply blocks:

      mixminion generate-surb -b -o <filename>

      By default, the client will choose servers to make sure that your
      reply blocks will still function for 7 days.  To choose a different
      lifetime:
         mixminion generate-surb --lifetime=1           (1 day)
      Note that if you choose an overlong lifetime, there may not be enough
      servers whose keys will be valid for the entire period.

      If you maintain multiple pseudonymous identities, to avoid a
      SURB-swapping attack, you should use the --identity option so that
      you can later see which messages were to sent to which SURB identity.
         mixminion generate-surb --identity=alice -o alices_surb
         mixminion generate-surb --identity=bob   -o bobs_surb

Once you have a reply block for a user, you can send reply messages by
typing:

      mixminion send -R <reply-block-filename> -i <input-filename>

      The other options to 'send' and 'pool' still apply; the reply block
      takes the place of the destination address:
         mixminion send -R <reply-block>          (Read from stdin)
         mixminion send -R <reply-block> -D yes   (Reload directory)
         mixminion send -R <reply-block> -H 4     (Use 4 hops before reply.)
         mixminion send -R <reply-block> -P 'Z,*' (Start with server "Z".)
         mixminion pool -R <reply-block>          (Pool the message.)

      IMPORTANT: Mixminion reply blocks can only be used once!  (Thus,
      SURB="Single Use Reply Block".)  The program will remember which
      reply blocks it has used in the past, but if you give a single reply
      block to 2 users, it will only work for one of them, once.

      As a convenience, if you have a file containing many reply blocks,
      you can use it with '-R': the client will choose the first reply
      block from the file which has not expired, and which you have not
      yet used.

      To inspect the reply blocks in a file, you can run:
         mixminion inspect-surbs <filename>
 
If you need to use a proxy server to use the web you can specify it using the
http_proxy environment variable:

      export http_proxy=http://proxy:3128/
      mixminion send -D yes


VI. HOW TO RUN YOUR OWN MIXMINION SERVER
========================================

1) Create a copy of the "etc/mixminiond.conf" file from the
   mixminion distribution and place it where you like.  Mixminion will
   automatically look in ~/.mixminiond.conf, ~/etc/mixminiond.conf, and
   /etc/mixminiond.conf.  However, you can store it anywhere.

2) Edit mixminiond.conf to reflect your own system settings.

3) Run your server for the first time:

        "mixminion server-start -f <path to mixminiond.conf>"

    (The -f flag and path are only necessary if you placed the
    configuration file somehwere other than ~/.mixminiond.conf,
    ~/etc/mixminiond.conf, or /etc/mixminiond.conf.)

5) To try out your server, clients will need a copy of your server
   descriptor, whose location is stored $SERVER_HOME/current-desc.

   For example, if your mixminiond.conf contains the following line:

           Homedir: /home/mixminion/spool

   Then if you read the contents of /home/mixminion/spool/current-desc,
   you will find a filename like:

           "/home/mixminion/spool/keys/key_0001/ServerDesc".

   This file is your current server descriptor.

   Mixminion supports a global directory of server descriptors.  Until you
   are listed in that directory, clients can import your ServerDesc file
   (if they have a copy) by hand by running:

           mixminion import-server <filename>

   They can also use your ServerDesc without importing it by using the
   filename as a part of their path:

           mixminion send -t <address> -P '<filename>,?,?'

6) When you're ready to advertise your server, edit 'mixminiond.conf' and set
   the 'Publish' option to 'yes'.  When you restart your server, it will
   advertise itself to the central directory.

   The first time you do this, I have to update the directory manually (to
   prevent pseudospoofing).  Once your server is listed, future updates will
   be get into the directory automatically.

   WARNING: We don't have statistics yet, so the system isn't robust in the
   presence of unreliable servers in the directory.  Please don't publish a
   server if you don't think you can keep it up for a good while.

   {This step will be more automated in later versions.}

To shut down a server:
    mixminion server-stop [-f configfile]

To make a server reload its configuration:
    mixminion server-reload [-f configfile]

    (Right now, this just closes and re-opens the log files.)

Your server can be configured to keep track of the number of packets it
receives and other interesting statistics.  Ordinarily, it aggregates these
totals and flushes a report to disk at a configurable interval.  If you want
to see statistics in the _current_ interval, run:

    mixminion server-stats [-f configfile]

 
VII. HOW TO REPORT BUGS AND SUGGEST NEW FEATURES
================================================

To report bugs, please use the Bugzilla pages at http://bugs.noreply.org.

For other correspondence, please email <nickm@freehaven.net>.

For help in debugging, please try to send a copy of:
        * What command you were running
        * The complete error you got, including stack trace (if any)

If your error occurred on a running server, please make a copy of your
log--it might be helpful.

VIII. FUTURE INTEROPERABILITY
=============================

Mixminion is not yet feature complete.  As the software moves closer to
official release, backwards-incompatible changes *WILL* be introduced.
Future versions of Mixminion, including future versions in the 0.x track, may
reject messages from older versions as additional security features are
added.

Furthermore, the present preview versions include necessary diagnostic
features that potentially compromise anonymity and would be inappropriate in
a production system; these features will be removed or disabled by 1.0.

IX. HOW TO CONTRIBUTE
=====================

Send patches to <nickm@freehaven.net>.  If you can, please submit unified
diffs against the latest version of the code in CVS.

Make sure to run 'make test' before you send in any patches, so you can see
whether your patch broke existing code.  (It's okay if you're not sure how to
fix the test, but please let me know when you send your patch.)

------------------
(for emacs)
  Local Variables:
  mode:text
  indent-tabs-mode:nil
  fill-column:77
  End:
