Hacking Mixminion                                  -*- Text -*-

Requirements:
        Python 2.0-2.2  (see PORTING NOTES below)

        OpenSSL 0.9.7 (If you don't have it, the Makefile knows how to
            download it for you.)

        A working /dev/urandom (see PORTING NOTES below)

Things to hack:
        See the TODO list.

DESIGN PRINCIPLES:
    - It's not done till it's documented.
    - It's not done till it's tested.
    - Don't build general-purpose functionality.  Only build the
      operations you need.
    - "Premature optimization is the route of all evil." -Knuth
      Resist the temptation to optimize until it becomes a necessity.

CODING STYLE:
    - See PEP-0008: "Style Guide For Python Code".  I believe in most of it.
      (http://www.python.org/peps/pep-0008.html)
    - Also see PEP-0257 for documentation; we're not there yet, but it's
      happening. (http://www.python.org/peps/pep-0257.html)
    - Magic strings:
         "XXXX" indicates a defect in the code.
         "FFFF" indicates a missing feature.
         "????" indicates an untested or iffy block.
         "DOCDOC" indicates missing documentation.

PORTABILITY NOTES:
    - I've already backported to Python 2.0.  (I refuse to backport to 1.5 or
      1.6.)
    - Right now, we're dependant on OpenSSL. OpenSSL's license has an
      old-style BSD license that isn't compatible with the GPL.  We
      have two other options, it seems:
         - libnss: this is a dual-license GPL/MPL library from
           Mozilla.  Sadly, we can't use it now, because it doesn't
           yet support server-side DHE.  Bugzilla says that
           server-side DHE is targetted for 3.5.  Perhaps then we can
           port, but I wouldn't hold my breath.
         - gnutls/libgcrypt: These are the GNU offerings; the relevant
           portions of each are licensed under the LGPL.  They don't
           support OAEP, but we've already got an implementation of that
           in Python.

      So for now, it's OpenSSL.  I'll accept any patches that make us
      run under gnutls/libgcrypt as well, but I think in the long term
      we should migrate to libnss entirely.

PORTING TO NON-LINUX PLATFORMS:
    - If you need to run on a system without an acceptable /dev/*random,
      you'll need to write an acceptable fallback for mixminion.Crypto.trng()
      to use.

CAVEATS:
    - If I haven't got a test for it in tests.py, assume it doesn't work.
    - The code isn't threadsafe.  It will become so only if it must.

FINDING YOUR WAY AROUND THE CODE.
    - All the C code is in src/.  Right now, this is just a set of thin
      Python wrappers for the OpenSSL functionality we use.
    - The Python code lives in lib/mixminion (for client and shared code)
      and lib/mixminion/server (for server code only).  The main loop is
      in lib/mixminion/server/ServerMain; the asynchronous server code is
      in lib/mixminion/server/MMMTPServer.
    - A message coming in to a Mixminion server takes the following path:

        Received in MMTPServer;
              V
         Stored in an 'Incoming' queue, implemented in ServerMain and Queue.
              V
        Validated, decrypted, padded by code in PacketHandler.
              V
         Stored in a 'Mix' pool, implemented in ServerMain and Queue.
             V
        A batch of messages is selected by the 'Mix pool' for delivery.
             V
             ---Some are placed in an 'Outgoing' queue...
             I       V
             I   ... and delivered to other Mixminion servers via MMTPServer
             V
             ---Others are queued and delivered by other exit methods,
                implemented and selected by ModuleManager.

CONTRIBUTING PATCHES:
    - Send them to the list mixminion-dev@freehaven.net, or to me
      (nickm@freehaven.net).

--Nick
