$Id: README,v 1.37 2003/02/20 16:57:38 nickm Exp $ ====================================================================== This is Mixminion version 0.0.3 WARNING! Mixminion 0.0.3 breaks backward compatibility with version 0.0.2. 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 VERSION 0.0.3: Better build support: - Fail more gracefully with missing 'which'. - Fail more gracefully with missing python-dev. - Portability fixes for Python 2.0. Client tweaks: - Default connection timeout to 1 minute. - Rename stop-server to server-stop. - Rename reload-server to server-reload. NEW IN VERSION 0.0.3rc2: Numerous bugfixes, including: - More verbose client locking - More reasonable log messages - Better messages on missing openssl - Improved documentation - Better support for confused permissions on build - Better errors on failing directory retrieval - Less verbose description of reply blocks skipped. - Base64 encoding should no longer get corrupted by outlook - Fix nasty race on queue cleaning. - The code compiles (but doesn't run) under cygwin. New features: - mixminion stop-server and mixminion reload-server commands. NEW IN VERSION 0.0.3rc1: CLIENT: - Single-use reply blocks (SURBs) are fully supported and available. - You can use client-side pooling: it holds messages until you're ready to send them. Pooling also prevents you from losing messages when the first hop in your path is temporarily down. - You can now decode binary messages or reply messages from the command line. - We now time out faster when servers are down. - Many error messages are far friendlier. - It's now safe to run multiple instances of the client at once. - Numerous UI improvements and typo fixes; error reporting is better in many ways. BUILD: - It's easier to build with different OpenSSL installations. SERVERS: - Servers now have a lightly multithreaded design to prevent extreme stalling under heavy loads. Now the network should remain fairly responsive under far more traffic than before. - When a message delivery fails, the retry schedule is more reasonable. By default, a server will retry an undeliverable message every 30 minutes for a day, then every 7 hours for 5 days. - All modules that use SMTP now set a "X-Anonymous: yes" header. CONFORMANCE: - We now implement MMTP correctly; before, we didn't accept junk packets; handle protocol negotiation right; or do support key renegotiation. - DROP packets have random payloads. - A nasty bug in our implementation of counter mode is fixed. On the bright side, big-endian and little-endian hosts should now, finally, be compatible. On the minus side, we lose backward compatibility. - Server descriptors and directories now follow a more forward- compatible format: we can add sections and entries in the future with less risk of breaking existing clients. NEW IN VERSION 0.0.2.2: - Fixed a bug that crashed your server when another server's KeyID was incorrect. - Add minimal handlers for TERM and HUP signals. - Add a disclaimer to main usage message. NEW IN VERSION 0.0.2.1: - BUGFIX: A nasty bug is fixed that could, under just the right circumstances, send the server into an infinite loop and fill up your hard drive. If you're running a server, you *should* upgrade. - Server log messages are more reasonably structured. - setup.py is more clever about half-installed Python. - "list-servers" now supports the same directory-download options as does "send". NEW IN VERSION 0.0.2: - A real SMTP exit module to relay messages via a local MTA. Blacklisting is supported by address, by username, by host, by entire domain, and by regular expression. - Integrated directory support for clients. - Automatic path selection, along with a better user interface to specify paths. - You can now enable Cottrell (DynamicPool) and Binomial Dynamic Pool batching, though they are disabled by default to make the system more testable. - Servers resist certain trivial DoS attacks more strongly. In particular, you should no longer be able to send zlib bombs or flood a server with open connections. - Clean build process under FreeBSD. - Ability to run server as a daemon. - Slightly better documentation and error messages. - Better resistance to newline corruption of server descriptors. - Other bugfixes and performance improvements too numerous to mention. NEW IN VERSION 0.0.1: - You can run a rudimentary server that can deliver to other Mixminion servers, that can use Mixmaster to deliver to any external address, or that sends SMTP directly to a preconfigured set of addresses. - You can send anonymous email via these servers. STILL NOT IN THIS VERSION: - We could use some man pages. - IP-based restrictions don't work. - No automatic key generation or server publication. - No support for distributed directories. - Other stuff too numerous to mention; see TODO. III. HOW TO UPGRADE FROM MIXMINION 0.0.2 ======================================== Just follow the installation instructions below. If you're running a server, you may want to configure the new 'Retry' options in your mixminiond.conf file; see ./etc/mixmioniond.conf for examples. You do not need to generate a new server descriptor or keyset; just upgrade your software. IV. HOW TO INSTALL MIXMINION ============================ The quick version. ------------------ % cd Mixminion-0.0.3 % 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 . 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". 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 see a list of currently known servers, type: mixminion list-servers 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 force a path of a given length, type: mixminion send -t
[-i ] -H You can change the default 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." If you only care about the servers at the beginning or end of your path, you can include a wildcard, like this: -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. :) 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 [NEW IN 0.0.3] To pool a message for later transmission, run "mixminion pool" instead of "mixminion send": mixminion pool -t
-i -P To see all the packets waiting in the pool: mixminion inspect-pool To attempt to deliver all messages waiting in the pool: mixminion flush (POOL NOTE: By default, when "mixminion send" fails to deliver a message, it leaves that message in the pool to be reattempted later. To suppress this behavior, use the "--no-pool" option: mixminion send --no-pool -t
-i -P Also, as a final sidenote, "mixminion send --pool" is a synonym for "mixminion pool".) [NEW IN 0.0.3] 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.) [NEW IN 0.0.3] 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. [NEW IN 0.0.3] 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 -f " (The -f flag and path is 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, which should be stored in $SERVER_HOME/keys/key_*/ServerDesc. For example, if your mixminiond.conf contains the following line: Homedir: /home/mixminion/spool Then your first server descriptor will be stored in: "/home/mixminion/spool/keys/key_0001/ServerDesc". 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 6) When you're ready to advertise your server, email your server descriptor (PGP-signed, if possible) to . I'll try out your server for a while and then add it to the directory. WARNING: We don't have statistics yet, so the system isn't robust in the presence of unreliable servers in the directory. Please let me know if you're going to take down a server, and 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.) VII. HOW TO REPORT BUGS AND SUGGEST NEW FEATURES ================================================ Just 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: