chiark - git - mdw - tripe/blob - doc/tripe-mitm.8

   1 .\" -*-nroff-*-
   2 .\".
   3 .de hP
   4 .IP
   5 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
   6 ..
   7 .de VS
   8 .sp 1
   9 .RS
  10 .nf
  11 .ft B
  12 ..
  13 .de VE
  14 .ft R
  15 .fi
  16 .RE
  17 .sp 1
  18 ..
  19 .ie t \{\
  20 .  ds o \(bu
  21 .  ds ss \s8\u
  22 .  ds se \d\s0
  23 .  if \n(.g \{\
  24 .    fam P
  25 .  \}
  26 .\}
  27 .el \{\
  28 .  ds o o
  29 .  ds ss ^
  30 .  ds se
  31 .\}
  32 .TH tripe-mitm 8 "14 October 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  33 .SH "NAME"
  34 tripe-mitm \- malicious proxy for TrIPE
  35 .SH "SYNOPSIS"
  36 .B tripe-mitm
  37 .RB [ \-k
  38 .IR keyring ]
  39 .IR directive ...
  40 .SH "DESCRIPTION"
  41 The
  42 .B tripe-mitm
  43 program is a
  44 .I malicious
  45 proxy for
  46 .BR tripe (8).
  47 Its purpose is to test the robustness of the TrIPE implementation, by
  48 deliberately introducing communication problems such as dropped,
  49 repeated or corrupted packets.
  50 .PP
  51 The command line contains a sequence of directives, each of which has
  52 the form
  53 .IB command : arg \c
  54 .BR : ...
  55 A list of directives can be stored in a file, one per line, and included
  56 using the
  57 .B include
  58 command.
  59 .SS "Command line options"
  60 The following options are recognized.
  61 .TP
  62 .B "\-h, \-\-help"
  63 Write a very brief help message to standard output, and exit
  64 successfully.
  65 .TP
  66 .B "\-v, \-\-version"
  67 Write the program's version number to standard output, and exit
  68 successfully.
  69 .TP
  70 .B "\-u, \-\-usage"
  71 Write a usage message to standard output, and exit successfully.
  72 .TP
  73 .BI "\-k, \-\-keyring=" file
  74 Read keys from
  75 .IR file .
  76 The default keyring file is
  77 .B keyring.pub
  78 in the current directory.
  79 .SS "Directives"
  80 A directive is ignored if it is empty, or if its first character is a
  81 .RB ` # '.
  82 The following directives are recognized.
  83 .TP
  84 .BI peer: name : local-port : remote-addr : remote-port
  85 Register a peer.  We listen for packets on
  86 .I local-port
  87 and send them on to
  88 .I remote-port
  89 on
  90 .IR remote-addr .
  91 The
  92 .I name
  93 identifies the public key which that peer uses to authenticate itself.
  94 Both
  95 .I local-port
  96 and
  97 .I remote-port
  98 must be numbers;
  99 .I remote-addr
 100 may be a hostname or an IP address in dotted-quad format.  Exactly two
 101 .B peer
 102 directives must be present.  The one first registered is the
 103 .I left
 104 peer; the second is the
 105 .I right
 106 peer.  The two peers must use
 107 .I different
 108 local ports.
 109 .TP
 110 .BI include: file
 111 Read more directives from
 112 .IR file .
 113 Directives should appear one per line.  Empty lines and comments are
 114 permitted.  An included file may include other files.  It may even
 115 include itself, though this is just a good way to tie the program in
 116 knots until it runs out of file handles.
 117 .TP
 118 .BI filt: filter : args : \fR...
 119 Apply a given filter to packets received from either peer.  See the
 120 description of filters below for more details.
 121 .TP
 122 .BI lfilt: filter : args : \fR...
 123 Apply a given filter to packets received from the left peer.
 124 .TP
 125 .BI lfilt: filter : args :\fR...
 126 Apply a given filter to packets received from the right peer.
 127 .TP
 128 .BI next: tag :\fR...
 129 Begin the next branch of the first fork filter node named
 130 .I tag
 131 in each filter chain.  See below for more about filter chains.
 132 .TP
 133 .BI flood\fR[\fP: type : millis : size\fR]
 134 Flood both peers with random packets.  If
 135 .I type
 136 is given, it is interpreted as a TrIPE message type code in hexadecimal,
 137 and the messages sent will have this type; otherwise the messages have
 138 random type.  Messages are sent approximately once every
 139 .I millis
 140 milliseconds; the default interval is 10 milliseconds.  The messages
 141 will be
 142 .I size
 143 bytes long each; the default size is 128 bytes.
 144 .TP
 145 .BI lflood\fR[\fP: type : millis : size\fR]
 146 As for
 147 .B flood
 148 above, but only flood the left peer.
 149 .TP
 150 .BI rflood\fR[\fP: type : millis : size\fR]
 151 As for
 152 .B flood
 153 above, but only flood the right peer.
 154 .SS "Filters"
 155 Each peer has a filter chain associated with it.  Messages received from
 156 that peer get processed by the filter chain.  Only if the filter chain
 157 decides to send the message is it actually sent.  (See the
 158 .B send
 159 filter, described below.)
 160 Messages generated by a
 161 .B flood
 162 directive (above) are also processed by a filter chain, just like normal
 163 messages.  The filters in a chain are processed in the order they were
 164 added.
 165 .PP
 166 The filters currently supported are as follows.
 167 .TP
 168 .B send
 169 Send the message to the destination peer.  This is the
 170 .I only
 171 way messages are sent.  If your filter chains don't end in a
 172 .B send
 173 filter then nothing will get through!
 174 .TP
 175 .BI fork: tag
 176 Introduce a fork in a filter chain.  A fork may have multiple branches
 177 leading off it.  The end of a branch is indicated by a
 178 .B next
 179 directive which names the fork
 180 .IR tag :
 181 further filters added to the chain form a new parallel branch of that
 182 fork.  (If there are two forks with the same tag on a peer's chain, then
 183 only the earliest is matched.  This isn't helpful behaviour.)
 184 .TP
 185 .BI delay: qlen \fR[\fP: millis : p-replay\fR]
 186 Delay, replay and reorder messages.  A queue of
 187 .I qlen
 188 messages is maintained.  If the queue fills up, or every
 189 .I millis
 190 milliseconds (default 100), a message from the queue is chosen at random
 191 and transmitted (i.e., processed by the rest of the filter chain).  If
 192 the message was transmitted due to a timer (rather than lack of space in
 193 the queue) then it has a 1 in
 194 .I p-replay
 195 probability (default 1 in 20) of being left in the queue.
 196 .TP
 197 .BI corrupt\fR[\fP: p-corrupt\fR]
 198 Randomly corrupt messages.  Each message has a 1 in
 199 .I p-corrupt
 200 probability (default 1 in 5) of being corrupted by having a
 201 randomly chosen byte mangled.  The message might be further corrupted,
 202 again with a 1 in
 203 .I p-corrupt
 204 probability.
 205 .SH "BUGS"
 206 The parser is currently very primitive, and error handling is rather
 207 poor.  There are lots of pointless restrictions which wouldn't take very
 208 long to fix.  The program generally lacks polish.  The program doesn't
 209 understand the TrIPE protocol to a sufficient extent to really attack it
 210 properly.
 211 .SH "SEE ALSO"
 212 .BR tripe (8).
 213 .SH "AUTHOR"
 214 Mark Wooding, <mdw@distorted.org.uk>