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 A list of directives can be stored in a file, one per line, and included
  62 using the
  63 .B include
  64 command.
  65 .SS "Command line options"
  66 The following options are recognized.
  67 .TP
  68 .B "\-h, \-\-help"
  69 Write a very brief help message to standard output, and exit
  70 successfully.
  71 .TP
  72 .B "\-v, \-\-version"
  73 Write the program's version number to standard output, and exit
  74 successfully.
  75 .TP
  76 .B "\-u, \-\-usage"
  77 Write a usage message to standard output, and exit successfully.
  78 .TP
  79 .BI "\-k, \-\-keyring=" file
  80 Read keys from
  81 .IR file .
  82 The default keyring file is
  83 .B keyring.pub
  84 in the current directory.
  85 .SS "Directives"
  86 A directive is ignored if it is empty, or if its first character is a
  87 .RB ` # '.
  88 The following directives are recognized.
  89 .TP
  90 .BI peer: name : local-port : remote-addr : remote-port
  91 Register a peer.  We listen for packets on
  92 .I local-port
  93 and send them on to
  94 .I remote-port
  95 on
  96 .IR remote-addr .
  97 The
  98 .I name
  99 identifies the public key which that peer uses to authenticate itself.
 100 Both
 101 .I local-port
 102 and
 103 .I remote-port
 104 must be numbers;
 105 .I remote-addr
 106 may be a hostname or an IP address in dotted-quad format.  Exactly two
 107 .B peer
 108 directives must be present.  The one first registered is the
 109 .I left
 110 peer; the second is the
 111 .I right
 112 peer.  The two peers must use
 113 .I different
 114 local ports.
 115 .TP
 116 .BI include: file
 117 Read more directives from
 118 .IR file .
 119 Directives should appear one per line.  Empty lines and comments are
 120 permitted.  An included file may include other files.  It may even
 121 include itself, though this is just a good way to tie the program in
 122 knots until it runs out of file handles.
 123 .TP
 124 .BI filt: filter : args : \fR...
 125 Apply a given filter to packets received from either peer.  See the
 126 description of filters below for more details.
 127 .TP
 128 .BI lfilt: filter : args : \fR...
 129 Apply a given filter to packets received from the left peer.
 130 .TP
 131 .BI rfilt: filter : args :\fR...
 132 Apply a given filter to packets received from the right peer.
 133 .TP
 134 .BI next: tag :\fR...
 135 Begin the next branch of the first fork filter node named
 136 .I tag
 137 in each filter chain.  See below for more about filter chains.
 138 .TP
 139 .BI flood\fR[\fP: type : millis : size\fR]
 140 Flood both peers with random packets.  If
 141 .I type
 142 is given, it is interpreted as a TrIPE message type code in hexadecimal,
 143 and the messages sent will have this type; otherwise the messages have
 144 random type.  Messages are sent approximately once every
 145 .I millis
 146 milliseconds; the default interval is 10 milliseconds.  The messages
 147 will be
 148 .I size
 149 bytes long each; the default size is 128 bytes.
 150 .TP
 151 .BI lflood\fR[\fP: type : millis : size\fR]
 152 As for
 153 .B flood
 154 above, but only flood the left peer.
 155 .TP
 156 .BI rflood\fR[\fP: type : millis : size\fR]
 157 As for
 158 .B flood
 159 above, but only flood the right peer.
 160 .SS "Filters"
 161 Each peer has a filter chain associated with it.  Messages received from
 162 that peer get processed by the filter chain.  Only if the filter chain
 163 decides to send the message is it actually sent.  (See the
 164 .B send
 165 filter, described below.)
 166 Messages generated by a
 167 .B flood
 168 directive (above) are also processed by a filter chain, just like normal
 169 messages.  The filters in a chain are processed in the order they were
 170 added.
 171 .PP
 172 The filters currently supported are as follows.
 173 .TP
 174 .B send
 175 Send the message to the destination peer.  This is the
 176 .I only
 177 way messages are sent.  If your filter chains don't end in a
 178 .B send
 179 filter then nothing will get through!
 180 .TP
 181 .BI fork: tag
 182 Introduce a fork in a filter chain.  A fork may have multiple branches
 183 leading off it.  The end of a branch is indicated by a
 184 .B next
 185 directive which names the fork
 186 .IR tag :
 187 further filters added to the chain form a new parallel branch of that
 188 fork.  (If there are two forks with the same tag on a peer's chain, then
 189 only the earliest is matched.  This isn't helpful behaviour.)
 190 .TP
 191 .BI delay: qlen \fR[\fP: millis : p-replay\fR]
 192 Delay, replay and reorder messages.  A queue of
 193 .I qlen
 194 messages is maintained.  If the queue fills up, or every
 195 .I millis
 196 milliseconds (default 100), a message from the queue is chosen at random
 197 and transmitted (i.e., processed by the rest of the filter chain).  If
 198 the message was transmitted due to a timer (rather than lack of space in
 199 the queue) then it has a 1 in
 200 .I p-replay
 201 probability (default 1 in 20) of being left in the queue.
 202 .TP
 203 .BI drop\fR[\fP: p-drop\fR]
 204 Randomly drop messages.  Each message has a 1 in
 205 .I p-drop
 206 probability (default 1 in 5) of being discarded.
 207 .TP
 208 .BI corrupt\fR[\fP: p-corrupt\fR]
 209 Randomly corrupt messages.  Each message has a 1 in
 210 .I p-corrupt
 211 probability (default 1 in 5) of being corrupted by having a
 212 randomly chosen byte mangled.  The message might be further corrupted,
 213 again with a 1 in
 214 .I p-corrupt
 215 probability.
 216 .
 217 .\"--------------------------------------------------------------------------
 218 .SH "BUGS"
 219 .
 220 The parser is currently very primitive, and error handling is rather
 221 poor.  There are lots of pointless restrictions which wouldn't take very
 222 long to fix.  The program generally lacks polish.  The program doesn't
 223 understand the TrIPE protocol to a sufficient extent to really attack it
 224 properly.
 225 .
 226 .\"--------------------------------------------------------------------------
 227 .SH "SEE ALSO"
 228 .
 229 .BR tripe (8).
 230 .
 231 .\"--------------------------------------------------------------------------
 232 .SH "AUTHOR"
 233 .
 234 Mark Wooding, <mdw@distorted.org.uk>
 235 .
 236 .\"----- That's all, folks --------------------------------------------------