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