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