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