chiark / gitweb /
Document the evil proxy.
authormdw <mdw>
Wed, 15 Oct 2003 09:30:29 +0000 (09:30 +0000)
committermdw <mdw>
Wed, 15 Oct 2003 09:30:29 +0000 (09:30 +0000)
doc/Makefile.am
doc/tripe-mitm.8 [new file with mode: 0644]

index 40bb6af..2d53380 100644 (file)
@@ -1,6 +1,6 @@
 ## -*-makefile-*-
 ##
-## $Id: Makefile.am,v 1.3 2003/04/23 13:53:20 mdw Exp $
+## $Id: Makefile.am,v 1.4 2003/10/15 09:30:29 mdw Exp $
 ##
 ## Makefile for TrIPE documentation
 ##
@@ -28,6 +28,9 @@
 ##----- Revision history ----------------------------------------------------
 ##
 ## $Log: Makefile.am,v $
+## Revision 1.4  2003/10/15 09:30:29  mdw
+## Document the evil proxy.
+##
 ## Revision 1.3  2003/04/23 13:53:20  mdw
 ## New manpage for pkstream.
 ##
@@ -40,7 +43,7 @@
 
 AUTOMAKE_OPTIONS = foreign
 
-man_MANS = tripe.8 tripectl.1 tripe-admin.5 pkstream.1
+man_MANS = tripe.8 tripectl.1 tripe-admin.5 pkstream.1 tripe-mitm.8
 EXTRA_DIST = $(man_MANS)
 
 ##----- That's all, folks ---------------------------------------------------
diff --git a/doc/tripe-mitm.8 b/doc/tripe-mitm.8
new file mode 100644 (file)
index 0000000..7c79d8a
--- /dev/null
@@ -0,0 +1,214 @@
+.\" -*-nroff-*-
+.\".
+.de hP
+.IP
+\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
+..
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.ie t \{\
+.  ds o \(bu
+.  ds ss \s8\u
+.  ds se \d\s0
+.  if \n(.g \{\
+.    fam P
+.  \}
+.\}
+.el \{\
+.  ds o o
+.  ds ss ^
+.  ds se
+.\}
+.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
+.B 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.  The help message hasn't been written.  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@nsict.org>