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 | .\" | |
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 | 35 | tripe-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 | 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 | |
e04c2d50 | 105 | must be numbers; |
6b3d271a | 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 | |
2d752320 | 135 | .BI next: tag :\fR... |
6b3d271a | 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. | |
e04c2d50 | 139 | .TP |
6b3d271a | 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 | |
a2e06ed5 MW |
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 | |
6b3d271a | 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. | |
fc916a09 MW |
217 | . |
218 | .\"-------------------------------------------------------------------------- | |
6b3d271a | 219 | .SH "BUGS" |
fc916a09 | 220 | . |
6b3d271a | 221 | The parser is currently very primitive, and error handling is rather |
808702d2 | 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. | |
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 | 235 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
236 | . |
237 | .\"----- That's all, folks -------------------------------------------------- |