--- /dev/null
+.\" -*-nroff-*-
+.\".
+.\" Manual for the malicious proxy
+.\"
+.\" (c) 2008 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of Trivial IP Encryption (TrIPE).
+.\"
+.\" TrIPE is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" TrIPE is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with TrIPE; if not, write to the Free Software Foundation,
+.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.
+.\"--------------------------------------------------------------------------
+.so ../defs.man.in \" @@@PRE@@@
+.
+.\"--------------------------------------------------------------------------
+.TH tripe-mitm 8 "14 October 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+.
+tripe-mitm \- malicious proxy for TrIPE
+.
+.\"--------------------------------------------------------------------------
+.SH "SYNOPSIS"
+.
+.B tripe-mitm
+.RB [ \-k
+.IR keyring ]
+.IR directive ...
+.
+.\"--------------------------------------------------------------------------
+.SH "DESCRIPTION"
+.
+The
+.B tripe-mitm
+program is a
+.I malicious
+proxy for
+.BR tripe (8).
+Its purpose is to test the robustness of the TrIPE implementation, by
+deliberately introducing communication problems such as dropped,
+repeated or corrupted packets.
+.PP
+The command line contains a sequence of directives, each of which has
+the form
+.IB command : arg \c
+.BR : ...
+A list of directives can be stored in a file, one per line, and included
+using the
+.B include
+command.
+.SS "Command line options"
+The following options are recognized.
+.TP
+.B "\-h, \-\-help"
+Write a very brief help message to standard output, and exit
+successfully.
+.TP
+.B "\-v, \-\-version"
+Write the program's version number to standard output, and exit
+successfully.
+.TP
+.B "\-u, \-\-usage"
+Write a usage message to standard output, and exit successfully.
+.TP
+.BI "\-k, \-\-keyring=" file
+Read keys from
+.IR file .
+The default keyring file is
+.B keyring.pub
+in the current directory.
+.SS "Directives"
+A directive is ignored if it is empty, or if its first character is a
+.RB ` # '.
+The following directives are recognized.
+.TP
+.BI peer: name : local-port : remote-addr : remote-port
+Register a peer. We listen for packets on
+.I local-port
+and send them on to
+.I remote-port
+on
+.IR remote-addr .
+The
+.I name
+identifies the public key which that peer uses to authenticate itself.
+Both
+.I local-port
+and
+.I remote-port
+must be numbers;
+.I remote-addr
+may be a hostname or an IP address in dotted-quad format. Exactly two
+.B peer
+directives must be present. The one first registered is the
+.I left
+peer; the second is the
+.I right
+peer. The two peers must use
+.I different
+local ports.
+.TP
+.BI include: file
+Read more directives from
+.IR file .
+Directives should appear one per line. Empty lines and comments are
+permitted. An included file may include other files. It may even
+include itself, though this is just a good way to tie the program in
+knots until it runs out of file handles.
+.TP
+.BI filt: filter : args : \fR...
+Apply a given filter to packets received from either peer. See the
+description of filters below for more details.
+.TP
+.BI lfilt: filter : args : \fR...
+Apply a given filter to packets received from the left peer.
+.TP
+.BI lfilt: filter : args :\fR...
+Apply a given filter to packets received from the right peer.
+.TP
+.BI next: tag :\fR...
+Begin the next branch of the first fork filter node named
+.I tag
+in each filter chain. See below for more about filter chains.
+.TP
+.BI flood\fR[\fP: type : millis : size\fR]
+Flood both peers with random packets. If
+.I type
+is given, it is interpreted as a TrIPE message type code in hexadecimal,
+and the messages sent will have this type; otherwise the messages have
+random type. Messages are sent approximately once every
+.I millis
+milliseconds; the default interval is 10 milliseconds. The messages
+will be
+.I size
+bytes long each; the default size is 128 bytes.
+.TP
+.BI lflood\fR[\fP: type : millis : size\fR]
+As for
+.B flood
+above, but only flood the left peer.
+.TP
+.BI rflood\fR[\fP: type : millis : size\fR]
+As for
+.B flood
+above, but only flood the right peer.
+.SS "Filters"
+Each peer has a filter chain associated with it. Messages received from
+that peer get processed by the filter chain. Only if the filter chain
+decides to send the message is it actually sent. (See the
+.B send
+filter, described below.)
+Messages generated by a
+.B flood
+directive (above) are also processed by a filter chain, just like normal
+messages. The filters in a chain are processed in the order they were
+added.
+.PP
+The filters currently supported are as follows.
+.TP
+.B send
+Send the message to the destination peer. This is the
+.I only
+way messages are sent. If your filter chains don't end in a
+.B send
+filter then nothing will get through!
+.TP
+.BI fork: tag
+Introduce a fork in a filter chain. A fork may have multiple branches
+leading off it. The end of a branch is indicated by a
+.B next
+directive which names the fork
+.IR tag :
+further filters added to the chain form a new parallel branch of that
+fork. (If there are two forks with the same tag on a peer's chain, then
+only the earliest is matched. This isn't helpful behaviour.)
+.TP
+.BI delay: qlen \fR[\fP: millis : p-replay\fR]
+Delay, replay and reorder messages. A queue of
+.I qlen
+messages is maintained. If the queue fills up, or every
+.I millis
+milliseconds (default 100), a message from the queue is chosen at random
+and transmitted (i.e., processed by the rest of the filter chain). If
+the message was transmitted due to a timer (rather than lack of space in
+the queue) then it has a 1 in
+.I p-replay
+probability (default 1 in 20) of being left in the queue.
+.TP
+.BI corrupt\fR[\fP: p-corrupt\fR]
+Randomly corrupt messages. Each message has a 1 in
+.I p-corrupt
+probability (default 1 in 5) of being corrupted by having a
+randomly chosen byte mangled. The message might be further corrupted,
+again with a 1 in
+.I p-corrupt
+probability.
+.
+.\"--------------------------------------------------------------------------
+.SH "BUGS"
+.
+The parser is currently very primitive, and error handling is rather
+poor. There are lots of pointless restrictions which wouldn't take very
+long to fix. The program generally lacks polish. The program doesn't
+understand the TrIPE protocol to a sufficient extent to really attack it
+properly.
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR tripe (8).
+.
+.\"--------------------------------------------------------------------------
+.SH "AUTHOR"
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / tripe / blobdiff