mdw@git.distorted.org.uk Git - tripe/blob - proxy/tripe-mitm.8.in

   1 .\" -*-nroff-*-
   2 .\".
   3 .\" Manual for the malicious proxy
   4 .\"
   5 .\" (c) 2008 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of Trivial IP Encryption (TrIPE).
  11 .\"
  12 .\" TrIPE is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU General Public License as published by the Free
  14 .\" Software Foundation; either version 3 of the License, or (at your
  15 .\" option) any later version.
  16 .\"
  17 .\" TrIPE is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20 .\" for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public License
  23 .\" along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
  24 .
  25 .\"--------------------------------------------------------------------------
  26 .so ../common/defs.man \" @@@PRE@@@
  27 .
  28 .\"--------------------------------------------------------------------------
  29 .TH tripe-mitm 8tripe "14 October 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  30 .
  31 .\"--------------------------------------------------------------------------
  32 .SH "NAME"
  33 .
  34 tripe-mitm \- malicious proxy for TrIPE
  35 .
  36 .\"--------------------------------------------------------------------------
  37 .SH "SYNOPSIS"
  38 .
  39 .B tripe-mitm
  40 .RB [ \-k
  41 .IR keyring ]
  42 .IR directive ...
  43 .
  44 .\"--------------------------------------------------------------------------
  45 .SH "DESCRIPTION"
  46 .
  47 The
  48 .B tripe-mitm
  49 program is a
  50 .I malicious
  51 proxy for
  52 .BR tripe (8).
  53 Its purpose is to test the robustness of the TrIPE implementation, by
  54 deliberately introducing communication problems such as dropped,
  55 repeated or corrupted packets.
  56 .PP
  57 The command line contains a sequence of directives, each of which has
  58 the form
  59 .IB command : arg \c
  60 .BR : ...
  61 (The delimiter character can be changed using the
  62 .B \-d
  63 command-line option.)
  64 A list of directives can be stored in a file, one per line, and included
  65 using the
  66 .B include
  67 command.
  68 .SS "Command line options"
  69 The following options are recognized.
  70 .TP
  71 .B "\-h, \-\-help"
  72 Write a very brief help message to standard output, and exit
  73 successfully.
  74 .TP
  75 .B "\-v, \-\-version"
  76 Write the program's version number to standard output, and exit
  77 successfully.
  78 .TP
  79 .B "\-u, \-\-usage"
  80 Write a usage message to standard output, and exit successfully.
  81 .TP
  82 .BI "\-d, \-\-delimiter=" char
  83 Use
  84 .I char
  85 as the delimiter to separate argument names in directives, rather than
  86 .RB ` : '.
  87 .TP
  88 .BI "\-k, \-\-keyring=" file
  89 Read keys from
  90 .IR file .
  91 The default keyring file is
  92 .B keyring.pub
  93 in the current directory.
  94 .SS "Directives"
  95 A directive is ignored if it is empty, or if its first character is a
  96 .RB ` # '.
  97 Directives consist of a name followed by zero or more arguments,
  98 separated by a delimiter character.  The default delimiter is
  99 .RB ` : ',
 100 but this can be overridden using the
 101 .B \-d
 102 option (see above); this manual uses
 103 .RB ` : '
 104 consistently as the delimiter character.
 105 The following directives are recognized.
 106 .TP
 107 .BI peer: name : local-port : remote-addr : remote-port
 108 Register a peer.  We listen for packets on
 109 .I local-port
 110 and send them on to
 111 .I remote-port
 112 on
 113 .IR remote-addr .
 114 The
 115 .I name
 116 identifies the public key which that peer uses to authenticate itself.
 117 (Currently this is checked, but not used for anything.)
 118 Both
 119 .I local-port
 120 and
 121 .I remote-port
 122 may be numbers or UDP service names;
 123 .I remote-addr
 124 may be a hostname, an IPv4 address in dotted-quad format, or an IPv6
 125 address in hex-and-colons format (this last obviously requires selecting
 126 a different delimeter character).  Additionally,
 127 .I local-port
 128 may be a string of the form
 129 .BI ? file
 130 to get the kernel to allocate an unused port number, and then write the
 131 port to the named
 132 .IR file .
 133 Exactly two
 134 .B peer
 135 directives must be present.  The one first registered is the
 136 .I left
 137 peer; the second is the
 138 .I right
 139 peer.  The two peers must use
 140 .I different
 141 local ports.
 142 .TP
 143 .BI peer4: name : local-port : remote-addr : remote-port
 144 As for
 145 .I peer
 146 (see above), but force the use of IPv4.
 147 .TP
 148 .BI peer6: name : local-port : remote-addr : remote-port
 149 As for
 150 .I peer
 151 (see above), but force the use of IPv6.
 152 .TP
 153 .BI include: file
 154 Read more directives from
 155 .IR file .
 156 Directives should appear one per line.  Empty lines and comments are
 157 permitted.  An included file may include other files.  It may even
 158 include itself, though this is just a good way to tie the program in
 159 knots until it runs out of file handles.
 160 .TP
 161 .BI filt: filter : args : \fR...
 162 Apply a given filter to packets received from either peer.  See the
 163 description of filters below for more details.
 164 .TP
 165 .BI lfilt: filter : args : \fR...
 166 Apply a given filter to packets received from the left peer.
 167 .TP
 168 .BI rfilt: filter : args :\fR...
 169 Apply a given filter to packets received from the right peer.
 170 .TP
 171 .BI next: tag :\fR...
 172 Begin the next branch of the first fork filter node named
 173 .I tag
 174 in each filter chain.  See below for more about filter chains.
 175 .TP
 176 .BI flood\fR[\fP: type : millis : size\fR]
 177 Flood both peers with random packets.  If
 178 .I type
 179 is given, it is interpreted as a TrIPE message type code in hexadecimal,
 180 and the messages sent will have this type; otherwise the messages have
 181 random type.  Messages are sent approximately once every
 182 .I millis
 183 milliseconds; the default interval is 10 milliseconds.  The messages
 184 will be
 185 .I size
 186 bytes long each; the default size is 128 bytes.
 187 .TP
 188 .BI lflood\fR[\fP: type : millis : size\fR]
 189 As for
 190 .B flood
 191 above, but only flood the left peer.
 192 .TP
 193 .BI rflood\fR[\fP: type : millis : size\fR]
 194 As for
 195 .B flood
 196 above, but only flood the right peer.
 197 .SS "Filters"
 198 Each peer has a filter chain associated with it.  Messages received from
 199 that peer get processed by the filter chain.  Only if the filter chain
 200 decides to send the message is it actually sent.  (See the
 201 .B send
 202 filter, described below.)
 203 Messages generated by a
 204 .B flood
 205 directive (above) are also processed by a filter chain, just like normal
 206 messages.  The filters in a chain are processed in the order they were
 207 added.
 208 .PP
 209 The filters currently supported are as follows.
 210 .TP
 211 .B send
 212 Send the message to the destination peer.  This is the
 213 .I only
 214 way messages are sent.  If your filter chains don't end in a
 215 .B send
 216 filter then nothing will get through!
 217 .TP
 218 .BI fork: tag
 219 Introduce a fork in a filter chain.  A fork may have multiple branches
 220 leading off it.  The end of a branch is indicated by a
 221 .B next
 222 directive which names the fork
 223 .IR tag :
 224 further filters added to the chain form a new parallel branch of that
 225 fork.  (If there are two forks with the same tag on a peer's chain, then
 226 only the earliest is matched.  This isn't helpful behaviour.)
 227 .TP
 228 .BI delay: qlen \fR[\fP: millis : p-replay\fR]
 229 Delay, replay and reorder messages.  A queue of
 230 .I qlen
 231 messages is maintained.  If the queue fills up, or every
 232 .I millis
 233 milliseconds (default 100), a message from the queue is chosen at random
 234 and transmitted (i.e., processed by the rest of the filter chain).  If
 235 the message was transmitted due to a timer (rather than lack of space in
 236 the queue) then it has a 1 in
 237 .I p-replay
 238 probability (default 1 in 20) of being left in the queue.
 239 .TP
 240 .BI drop\fR[\fP: p-drop\fR]
 241 Randomly drop messages.  Each message has a 1 in
 242 .I p-drop
 243 probability (default 1 in 5) of being discarded.
 244 .TP
 245 .BI corrupt\fR[\fP: p-corrupt\fR]
 246 Randomly corrupt messages.  Each message has a 1 in
 247 .I p-corrupt
 248 probability (default 1 in 5) of being corrupted by having a
 249 randomly chosen byte mangled.  The message might be further corrupted,
 250 again with a 1 in
 251 .I p-corrupt
 252 probability.
 253 .
 254 .\"--------------------------------------------------------------------------
 255 .SH "BUGS"
 256 .
 257 The parser is currently very primitive, and error handling is rather
 258 poor.  There are lots of pointless restrictions which wouldn't take very
 259 long to fix.  The program generally lacks polish.  The program doesn't
 260 understand the TrIPE protocol to a sufficient extent to really attack it
 261 properly.
 262 .
 263 .\"--------------------------------------------------------------------------
 264 .SH "SEE ALSO"
 265 .
 266 .BR tripe (8).
 267 .
 268 .\"--------------------------------------------------------------------------
 269 .SH "AUTHOR"
 270 .
 271 Mark Wooding, <mdw@distorted.org.uk>
 272 .
 273 .\"----- That's all, folks --------------------------------------------------