[minion-cvs] A first man page fro mixminion.

[gd@seul.org]

Update of /home/minion/cvsroot/doc
In directory moria.mit.edu:/tmp/cvs-serv10927

Added Files:
	mixminion.1 
Log Message:
A first man page fro mixminion.

Should this be in src?



--- NEW FILE: mixminion.1 ---
.\" "man mdoc.samples" for information on how to tag the document.
.\" Type nroff -mdoc mixminion.1 | less
.Dd August 18, 2003
.Dt MIXMINION 1 Anonymity
.Os GNU/Linux
.Sh NAME
.Nm mixminion
.Nd A third generation remailer client and server (v0.0.4).
.Sh SYNOPSIS
.Nm mixminion Cm send
.Op Fl t Ar <email-address> | Ar drop 
.Op Fl R Ar <reply-block-filename>
.Op Fl i Ar <filename-to-send>
.Op Fl D Ar yes|no
.Op Fl H Ar <number-of-hops> 
.Op Fl P Ar <path>
.Nm mixminion Cm list-servers 
.Nm mixminion Cm update-servers
.Pp
.Nm mixminion Cm queue
.Op Fl t Ar <email-address> | Ar drop
.Op Fl R Ar <reply-block-filename>
.Op Fl i Ar <filename-to-send>
.Op Fl D Ar yes|no
.Op Fl H Ar <number-of-hops> 
.Op Fl P Ar <path>
.Nm mixminion Cm inspect-queue 
.Nm mixminion Cm flush 
.Op Fl n Ar <no-of-messages> 
.Pp
.Nm mixminion Cm decode Fl i Ar <input-file> 
.Op Fl o Ar <output-file> 
.Nm mixminion Cm generate-surb Fl t Ar <your-address> 
.Op Fl b 
.Op Fl o Ar <filename>
.Op Fl H Ar <number-of-hops> 
.Op Fl P Ar <path>
.Op Fl n Ar <no-of-SURBs>
.Op Ar --lifetime=<days>
.Op Ar --identity=<pseudonym> 
.Nm mixminion Cm inspect-surbs Ar <filename> 
.Sh DESCRIPTION
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.
.Pp
Aside from sending anonymous messages mixminion allows the creation and
use of 
.Em single use reply blocks (SURBs)
to also receive anonymous messages. See the section on 
SURBs to find out how to generate them. For the moment you will need to 
include a SURB addressed back to your email address by hand in the anonymous 
message you send. 
.Pp
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.
.Pp
.Em 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.
.Pp
The 
.Nm mixminion Cm send 
and 
.Nm mixminion Cm queue
commands:
.Bl -tag
.It Fl D Ar yes|no
Reloading or not of the server list. 
The default is to reload the list once per day, the first time the program 
is used after midnight GMT. To reload the list without sending a message type 
.Nm mixminion Cm send Fl D Ar yes
or
.Nm mixminion Cm update-servers
on the command line.
.It Fl H Ar <number-of-hops> 
The number of hops the message should be relayed.
You can change the default by editing ~/.mixminionrc .
.It Fl i Ar <filename-to-send>
File containing the message to be sent. If this is not specified 
or is the default is to read from stdin.
.It Fl t Ar <email-address> | Ar drop
The email address of the final recipient, or 
.Ar drop
if the message is intended to be a dummy and dropped by 
the last mix in the chain.
.It Fl R Ar <reply-block-filename>
Specifies that the final recipient of the message is the reply block 
contained in the specified file.
.It Fl P Ar <path>
The argument 
.Ar <path> 
must be a comma separated list of either:
.Bl -enum -compact           
.It 
Server nicknames as given by 'list-servers'
.It 
Paths to files containing server descriptors [more info below]
.El
.Pp   
For example, to send a message through the servers Foo, Bar, Baz, and
Quux, you would type "-P Foo,Bar,Baz,Quux."
.Pp
To specify a randomly chosen server, you can include a question mark,
like this:
.Bl -item -compact
.It
.Fl P Ar 'Foo,?,Bar,?'     
[Foo, a random server, Bar, and another random server]
.El
.Pp
You can specify a sequence of N random servers like this:
.Bl -item -compact
.It
.Fl P Ar 'Foo,*3,Bar'      
[Foo, three random servers, then Bar.]
.El
.Pp
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:
.Bl -item -compact
.It 
.Fl P Ar 'Foo,*'           
[Path that starts with Foo]
.It 
.Fl P Ar '*,Foo'           
[Path that ends with Foo]
.It 
.Fl P Ar 'Foo,Bar,*,Quux'  
[Path that starts with Foo and Bar, and ends with Quux]
.El
.Pp      
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:
.Bl -item -compact
.It 
.Fl P Ar 'Foo,Bar:Baz,Quux'    
[Swap headers at server Bar]
.It 
.Ar --swap-at=<n>            
[Swap headers at the n'th server]
.El
.It Ar --no-queue
Prevents messages from being queued if the transmission fails.
.It Ar --swap-at=<n>
Swap headers at the n'th server.
.El
.Pp
While
.Nm mixminion Cm send 
immediately sends the message specified, 
.Nm mixminion Cm queue
queues messages for later transmission. The command options for 
.Nm mixminion Cm flush
that transmits the messages waiting in the queue are:
.Bl -tag
.It Fl n Ar <no-of-messages>
To attempt to deliver no more than n messages. The default is to 
attempt to send all messages waiting in the queue.
.El
.Pp
The command
.Nm mixminion Ar list-servers
prints the list of all known servers, while
.Nm mixminion Ar update-servers
updates the list of servers by contacting the mixminion directory server.
.Pp
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 
.Nm mixminion Ar decode
command extracts the original text from either kind of message as best it can.
Its command line options are:
.Bl -tag
.It Fl i Ar <input-file>
The message to be decoded.
.It Fl o Ar <output-file>
The output file. The default is stdout.
.El
.Pp
The 
.Nm mixminion Ar generate-surb
command is used to manage single use reply blocks (SURBs):
.Bl -tag
.It Fl b
Writes the SURB in binary format.
.It Fl H Ar <number-of-hops> 
The number of hops as for the 
.Nm mixminion Cm send
command.
.It Fl n Ar <no-of-SURBs>
The number of SURBs to be generated.
.It Fl P Ar <path>
The path as for the
.Nm mixminion Cm send
command.
.It Fl t Ar <your-address>
The final address of the SURB. This should be your address and defaults to 
the "SURBAddress" field in ~/.mixminionrc.
.It Fl o Ar <filename>
The file in which to write the SURBs.
.It Ar --lifetime=<days>
Number of days SURB is valid for.
.It Ar --identity=<pseudonym>
The pseudonym this SURB is attached to.
.El
.Em 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.
.Pp
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.
.Pp
To inspect the reply blocks in a file, you can run:
.Nm mixminion Cm inspect-surbs Ar <filename>
.Sh ENVIRONMENT
The variable
.Ev http_proxy is used by mixminion to specify the address to use, 
in order to proxy HTTP connections. Its usage is
.Li export Ev http_proxy=http://proxy:3128/
.Sh FILES
The file 
.Pa ~/.mixminionrc 
contains configuration parameters for the mixminion client. 
.Sh EXAMPLES
To send a message:
.Bl -item -compact
.It 
.Nm mixminion Cm send Fl t Ar <email address> Fl i Ar <filename to send>
.It 
.Nm mixminion Cm send Fl t Ar <email address>            
to read from stdin.
.It 
.Nm mixminion Cm send Fl t Ar <email address> Fl i Ar -       
also reads from stdin.
.El
.Sh SEE ALSO
The instruction on how to use 
.Nm mixminion 
as a mix server are contained in the 
.Pa README.TXT
file, in the root directory of the mixminion distribution.
.Pp
More information about how mixminion works can be found in the technical paper
.Rs
.%A George Danezis
.%A Roger Dingledine
.%A Nick Mathewson
.%B Proceedings of the 2003 IEEE Symposium on Security and Privacy
.%D May 2003
.%T Mixminion: Design of a Type III Anonymous Remailer Protocol
.%O http://mixminion.net/minion-design.pdf
.Re
.Pp
The website of the mixminion project with up to date releases, and the 
client and server specifications is at 
.Em http://mixminion.net
.Sh AUTHORS
Original text by
.An Nick Mathewson Aq nickm@freehaven.net
.Pp
Man page by 
.An George Danezis Aq George.Danezis@cl.cam.ac.uk
.Sh BUGS
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:
.Bl -bullet -compact
.It
What command you were running
.It        
The complete error you got, including stack trace (if any)
.El
If your error occurred on a running server, please make a copy of your
log--it might be helpful.