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