$Id: README,v 1.66 2003/12/12 23:01:31 nickm Exp $ ====================================================================== This is Mixminion version 0.0.6rc2, from the Mixminion CVS repository. 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 VERSION 0.0.6rc2: - Fixed a couple of bugs that would prevent Mixminion from running on Python 2.0 or Python 2.1. - Fixed a build problem with stand-alone Windows builds: the 'bsddb' module was not included, so we were defaulting to the slow and inefficient 'dumbdbm' module to store hash logs, SURB logs, and fragment indexes. NEW IN VERSION 0.0.6rc1: - Windows support - The Mixminion command-line interface now works on MS Windows, at least for me. It has been tested on Windows 2000, and should work on any platform running Windows 98 or later. There are probably some lingering bugs, especially when running a server. - Improved security - SURB keys are now rotated periodically. - The client now _always_ shuffles packets before delivery, and sends them in a random order. - Improved robustness - Servers are now addressed by hostname rather than IP. It is now feasible to run a Mixminion server with a dynamic IP address. Support for old-style routing will be deprecated in 0.0.7. (Servers use a DNS-farm abstraction to avoid blocking on slow DNS lookups. MMTP connections are still authenticated, so attacks against DNS can at worst delay packets from arriving.) - The path generation logic has been largely rewritten to use the optimal routing method for each server-to-server pair. - The path generation code now chooses good paths for fragmented messages and messages with specific requirements on their exit nodes. - Client queues are generally less buggy. - Consistency enforcement between fragmentation and other modules. - Better spec compliance. - Improved performance - When flushing messages from the client queue, it is no longer necessary to load them all into RAM at once. - User interface tweaks - When running as a client, Mixminion now displays servers by nickname in addition to IP:port whenever possible. Servers will gain this behavior in a later version, once they begin downloading directories. - The behavior of 'mixminion list-servers' has been changed: its default output is far terser and easier to parse than before, though output _even more_ verbose than previous can be selected. Also, whereas the old implementation only listed servers by their lifetime, capabilities, and status, it is now possible to list arbitrary 'features' of the servers in the directory. - Error messages for timeouts are more reasonable; timeouts themselves should now work a little better than before. - A longstanding typo in the MMTP server's logging code has been resolved: running at DEBUG should be far terser and more reasonable than before. - Users can now send fragmented messages for reassembly by their recipients rather than exit servers. (Client side reassembly is not yet implemented, however.) - Many error messages have been cleaned up, including a few related to SSL errors, Windows internals, corrupt databases, unsupported databases. - Build improvements - Use the preferred version of Python if one exists. - Add build target to output test vectors for crypto functionality. - Support the DESTDIR environment variable - Check SHA1 digest on downloaded OpenSSL 0.9.7c. - Other bugfixes too numerous to mention. STILL NOT IN THIS VERSION: - There's a man page, but it's not included yet because I want it to work cross-platform. - 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.5 ======================================== First, follow the installation instructions from section IV to install the new version of the software. If you aren't running a server, you are done. (Compatibility note: SURB keyrings used by version 0.0.5 are _not_ compatible with keyrings used by 0.0.6!) If you're running a server, you may need to upgrade your configuration file. Follow these steps: 1. Your configuration file may be out of date. You will need to add a 'Hostname' entry to the 'Incoming/MMTP' section of your configuration. It _must_ contain a valid DNS name for your server. (You can use a static IP instead, if your server's IP will never change.) The 'IP' configuration entry is still required, too, in order to support older clients. 2. Start your server as usual ('mixminion server-start') and try sending some messages through it. Check your configuration log for warnings. IV. HOW TO INSTALL MIXMINION ============================ The quick version: For Unix-clones, Mac OS X, or Windows with Cygwin --------------------------------------------------------------------- % cd Mixminion-0.0.6rc2 % make download-openssl % make build-openssl % make % make test EITHER: % su Password: # make install OR: % make install PREFIX=~ The verbose version: For Unix-clones, Max OS X, or Windows with Cygwin ----------------------------------------------------------------------- 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 . 6) Run "make test" to run Mixminion's unit tests. If you get any errors, please report them to . 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". The very easy version: For Windows ---------------------------------- First, make sure that you're running Win98 or later. Download 'Mixminion-0.0.6rc2.win32.zip", and unpack it anywhere you like. It will create a directory named 'mixminion'. Use mixminion.exe from that directory as your command-line client. NOTE TO ALL WINDOWS USERS: This is the first version of Mixminion to support native Win32 operations. As such, you should consider it even more experimental than usual. If you find any bugs, or any places where its behavior is stupid for a Windows environment, please let me know. (See section VII below for information on how to report bugs.) The slightly harder version: For Windows with Python 2.3 -------------------------------------------------------- First, make sure that you have the latest official release of Python 2.3 installed. As of 5 Dec 2003, this is 2.3.2. Download and run "Mixminion-0.0.6rc2.win32-py2.3.exe". It will unpack its files into your Python directory. The script to invoke Mixminion will be stored in the 'Scripts' subdirectory of your Python directory. Whenever the instructions below tell you to run 'mixminion', run "python Scripts\mixminion.py' instead, from the python directory. (Future releases may include a batch file to make this easier, especially if somebody else contributes one.) Be sure to read the "NOTE TO ALL WINDOWS USERS" above. The verbose version: How to build on Windows -------------------------------------------- (I have only tried this with Visual Studio 6 and Python 2.3. Let me know if you succeed with any other compilers. Also, let me know if these instructions don't work.) First, install Python version 2.0 or later, either from the official binary or by building it yourself. When you build Mixminion, you will need to use the same compiler as was used to build Python: the standard distribution uses Visual Studio 6. Second, download an unpack the Mixminion source distribution. Third, get a compiled copy of OpenSSL version 0.9.7 or later (as of 5 Dec 2003, the latest stable version is 0.9.7c). You can either compile it yourself, or use a set of precompiled binaries (such as are available from XXXX). Place the compiled libraries under the "contrib" directory in the Mixminion source directory, so that the include files are in "contrib\OpenSSL\include" and the libraries are in "contrib\OpenSSL\lib\VC". Now you are ready to build Mixminion! Make sure that python.exe is on your path, then run: python setup.py build python setup.py run --subcommand=unittests If all the unit tests pass, you can either install the software locally and use it as described in 'the slightly harder version' above: python setup.py install Or you can make a windows installer for users with Python: python setup.py bdist_wininst Or, if you have the py2exe package installed, you can make a standalone binary that people can run without installing Python: python setup.py py2exe Finally, be sure to read the "NOTE TO ALL WINDOWS USERS" above. V. HOW TO SEND MESSAGES VIA MIXMINION ===================================== Just run one of the following command lines: mixminion send -t -i OR mixminion send -t (to read from stdin) OR mixminion send -t -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 specify headers, use any of the following options: --subject= --in-reply-to= --references= --from= All are used verbatim, except for 'from', which the exit server wraps in an envelope to indicate that the address is anonymous. For example, if you specify --from="Tristero", your recipient will get an email that says something like "From: "[Anon] Tristero" ". To see a list of currently known servers, type: mixminion list-servers You can change the format and contents of this listing. For more information, run 'mixminion list-servers --help'. To force a reload of the server directory, type: mixminion send -t
[-i ] -D yes To send a message _without_ reloading the directory, type: mixminion send -t
[-i ] -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 (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
[-i ] -H You can change the default number of hops by editing ~/.mixminionrc To specify a path manually, type: mixminion send -t
[-i ] -P The argument 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.] You can specify a random-length sequence of *about* N servers like this: -P 'Foo,~3,Bar' [Foo, about 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= [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 ~/.mixminionrc and change the ForwardPath line: # By default, use the same servers for entry and exit each time, # with about three randomly chosen servers in the middle. ForwardPath: FavoriteEntry,~3,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
-i -P 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 To remove messages that have been waiting in the queue for more than seven days: mixminion clean-queue -d 7 (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
-i -P Also, as a final side note, "mixminion send --queue" is a synonym for "mixminion queue".) To decode a message you have received, type: mixminion decode -i -o . Or, to send output to stdout: mixminion decode -i (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 To send the reply block to a file, instead of to stdout: mixminion generate-surb -t -o 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 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 -i The other options to 'send' and 'pool' still apply; the reply block takes the place of the destination address: mixminion send -R (Read from stdin) mixminion send -R -D yes (Reload directory) mixminion send -R -H 4 (Use 4 hops before reply.) mixminion send -R -P 'Z,*' (Start with server "Z".) mixminion pool -R (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 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 " (The -f flag and path are only necessary if you placed the configuration file somewhere 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 They can also use your ServerDesc without importing it by using the filename as a part of their path: mixminion send -t
-P ',?,?' 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, your server will not be inserted automatically; the directory server holds your server's information separately until I confirm it (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 . 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 . 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: