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