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